Pillbox

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

Item 1 Remove
Item 2 Remove
Item 3 Remove
Item 4 Remove
Item 5 Remove
and more...

Usage

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

Via JavaScript

Call the Pillbox via JavaScript:

$('#myPillbox').pillbox();

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.


<div class="pillbox" id="myPillbox" data-initialize="pillbox">
  <ul class="clearfix pill-group">
    <li class="btn btn-default pill" data-value="foo">
      <span>Item Title</span>
      <span class="glyphicon glyphicon-close">
        <span class="sr-only">Remove</span>
      </span>
    </li>
    ....
    <li class="pillbox-input-wrap btn-group">
      <a class="pillbox-more">and <span class="pillbox-more-count"></span> more...</a>
      <input class="form-control dropdown-toggle pillbox-add-item" type="text" placeholder="add item">
      <button class="dropdown-toggle sr-only" type="button">
        <span class="caret"></span>
        <span class="sr-only">Toggle Dropdown</span>
      </button>
      <ul class="suggest dropdown-menu" data-toggle="dropdown" data-flip="auto" role="menu"></ul>
    </li>
  </ul>
</div>

Methods

.pillbox('addItems')

Adds Items to the pillbox programmatically.


$('#myPillbox').pillbox('addItems', index, [{ text: '', value: '', attr: {}, data: {} }]);

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.

$('#myPillbox').pillbox('removeItems');

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.

$('#myPillbox').pillbox('removeItems', index, count);

.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.

$('#myPillbox').pillbox('removeBySelector', 'li[data-value=buzz]');

.pillbox('removeByText')

Removes an item with contained text matching that of the provided text string parameter.

$('#myPillbox').pillbox('removeByText', "Item 4");

.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

$('#myPillbox').pillbox('removeByValue', '1');

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. `callback({data:[ { text: '', value:'' }] });`
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.


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

Fuel UX Dependencies

Dropdown-autoflip

Example

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

Item 1 Remove
Item 2 Remove
Item 3 Remove
Item 4 Remove
Item 5 Remove
and more...