Widgets

Browse Catalog

Flex widgets are "pre-fabricated" musical interface elements that you can add to your web pages at your own leisure and in your own specific locations on the page. And since they are added directly into the flow of your page, you are also free to theme or re-style them with your own css.


Are you a designer? You can create your own custom widgets and distribute them for other people to use.

Acquiring & Using Widgets

In order to use a widget on a page, a flex app must first be deployed to that page. For more information on deployment options, have a look at our quick start guide.

Although there are a few basic widgets that are built-in to flex apps that you can use right out of the box, custom widgets typically have their own javascript file that you will need to add to your page before they will work. You can get new widgets from independent sources or by browsing our widget catalog.

Refer to the documentation for a specific widget to learn what (if any) script files you need to add to your page for the widget to work correctly. Depending on the widget, you may also need to add references to other resources also (such as css files).

You can include all the resources that a widget needs manually in your html source, or you can use the widget autoloader (in your flex store settings), to autoload flex widget scripts.

Note: To actually get a widget to appear on your webpage where you want, it's as simple as inserting a shortcode into your content (if you're using a cms plugin), inserting an html element with a custom attribute (if you're working directly with the html source), or using a jQuery method (if your working programmatically with javascript).

Display A Widget: The Shortcode Way

If you are using one of our cms plugins, you can insert widgets into your content using a shortcode.

Wordpress: More Info

[bbflex widget="widgetname" width="500" height="100" param3="value3"]

Drupal: More Info

[bbflex:widget="widgetname",width="500",height="100",param3="value3"]

Joomla: More Info

[bbflex:widget="widgetname",width="500",height="100",param3="value3"]

Display A Widget: The HTML Way

<div data-bbflex="widget:widgetname,width:500,height:100,param3:value3"></div>
Notice that the html element has the widget settings assigned to a special html attribute called "data-bbflex". The flex framework will look for any html elements on your page with this attribute and replace it with the associated widget based on the properties included in the attribute.

The value assigned to the "data-bbflex" in the example above is in basic notation. The parameter names (i.e "widget") are separated from the parameter values (i.e. "widgetname") by a colon. And each param:value pair is separated by a comma. This format is sufficient (and easier) to use in most cases. However, there may be circumstances where widgets may require more advanced parameter values that break the interpretation of this basic notation (such as if you needed to provide a comma as a parameter value). In such cases:

You can also use a JSON formatted string for the "data-bbflex" attribute to supply your widget parameters. Here is another way to create the widget demonstrated above:

<div data-bbflex='{ "widget" : "widgetname", "width" : "500", "height" : "100", "param3" : "value3" }'></div>

Note: When supplying the "data-bbflex" attribute as a JSON formatted string, you'll need to use the single quote ' to enclose the string because of the mandatory double quote characters included in the JSON formatted string. The JSON string needs to adhere to strict JSON syntax in order to be interpreted correctly.


Display A Widget: The jQuery Way

<div id="mywidget"></div>

<script type="text/javascript">
flexloader.execute(function($) {
  $("#mywidget").bbflex({ widget: 'widgetname', width: 500, height: 100, param3: 'value3' });
});
</script>
In the example above, we apply the flex widget settings to the <div id="mywidget"> html element using a jQuery method. You'll also notice that the command is wrapped in a function and executed with the flexloader.execute() method. We do this to ensure that the $ variable is referenced to the correct instance of jQuery, and that the flex app is loaded before the commands are issued.

Theme Prefixing

The flex framework adds a few basic css classes to every widget on your page by default. There are three primary classes that can be used to target your widgets with css.
  • flex-widget This class is assigned to the container element of every widget.
  • flex-widget-widgetname This class is assigned to the container, and varies depending on the widget name.
  • fw-theme-default This class is assigned to the container, and varies depending on the "theme" setting.

As mentioned, every widget that you add to your page includes a theme class which is controlled by the theme setting used when creating the widget. By default, if you do not specify a "theme" setting, the framework will use the default css prefix of fw-theme-default on the widget container.


Default Theming Example:
<div data-bbflex="widget:playbar"></div>
Will produce a widget with a container which looks like the following:
<div class="flex-widget flex-widget-playbar fw-theme-default"></div>

Custom Theming Example:
<div data-bbflex="widget:playbar,theme:customized"></div>
Will produce a widget with a container which looks like the following:
<div class="flex-widget flex-widget-playbar fw-theme-customized"></div>
And you can target elements in this widget specifically:
.flex-widget-playbar.fw-theme-customized {
  /* style rules to apply to the widget container itself */
}
.flex-widget-playbar.fw-theme-customized div.element {
  /* style rules to apply to div's with the "element" class */
}

Stock Widgets

Stock widgets are built into every flex app, and can be used without loading any additional scripts or resources on your website. You can add them to your page with any of the widget display methods, and theme them with your own css. They are provided as an easy way to get basic interface elements into your webpages with minimal effort.

Are you handy with HTML? Read our themers guide for information on how to create your own new interfaces on the fly!

Sandbox

Open SandboxWant to get hands on with the flex framework? Use any of the html examples from this guide in our sandbox!


Playbar: playbar

The playbar is a widget that contains standard music player controls (play, pause, previous, and next). It also has a play head scrubber, a volume control slider, and an optional button that can be used to open the fullscreen mode of the app.

Settings:

width:Integer Optional Controls the width of the widget as it's rendered.
fullscreen:Boolean Optional If set to 'false', the fullscreen button will not appear.
theme:String Optional Specify a custom theming prefix for the widget.

Embed Example:
<div data-bbflex="widget:playbar,width:500"></div>
Theme & Structure
This widget can be used "out of the box". If no custom theme prefix is specified in the settings, it will inherit default theming from the framework. The following html elements are created inside the widget container.
<div class="fw-interface-controls-wrap fw-jplayer-interface">
  <div class="fw-controls">
    <a class="fw-previous jp-button" ><i class="flexicon-fast-bw"></i></a>
    <a class="fw-play jp-button"><i class="flexicon-play"></i></a>
    <a class="fw-pause jp-button"><i class="flexicon-pause"></i></a>
    <a class="fw-next jp-button"><i class="flexicon-fast-fw"></i></a>
    <span class="divider"></span>
  </div>
  <div class="fw-progress-container">
    <div class="fw-progress">
      <div class="fw-seek-bar">
        <div class="fw-play-bar">
          <div class="bullet">
            <div class="fw-current-time"></div>
          </div>
        </div>
      </div>
    </div>
    <span class="divider"></span>
  </div>
  <div class="fw-volume-bar-container">
    <a class="fw-mute"><i class="flexicon-volume-up"></i></a>
    <a class="fw-unmute"><i class="flexicon-volume-down"></i></a>
    <div class="fw-volume-bar">
      <div class="fw-volume-bar-value">
        <div class="bullet"></div>
      </div>
    </div>
  </div>
  <div class="fw-full-screen-container">
    <a class="fw-fullscreen jp-button"><i class="fwicon-resize-full"></i></a>
  </div>
</div>

Progressbar: progressbar

The progress bar is a widget that includes the total time of the currently playing song, the current play head position, and a progress indicator.

Settings:

width:Integer Optional Controls the width of the widget as it's rendered.
height:Integer Optional Controls the height of the widget as it's rendered.
theme:String Optional Specify a custom theming prefix for the widget.

Embed Example:
<div data-bbflex="widget:progressbar,width:500"></div>
Theme & Structure
This widget does not include any default theming. It is meant to be included as part of a larger interface and themed according to the manner in which it is used. The primary benefit to using this widget is that it's already composed and linked to the music play head in the application. All you need to do is provide the css styles.
<div class="fw-interface-controls-wrap fw-jplayer-interface">
  <div class="fw-progress-container">
    <div class="fw-current-time"></div>
    <div class="fw-progress">
      <div class="fw-seek-bar">
        <!-- The width of the "fw-play-bar" is sync'd with the play head -->
        <div class="fw-play-bar">
          <div class="bullet"></div>
        </div>
      </div>
    </div>
    <div class="fw-duration"></div>
  </div>
</div>

Cart: cart

The cart widget displays the name, quantity, price, and license type of all the beats currently in the users shopping cart. Clicking on an item will show that items details in a modal dialog.

Settings:

width:Integer Optional Controls the width of the widget as it's rendered.
height:Integer Optional Controls the height of the widget as it's rendered.
scroll:Boolean Optional Default: false. If set to true, the widget will be a fixed height with scrollbars.
theme:String Optional Specify a custom theming prefix for the widget.

Embed Example:
<div data-bbflex="widget:cart,width:500,height:300,scroll:true"></div>
Theme & Structure
<div class="fw-cart-item-list">
  <div class="fw-cart-item">
    <div class="fw-cart-item-wrapper">
      <div class="fw-cart-item-qty"></div>
      <div class="fw-cart-item-price"></div>
      <div class="fw-cart-item-title"></div>
      <div class="fw-cart-item-model"></div>
    </div>
  </div>
</div>

Playlist: playlist

The playlist widget displays the name of all the beats in the selected playlist. It also supports dynamic loading of additional beats in the playlist if it's scrolled to the bottom. Clicking the name of a beat will begin playing that beat.

Settings:

width:Integer Optional Controls the width of the widget as it's rendered.
height:Integer Optional Controls the height of the widget as it's rendered.
scroll:Boolean Optional Default: false. If set to true, the widget will be a fixed height with scrollbars.
playlist:String Optional Default: current playlist. You can provide the id to a specific playlist to show.
theme:String Optional Specify a custom theming prefix for the widget.

Embed Example:
<div data-bbflex="widget:playlist,width:500,height:100,scroll:true"></div>
Theme & Structure
<ul class="fw-playlist-items">
  <!-- The "fw-playlist-current" class will only apply to the active beat -->
  <li class="fw-playlist-current"><a>Beat Title</a></li>
</ul>
<div class="fw-playlist-loading"><i class="fwicon-down-dir"></i> Load More...</div>

Playlists: playlists

The playlists widget displays the name of all the playlists available in your app, grouped together by category. Clicking the name of a playlist will make it the active playlist.

Settings:

width:Integer Optional Controls the width of the widget as it's rendered.
height:Integer Optional Controls the height of the widget as it's rendered.
scroll:Boolean Optional Default: false. If set to true, the widget will be a fixed height with scrollbars.
theme:String Optional Specify a custom theming prefix for the widget.

Embed Example:
<div data-bbflex="widget:playlists,width:500,height:200,scroll:true"></div>
Theme & Structure
<div class="fw-playlists">
  <span class="group-title"></span>
  <!-- The "active-playlist" class only applies to the active playlist! -->
  <div class="fw-list-title active-playlist">
    <span class="fw-list-count"></span>
    <i class="fwicon-music"></i>
    <span data-bind="text: title"></span>
  </div>
</div>

Licensing Options: licensing

The licensing widget displays a list of all the currently available licensing options (name, price, details link) for the currently playing beat. Clicking the item will allow the user to add the item to cart.

Settings:

width:Integer Optional Controls the width of the widget as it's rendered.
height:Integer Optional Controls the height of the widget as it's rendered.
scroll:Boolean Optional Default: false. If set to true, the widget will be a fixed height with scrollbars.
theme:String Optional Specify a custom theming prefix for the widget.

Embed Example:
<div data-bbflex="widget:licensing,width:500,height:200,scroll:true"></div>
Theme & Structure
<div class="fw-buynow-licenses nowplaying-licenses">
  <div class="fw-buynow-license">
    <i class="fw-buynow-license-icon icon-tag"></i>
    <div class="fw-buynow-addtocart"><i class="icon-forward"></i> View Details</div>
    <div class="fw-buynow-license-name"></div>
    <div class="fw-buynow-license-price"></div>
  </div>
</div>

Widget Catalog

Here are a few widgets that have been built using flex. Use them in your own projects, or fork them on GitHub to add your own features! Refer to the themers guide or developer documentation for more information on how to build your own custom flex widgets and interfaces. Then send us the link to your project and we can add it here for others to download and use.


Open Source Flex Projects
Download Docs Demo Home

Standalone Music Player

This is a standalone embedded music player for the flex framework. It supports a wide range of different sizes, and it includes built in access to the full current playlist, licensing options, and shopping cart as well as all the standard song controls.

Download Docs Demo Home

Playlist Peeler

This is a HTML5 playlist widget that allows you to flip through the beats in the playlist like they were a stack of polaroid snapshots. Just drag the top one off to get to the ones underneath!

Download Docs Demo Home

Docked Music Player

This is a docked player for your flex app. It stays fixed to the bottom of the screen and supports licensing options, playlist changing, shopping cart access, checkout access, and all other standard music controls. It is also responsive to screen size and will adjust its controls and layout according to the screen size it's being viewed on.

Download Docs Demo Home

Floating Screenplay Player

This player floats at the top left of the screen and expands to full size when hovered over. When not hovered, it shrinks down and becomes translucent until hovered again. It provides convenient access to song controls, licensing options, and music information.

Download Docs Demo Home

Perspective Modal Dialogs

This widget adds a cool twist on the presentation of modal dialogs in your app. Instead of the standard modal dialog, if the browser supports 3d transitions, this widget will perform a 3d effect to 'unhide' modal dialogs. In the event that the screen size is too small or the browser doesn't support the effect, then the standard modal dialog will display as usual.