Bundled Extensions

Extensions that come as a part of Fuel UX by default.

Additional functionality added to drop-down menus that enables dropup menus instead of drop-down menus based on screen position.

Add data-flip="auto" to a drop-down trigger data-toggle="drop-down". (You may need to scroll up to trigger this functionality.) Place this menu at the bottom of the screen to implement a drop-up menu.

<div class="btn-group">
	<button type="button" class="btn btn-danger">Auto-Flip Drop-down</button>
	<button type="button" class="btn btn-danger dropdown-toggle" data-toggle="dropdown" data-flip="auto">
		<span class="caret"></span>
		<span class="sr-only">Toggle Drop-down</span>
	</button>
	<ul class="dropdown-menu" role="menu" >
		<li><a href="#">Action</a></li>
		<li><a href="#">Another action</a></li>
		<li><a href="#">Something else here</a></li>
		<li class="divider"></li>
		<li><a href="#">Separated link</a></li>
	</ul>
</div>

By default, Fuel UX automatically positions the drop-down menu 100 percent from the top and along the right side of its parent. Remove .dropdown-menu-right to a .dropdown-menu to left align the drop-down menu.

The dropdown-autoflip add-on determines whether to show a drop-down menu or a dropup menu by calculating the position on the screen and the edge of the viewport. If the positioning requires a drop-up menu, add .dropup to the .dropdown-menu element.

Markup

Add data-flip="auto" to a drop-down menu within a class="fuelux" container.

<div class="btn-group">
	<button type="button" class="btn btn-danger">Auto-Flip Drop-down</button>
	<button type="button" class="btn btn-danger dropdown-toggle" data-toggle="dropdown" data-flip="auto">
		<span class="caret"></span>
		<span class="sr-only">Toggle Drop-down</span>
	</button>
	<ul class="dropdown-menu" role="menu" >
		...
	</ul>
</div>

Event Listeners

The auto-flip drop-down only receives events.

Event Type Description
click Receives clicks from [data-toggle=dropdown][data-flip]
suggest Fire the suggest event and pass in a drop-down menu $('#dropdownMenu').

Repeater List View repeater-list.js

The repeater list view plug-in will render data in a tabular format, with many options and methods to suit your needs.

Example

Usage

The repeater list plug-in extends repeater functionality. This plug-in follows the steps specified in the repeater docs. You can also use the following additional features:

Data Source

The dataSource function behaves as described in the repeater docs. However, the function potentially provides a few additional attributes in the options argument:

Attribute type description
sortDirection string If the list view is sortable and has been sorted by the user, this will indicate the sort direction. Values are either 'asc' or 'desc'.
sortProperty string If the list view is sortable and has been sorted by the user, this will indicate the column property that has been sorted on.

Additionally, the function requires a few additional parameters on the returned data object to render the data properly:

Attribute type description
columns array Array of objects representing the desired columns within the rendered list. The column objects contain three attributes:
  • className - String representing the classes to be added to any DOM items associated with the column. Multiple classes can be adding a space between each name
  • label - String or jQuery attribute containing the content to be displayed as the "name" of the column
  • property - String value that dictates which item attribute is displayed within the column
  • sortable - Optional Boolean or string value dictating whether user can sort the column. A true value indicates sorting on the property value. A string value sorts on the specified value. This attribute defaults to false
  • sortDirection - Optional string to set initial sort direction of the column. Values can be either 'asc' or 'desc'. NOTE: only one column can be sorted upon at a time.
  • width - String or Number dictating this column's width
(ex: [ { label: 'Name', property: 'name', sortable: true }, ... ] )
items array Array of objects representing the item data that will be displayed within the repeater. The item objects can contain any number of attributes. The attribute name must match the column property value to display within a column.

Options

You can pass options via Javascript upon initialization.

Name type default description
list_actions object null Can be used to configure an additional actions column in the repeater. It will positioned as the rightmost column and will always be visible. It creates a dropdown menu that can be populated with x number of actions to be applied to the row. If multi select is also enabled will allow for bulk actions.
  • width - optional width to the actions column
  • items - Array of objects representing the different action items in the dropdown
    • name - String representing the name of the action
    • html - HTML string that would modify the markup of the action item
    • clickAction - returns a helpers obj once this action item has been clicked
      • helpers returns an object that contains helpers.item which is the jquery element of the current table row. Also returns helpers.rowData which are all key/value data from the current item/row in the dataSource
list_actions:  {
  width: 37,
  items: [{
    name: 'delete',
    html: '<span class="glyphicon glyphicon-trash"></span> Delete',
    clickAction: function(helpers, callback, e) {
        e.preventDefaul();
        console.log('hey it worked');
        console.log(helpers);
        console.log(e);
        callback();
    }
  }]
}
list_columnRendered function null If set, the repeater calls this function after rendering each table cell within a row. It passes a helpers object and a callback function as arguments. This function is the preferred way to modify table cell markup.
  • helpers.rowData - All key/value data from the current item/row in the dataSource
  • helpers.columnAttr - The key name specified by dataSource.columns of the current column/cell
  • helpers.container - jQuery element of the current tr or table row
  • helpers.item - jQuery element of the current td or table cell
  • callback - Call this function to continue rendering the view
list_columnSizing boolean true Dictates whether the repeater should run the intelligent column resizing algorithm. This feature only resizes columns without a set value. Setting this value to false will disable this feature entirely.
list_columnSyncing boolean true Dictates whether the repeater should run the post-render column syncing algorithm. This feature keeps the `.repeater-list-heading` classed divs in alignment with the columns. Setting this value to false will disable this feature entirely.
list_frozenColumns number 0 Dictates whether the repeater should create frozen columns in the repeater. This feature creates x number of frozen columns on the left side of the repeater. Frozen columns means that when scrolled left to right these columns will not move and always be visible.
list_infiniteScroll boolean or object false Dictates whether the repeater list view should utilize infinite scrolling instead of pagination. A true value enables infinite scrolling with default settings. Additionally, you can set this value to an object with attributes matching the options available in the infinite scroll control. This option allows for further customization and ignores the dataSource option.
list_noItemsHTML string or jQuery object '' Specifies what is displayed if no items return from the dataSource. You can use a string or jQuery object.
list_selectable boolean or string false Specifies whether a user can select rendered item rows. If you set the value to true, users can select only one row at a time. If you set the value to 'multi', users can select multiple rows at once.
list_sortClearing boolean false Specifies whether users can clear sortable columns with a third click:
  • one click, sort ASC.
  • second click, sort DESC
  • third click, no sorting
list_rowRendered function null If set, the repeater calls this function after the repeater renders each row, passing a helpers object and callback function as arguments. This function is the preferred way to modify table row markup.
  • helpers.rowData - All key/value data from the current item/row in the dataSource
  • helpers.container - jQuery element of the row's parent (tbody)
  • helpers.item - jQuery element of the current tr or table row
  • callback - Call this function to continue rendering the view
list_highlightSortedColumn boolean true Specifies whether sorted columns should be highlighted.

Methods

.repeater('list_clearSelectedItems');

Clears any currently selected row items. You can use selectable row items only by enabling the list_selectable option.

$('#myRepeater').repeater('list_clearSelectedItems');

.repeater('list_getSelectedItems');

Returns the currently selected row items in an array. You can use selectable row items only by enabling the list_selectable option.

$('#element').repeater('list_getSelectedItems');

.repeater('list_setSelectedItems');

Set the selected row items for the current displayed data. This function accepts an array of items objects and force boolean as arguments.

$('#myRepeater').repeater('list_setSelectedItems', [ {...}, ...]);
Parameter description
items Required Array of items objects. The items objects specify which item to select with attributes to identify the item. If the items object contains an index property, that items object will select the matching item index within the currently displayed data. If the items object contains a property attribute and value attribute, that items object will select items with properties matching the specified value.
(ex: [ { index: 4 }, { property: 'name', value: 'nameValue' } ] )
force Optional Boolean specifying whether to ignore current list_selectable mode when selecting items. This value defaults to false and allows only one selectable item if list_selectable does not equal multi, regardless of how many items are passed into the items array parameter. Set the value to true to override this behavior and select all provided items.

Events

Event Type Description
deselected.fu.repeaterList If list_selectable is enabled, fires whenever the user deselects a row. Provides an event object and the deselected row as arguments.
selected.fu.repeaterList If list_selectable is enabled, fires whenever the user selects a row. Provides an event object and the selected row as arguments.

All repeater-list events are fired on the .repeater classed element.

$('#myRepeater').on('selected.fu.repeaterList', function () {
    // do something…
});

Repeater Thumbnail View repeater-thumbnail.js

The repeater thumbnail view plug-in will render data in customizable thumbnails, with many options and methods to suit your needs.

Example

Usage

The repeater thumbnail plug-in extends repeater functionality. This plug-in follows the steps specified in the repeater docs. You can also use the following additional features:

Data Source

The dataSource function behaves as described in the repeater docs. However, the function requires a few additional parameters on the returned data object to render the data properly:

Attribute type description
items array Array of objects representing the thumbnails that will be displayed within the repeater. The item objects can contain any number of attributes, although attributes with certain names will be used to render the thumbnail. In the default thumbnail template, the `src` and `name` attributes are expected.

Options

You can pass options via Javascript upon initialization.

Name type default description
thumbnail_alignment string 'justify' Specifies the alignment of rendered thumbnails. The options for the alignment of thumbnails include 'left', 'center', 'justify', 'right' or 'none'
thumbnail_infiniteScroll boolean or object false Dictates whether the repeater thumbnail view should utilize infinite scrolling instead of pagination. A true value enables infinite scrolling with default settings. Additionally, you can set this value to an object with attributes matching the options available in the infinite scroll control. This option allows for further customization and ignores the dataSource option.
thumbnail_itemRendered function null The repeater calls this function after the repeater renders each item, passing a a helpers object and callback function as arguments. The helpers object includes itemData, parent container, and current thumbnail item as attributes, if available. Once ready, call the callback function in order to continue with rendering.
thumbnail_selectable boolean or string false Specifies whether a user can select rendered thumbnails. If you set the value to true, users can select only one thumbnail at a time. If you set the value to 'multi', users can select multiple thumbnails at once.
thumbnail_template string
<div class="thumbnail repeater-thumbnail"><img height="75" src="{{src}}" width="65"><span>{{name}}</span></div>
Dictates the template used to render the repeater thumbnails. Mustache/Handlebar-style syntax ('{{example}}') can be used to specify where various attribute values will be inserted. NOTE: only the immediate decendents of the thumbnail item object can be referenced; all other Mustache/Handlebars functionality not supported.

Methods

.repeater('thumbnail_clearSelectedItems');

Clears any currently selected thumbnail items. You can use selectable thumbnail items only by enabling the thumbnail_selectable option.

$('#myRepeater').repeater('thumbnail_clearSelectedItems');

.repeater('thumbnail_getSelectedItems');

Returns the currently selected thumbnail items in an array. You can use selectable thumbnail items only by enabling the thumbnail_selectable option.

$('#element').repeater('thumbnail_getSelectedItems');

.repeater('thumbnail_setSelectedItems');

Set the selected thumbnail items for the current displayed data. This function accepts an array of items objects and force boolean as arguments.

$('#myRepeater').repeater('thumbnail_setSelectedItems', [ {...}, ...]);
Parameter description
items Required Array of items objects. The items objects specify which thumbnails to select with attributes to identify the item. If the items object contains an index property, the method will select the matching thumbnail index within the currently displayed data. If the items object contains a selector property, the method will select any thumbnails matching that selector.
(ex: [ { index: 4 }, { selector: '.coolThumbnail' } ] )
force Optional Boolean specifying whether to ignore current thumbnail_selectable mode when selecting items. This value defaults to false and allows only one selectable item if thumbnail_selectable does not equal 'multi', regardless of how many items are passed into the items array parameter. Set the value to true to override this behavior and select all provided items.

Events

Event Type Description
deselected.fu.repeaterThumbnail If thumbnail_selectable is enabled, fires whenever the user deselects a thumbnail. Provides an event object and the deselected thumbnail as arguments.
selected.fu.repeaterThumbnail If thumbnail_selectable is enabled, fires whenever the user selects a thumbnail. Provides an event object and the selected thumbnail as arguments.

All repeater-thumbnail events are fired on the .repeater classed element.

$('#myRepeater').on('selected.fu.repeaterThumbnail', function () {
    // do something…
});

Writing an Extension

They say one learns best by showing, so let's walk through some of the details and gotchas of making a repeater view.

Repeater Views

The repeater view object contains various attributes used to render data within the repeater control. Each view includes a unique name that is selectable via the .repeater-views classed button group. The $.fn.repeater.views object adds the view object upon load using the unique view name as a key. Find more information on creating a repeater view extension below.

Default Options and Methods

Here are examples for adding default options and methods in your repeater view extension:

//Adding default options to the repeater
$.fn.repeater.defaults = $.extend({}, $.fn.repeater.defaults, {
  myView_additionalOption: false,
  myView_anotherOption: 'Hello World'
});

//Adding methods to the repeater
$.fn.repeater.Constructor.prototype.myView_additionalMethod = function () {
  //Do stuff here
};

View Object

The main view object serves as the base for the repeater view extension. It's definition looks something like this:

//View extension definition
$.fn.repeater.viewTypes.myView = {
  cleared: function (helpers) {
    //Do stuff here
  }

  //Additional attributes listed as needed
};
The view object can contain a variety of attributes. All functions within the repeater view object are called with the repeater instance's context of this. The functions receive a helpers object, and in some cases a callback function. If a callback function is present, it must be called to proceed to the next step. The following attributes can be defined when developing a repeater view extension:

Name type description
cleared function Runs whenever the repeater canvas is cleared. Provided a helpers object containing the current repeater render options.
dataOptions function This function is called prior to calling the dataSource, allowing a view extension to provide additional options to the dataSource. Provided a options object as an argument, which is populated with current dataSource options and is expected to be passed back via the return statement after any manipulation in order to provide the repeater the newly altered dataSource options.
initialize function Runs only once at the beginning of each instantiation of the repeater. Provided a helpers object and callback function, which must be called in order for the repeater to proceed.
resize function Runs whenever the repeater is resized. Provided a helpers object containing width and height of the repeater.
selected function Runs every time this repeater view is selected prior to rendering. Provided a helpers object containing the previous repeater view (prevView)
before function This function is called prior to the renderItems function, if no render function has been defined. Provided a helpers object containing the parent container (the repeater canvas) for items to be inserted and data returned from the dataSource. Expects to be returned an item object, or false if no action is desired.
renderItem function This function is called after the before function, if no render function has been defined. It is iterated over the array specified by the repeat attribute. It is provided a helpers object containing the parent container (which will be whatever element within the repeater canvas has the data-container="true" attribute, or the canvas itself if not found) for items to be inserted, the data returned from the dataSource, the index of the current item within the iteration, and the subset array of data that the renderItem function is being iterated on. Expects to be returned an item object, or false if no action is desired.
repeat string This string value specifies which array the renderItem function iterates over. It represents an attribute of an object using dot notation. The root level value must use 'data' or 'this'. If the root value uses 'data', the root object will be the data object returned from the dataSource. If the root value uses 'this', the root object will be the current repeater instance context of this. You can specify further levels separated by dots. The final level must include an array or iteration will not function correctly. This array will be passed as the subset attribute in the helpers object of the renderItem function. The default value is 'data.items'
after function This function is called after the renderItems function, if no render function has been defined. Provided a helpers object containing the parent container (the repeater canvas) for items to be inserted and data returned from the dataSource. Expects to be returned an item object, or false if no action is desired.
render function If defined, before, renderItem, and after will be ignored, and this function will be called instead. It is provided a helpers object containing the parent container (the repeater canvas) for items to be inserted and data returned from the dataSource, as well as a callback function. The callback function must be called in order for the repeater to complete rendering. With this function, it is up to the view extension developer to append contents to the container as they see fit.

Item Object

The before, renderItem, and after functions can be returned item objects, which specify certain actions to be carried out by the repeater, such as inserting content:

Name type description
item string, jQuery object, or DOM node Specifies the content to be inserted into the container. If not specified, no action will be taken.
action string Optional. Specifies the jQuery mechanism of action to insert item content. If not specified, the default action will be 'append'. Any of the jQuery insertion methods can be used. If set to 'none', no insertion will occur.
container jQuery object, DOM node, or selector Optional. Specifies which element to insert the item content. If not specified, the default will be whatever the container was in the helpers object of the function that returned the items object.

Data Attributes

You can add a few data-attributes to any markup when rendering content to specify different rendering behaviors:

Name Value(s) description
data-container "true" If you add this value to an element within the repeater canvas in the before function, that element will become the container that is passed to the renderItem function.
data-infinite "true" If infinite scrolling is enabled, the element with this attribute becomes the infinite scrolling container.
data-preserve "deep" or "shallow" The repeater will preserve an element containing this attribute upon clearing the repeater of content. This clear occurs during each dataSource call. Set the value to "deep" to preserve the element and all children. Set the value to "shallow" to preserve just the element and remove any child nodes not marked with data-preserve.

Community Extensions

Do you have an extension that others would find useful?

Submit an extension

To submit your extension to the Fuel UX Community, first publish a repository on GitHub with complete and well written instructions. Instructions should be a clear and detailed explanation of the purpose and usage of the extension. Please show code, when applicable, that is clear and easy to read and copy as a whole. Bonus points for screen shots in your README.md! If you choose not to support your extension, state this in your description.

Please fork the Fuel UX repository and submit a pull request with a modified extensions.html in the gh-pages branch.

Fuel UX controls are also jQuery plugins, so you can $.extend() them, too.

(function (factory) {
	if (typeof define === 'function' && define.amd) {
		// if AMD loader is available, register as an anonymous module.
		define(['jquery', 'fuelux/datepicker'], factory);
	} else {
		// OR use browser globals if AMD is not present
		factory(jQuery);
	}
}(function ($) {

	// -- END UMD WRAPPER PREFACE --
		
	// -- BEGIN MODULE CODE HERE --

	// change something with the data grid control
	$.fn.extend($.fn.datepicker.Constructor.prototype, {
		// adding methods
		awesomeNewMethod: function () { },

		// overriding methods
		someExistingMethod: function () { }
	});

	// rinse and repeat

// -- BEGIN UMD WRAPPER AFTERWORD --
}));
	// -- END UMD WRAPPER AFTERWORD --

Thank you for your contribution! We look forward to your creative ideas.