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.