Pillbox pillbox.js

Pillbox is an interface to manage a dynamic list of tags.

{% include js/pillbox-example.html %}

Usage

A pillbox allows user tag management enabling features such as typeahead and tag editing.

Via JavaScript

Call the Pillbox via JavaScript:

{% highlight js %}$('#myPillbox').pillbox();{% endhighlight %}

Via data-attributes

The pillbox will automatically instantiate any pillboxes with data-initialize="pillbox". If the control markup is added after page load with data-initialize="pillbox", this control will be initialized on mousedown.

Markup

Add class="pillbox" to a div within a class="fuelux" container.

{% highlight html %}
{% endhighlight %}

Methods

.pillbox('addItems')
Adds Items to the pillbox programmatically. {% highlight js %} $('#myPillbox').pillbox('addItems', index, [{ text: '', value: '', attr: {}, data: {} }]); {% endhighlight %}
Parameter Description
index The position where to start inserting pill(s). First pane is at position 1. If omitted, or if -1 is used, the item will be appended to end of the list of pills.
[item1, ..., itemX]
item1, ..., itemX		 An array or list of pill objects to be added at the index. See the following table for an overview of the pill object.
Pill object key Type Description
text string Required. Text of pillbox
value string A value stored in the data-value of the pill markup and returned with events
attr object Unless it is a reserved key in this table, child keys will be added as attributes to .pill.
attr.cssClass string CSS classes that will be added to .pill
data object An object of key/value pairs that can be stored in the jQuery data of a pill
.pillbox('destroy')
Removes all functionality, jQuery data, and the markup from the DOM. Returns string of control markup.
.pillbox('removeItems')
Removes all items from the pillbox. {% highlight js %}$('#myPillbox').pillbox('removeItems');{% endhighlight %} Remove one or more items at a specific position in the pillbox by passing optional parameters. The first parameter is a 1 based index that represent the location of the first element to be removed. The second parameter is the number of items that will be removed. {% highlight js %}$('#myPillbox').pillbox('removeItems', index, count);{% endhighlight %}
.pillbox('items')
Returns an array of objects, one per item, each containing the jQuery data() contents of the item which includes data-* attributes plus a text property with the label's visible text.
.pillbox('itemCount')
Returns an integer representing the current number of items.
.pillbox('readonly')
Enables or disables readonly mode for the pillbox.
.pillbox('removeBySelector')
Removes an item based on a jQuery selector. {% highlight js %}$('#myPillbox').pillbox('removeBySelector', 'li[data-value=buzz]');{% endhighlight %}
.pillbox('removeByText')
Removes an item with contained text matching that of the provided text string parameter. {% highlight js %}$('#myPillbox').pillbox('removeByText', "Item 4");{% endhighlight %}
.pillbox('removeByValue')
Removes an item with value matching that of the provided value string parameter. The item has to have a .data-value="{value}" attribute {% highlight js %}$('#myPillbox').pillbox('removeByValue', '1');{% endhighlight %}

Options

Control options below can only be set via JavaScript. Values needed to identify which pill caused an event should be stored in data-attributes within the .pill element, as in data-value="".

Name type default description
acceptKeyCodes array [13, 188] Key codes for keys that trigger an add pill event. Default keys 13 (for enter) and 188 (for comma).
edit boolean false Enables user edited pills.
onAdd function undefined A callback function that executes when a pill is added. function(data,callback){} The data parameter contains an array of the elements being added. The callback parameter is a function that provides asynchronous support for the add functionality. In order for items to be added, the callback must be run and provided an array of items to be added. If you would like to not modify the list of items to be added, provide data as the parameter for the callback function, callback(data).
onRemove function undefined Function that runs when a pill is removed. function(data,callback){} The data parameter contains an array of the elements being removed. The callback parameter is a function that provides asynchronous support for the remove functionality. In order for items to be removed, the callback must be run and provided an array of items to be removed. If you would not like to modify the list of items to be removed, provide data as the parameter for the callback function, callback(data).
onKeyDown function undefined Function that executes when a keydown event is triggered. function(event,data,callback){} The event parameter contains the event object. The data parameter contains an array of the elements being removed. The callback parameter is a function that provides asynchronous support for the typeahead functionality. The callback function must be run in order for the typeahead dropdown with values. Provided the callback with an array of items to display in the typeahead dropdown. {% highlight js %} callback({data:[ { text: '', value:'' }] }); {% endhighlight %}
readonly boolean or -1 -1 Specifies whether the control is in readonly mode. If set to true, the pillbox disables user capacity to add / edit pills. A -1 value means it will check for the presence of the data-readonly="readonly" attribute, and if found initialize in readonly mode.
truncate boolean false When in readonly mode, this option will display only the number of pills that fit within the pillbox main container, with a message indicating the number of hidden items. The message content that appears is found inside the element with class pillbox-more.

Events

Event Type Description
clicked.fu.pillbox This event is triggered when a pill is clicked. A jQuery data() object with information about the clicked pill is returned.
added.fu.pillbox This event is triggered when a pill is added. A jQuery data() object with information about the added pill is returned.
removed.fu.pillbox This event is triggered when a pill is removed. A jQuery data() object with information about the removed pill is returned.
edited.fu.pillbox This event is triggered when a pill is edited. A jQuery data() object with information about the edited pill is returned.

All pillbox events are fired on the .pillbox classed element.

{% highlight js %} $('#myPillbox').on('clicked.fu.pillbox', function (evt, item) { // do something }); {% endhighlight %}

Fuel UX Dependencies

Example

Pillbox is an interface to manage a list of tags. Wrap the list of tags (pills) within .fuelux .pillbox

{% include js/pillbox-example.html %}
Sample Methods