fuelux/_includes/js/pillbox.html

<!-- pillbox
================================================== -->
<div class="fu-docs-section">
  <h1 id="pillbox" class="page-header">Pillbox <a href="{{ site.repo }}/blob/{{ site.current_version }}/js/pillbox.js"><small>pillbox.js</small></a></h1>

  <p>Pillbox is an interface to manage a dynamic list of tags.</p>

  <div id="pillboxIllustration" class="pillbox">
  {% include js/pillbox-example.html %}
  </div>

  <h2 id="pillbox-usage">Usage</h2>
  <p>A pillbox allows user tag management enabling features such as typeahead and tag editing.</p>

  <h3 id="pillbox-usage-javascript">Via JavaScript</h3>
  <p>Call the Pillbox via JavaScript:</p>
  {% highlight js %}$('#myPillbox').pillbox();{% endhighlight %}

  <h3 id="pillbox-usage-data-attributes">Via data-attributes</h3>
  <p>The pillbox will automatically instantiate any pillboxes with <code>data-initialize="pillbox"</code>. If the control markup is added <em>after page load</em> with <code>data-initialize="pillbox"</code>, this control will be initialized on <code>mousedown</code>.

  <h3 id="pillbox-usage-markup">Markup</h3>

  <p>Add <code>class="pillbox"</code> to a div within a <code>class="fuelux"</code> container.</p>


{% highlight html %}
<div class="pillbox" data-initialize="pillbox" id="myPillbox">
  <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 type="text" class="form-control dropdown-toggle pillbox-add-item" placeholder="add item">
      <button type="button" class="dropdown-toggle sr-only">
        <span class="caret"></span>
        <span class="sr-only">Toggle Dropdown</span>
      </button>
      <ul class="suggest dropdown-menu" role="menu" data-toggle="dropdown" data-flip="auto"></ul>
    </li>
  </ul>
</div>
{% endhighlight %}

  <h3 id="pillbox-usage-methods">Methods</h3>

  <dl>
    <dt id="pillbox-usage-methods-add-items">.pillbox('addItems')</dt>
    <dd>Adds Items to the pillbox programmatically.
{% highlight js %}
$('#myPillbox').pillbox('addItems', index, [{ text: '', value: '', attr: {}, data: {} }]);
{% endhighlight %}

      <div class="table-responsive">
        <table class="table table-bordered table-striped">
          <thead>
            <tr>
              <th style="width: 150px;">Parameter</th>
              <th>Description</th>
            </tr>
          </thead>
          <tbody>
            <tr>
              <td>index</td>
              <td>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.</td>
            </tr>
            <tr>
              <td><em>[item1, ..., itemX] <br/> item1, ..., itemX</em></td>
              <td>An array or list of pill objects to be added at the <code>index</code>. See the following table for an overview of the pill object.</td>
            </tr>
          </tbody>
        </table>
      </div><!-- ./fu-table-responsive -->


      <div class="table-responsive">
        <table class="table table-bordered table-striped">
          <thead>
          <tr>
            <th style="width: 125px;">Pill object key</th>
            <th style="width: 100px;">Type</th>
            <th>Description</th>
          </tr>
          </thead>
          <tbody>
          <tr>
            <td>text</td>
            <td>string</td>
            <td><i>Required.</i> Text of pillbox</td>
          </tr>
          <tr>
            <td>value</td>
            <td>string</td>
            <td>A value stored in the <code>data-value</code> of the pill markup and returned with events</td>
          </tr>
          <tr>
            <td>attr</td>
            <td>object</td>
            <td>Unless it is a reserved key in this table, child keys will be added as attributes to <code>.pill</code>.</td>
          </tr>
          <tr>
            <td>attr.cssClass</td>
            <td>string</td>
            <td>CSS classes that will be added to <code>.pill</code></td>
          </tr>
          <tr>
            <td>data</td>
            <td>object</td>
            <td>An object of key/value pairs that can be stored in the jQuery data of a pill</td>
          </tr>
          </tbody>
        </table>
      </div><!-- ./fu-table-responsive -->

    </dd>

    <dt id="pillbox-usage-methods-destroy">.pillbox('destroy')</dt>
    <dd>Removes all functionality, jQuery data, and the markup from the DOM. Returns string of control markup.</dd>

    <dt id="pillbox-usage-methods-remove-items">.pillbox('removeItems')</dt>
    <dd>
    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 <code>1</code> 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 %}
    </dd>

    <dt id="pillbox-usage-methods-items">.pillbox('items')</dt>
    <dd>Returns an array of objects, one per item, each containing the jQuery data() contents of the item which includes <code>data-*</code> attributes plus a text property with the label's visible text.</dd>

    <dt id="pillbox-usage-methods-item-count">.pillbox('itemCount')</dt>
    <dd>Returns an integer representing the current number of items.</dd>

    <dt id="pillbox-usage-methods-readonly">.pillbox('readonly')</dt>
    <dd>Enables or disables readonly mode for the pillbox.</dd>

    <dt id="pillbox-usage-methods-remove-by-selector">.pillbox('removeBySelector')</dt>
    <dd>
      Removes an item based on a jQuery selector.
{% highlight js %}$('#myPillbox').pillbox('removeBySelector', 'li[data-value=buzz]');{% endhighlight %}
    </dd>

    <dt id="pillbox-usage-methods-removeByText">.pillbox('removeByText')</dt>
    <dd>
      Removes an item with contained text matching that of the provided <code>text</code> string parameter.
{% highlight js %}$('#myPillbox').pillbox('removeByText', "Item 4");{% endhighlight %}
    </dd>

    <dt id="pillbox-usage-methods-removeByValue">.pillbox('removeByValue')</dt>
    <dd>
      Removes an item with value matching that of the provided <code>value</code> string parameter. <em>The item has to have a <code>.data-value="{value}"</code> attribute</em>
{% highlight js %}$('#myPillbox').pillbox('removeByValue', '1');{% endhighlight %}
    </dd>
  </dl>

  <h3 id="pillbox-usage-options">Options</h3>
  <p>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 <code>.pill</code> element, as in <code>data-value=""</code>.</p>

  <div class="table-responsive">
    <table class="table table-bordered table-striped">
      <thead>
      <tr>
        <th style="">Name</th>
        <th style="">type</th>
        <th style="width: 50px;">default</th>
        <th>description</th>
      </tr>
      </thead>
      <tbody>
        <tr>
          <td>acceptKeyCodes</td>
          <td>array</td>
          <td>[13, 188]</td>
          <td>Key codes for keys that trigger an add pill event. Default keys <code>13</code> (for enter) and <code>188</code> (for comma).</td>
        </tr>
        <tr>
          <td>edit</td>
          <td>boolean</td>
          <td>false</td>
          <td>Enables user edited pills.</td>
        </tr>
        <tr>
          <td>onAdd</td>
          <td>function</td>
          <td>undefined</td>
          <td>
            A callback function that executes when a pill is added. <code>function(data,callback){}</code>
            The <code>data</code> parameter contains an array of the elements being added.
            The <code>callback</code> parameter is a function that provides asynchronous support for the add functionality.
            In order for items to be added, the <code>callback</code> 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, <code>callback(data)</code>.
          </td>
        </tr>
        <tr>
          <td>onRemove</td>
          <td>function</td>
          <td>undefined</td>
          <td>
            Function that runs when a pill is removed.
            <code>function(data,callback){}</code>
            The <code>data</code> parameter contains an array of the elements being removed.
            The <code>callback</code> parameter is a function that provides asynchronous support for the remove functionality.
            In order for items to be removed, the <code>callback</code> 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, <code>callback(data)</code>.
          </td>
        </tr>
        <tr>
          <td>onKeyDown</td>
          <td>function</td>
          <td>undefined</td>
          <td>
            Function that executes when a <code>keydown</code> event is triggered.
            <code>function(event,data,callback){}</code>
            The <code>event</code> parameter contains the event object.
            The <code>data</code> parameter contains an array of the elements being removed.
            The <code>callback</code> parameter is a function that provides asynchronous support for the typeahead functionality.
            The <code>callback</code> function must be run in order for the typeahead dropdown with values. Provided the <code>callback</code> with an array of items to display in the typeahead dropdown.
{% highlight js %}
callback({data:[
  {
    text: '',
    value:''
  }]
});
{% endhighlight %}
          </td>
        </tr>
    <tr>
      <td>readonly</td>
      <td>boolean or -1</td>
      <td>-1</td>
      <td>Specifies whether the control is in readonly mode. If set to <code>true</code>, the pillbox disables user
        capacity to add / edit pills. A <code>-1</code> value means it will check for the presence of the
        <code>data-readonly="readonly"</code> attribute, and if found initialize in readonly mode.
      </td>
    </tr>
    <tr>
      <td>truncate</td>
      <td>boolean</td>
      <td>false</td>
      <td>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 <code>pillbox-more</code>.
      </td>
    </tr>
      </tbody>
    </table>
  </div><!-- ./fu-table-responsive -->



  <h3 id="pillbox-usage-events">Events</h3>
  <div class="table-responsive">
    <table class="table table-bordered table-striped">
      <thead>
      <tr>
        <th style="width: 150px;">Event Type</th>
        <th>Description</th>
      </tr>
      </thead>
      <tbody>
      <tr>
        <td>clicked.fu.pillbox</td>
        <td>This event is triggered when a pill is clicked. A jQuery data() object with information about the clicked pill is returned.</td>
      </tr>
      <tr>
        <td>added.fu.pillbox</td>
        <td>This event is triggered when a pill is added. A jQuery data() object with information about the added pill is returned.</td>
      </tr>
      <tr>
        <td>removed.fu.pillbox</td>
        <td>This event is triggered when a pill is removed. A jQuery data() object with information about the removed pill is returned.</td>
      </tr>
      <tr>
        <td>edited.fu.pillbox</td>
        <td>This event is triggered when a pill is edited. A jQuery data() object with information about the edited pill is returned.</td>
      </tr>
      </tbody>
    </table>
  </div><!-- ./fu-table-responsive -->

  <p>All pillbox events are fired on the <code>.pillbox</code> classed element.</p>
{% highlight js %}
$('#myPillbox').on('clicked.fu.pillbox', function (evt, item) {
  // do something
});
{% endhighlight %}
  
  <h3 id="pillbox-dependencies">Fuel UX Dependencies</h3>
  <ul>
    <li><a href="extensions.html#bundled-extensions-dropdown-autoflip">Dropdown-autoflip</a></li>
  </ul>

  <h2 id="pillbox-examples">Example</h2>
  <p>Pillbox is an interface to manage a list of tags. Wrap the list of tags (pills) within <code>.fuelux .pillbox</code></p>

  <div class="fu-example section">
    <div id="myPillbox" class="pillbox">
    {% include js/pillbox-example.html %}
    </div>

    <h5 id="pillbox-examples-sample-methods">Sample Methods</h5>
    <div class="btn-group">
      <button type="button" class="btn btn-default" id="btnPillboxAdd">add</button>
      <button type="button" class="btn btn-default" id="btnPillboxRemoveByValue">remove by value</button>
      <button type="button" class="btn btn-default" id="btnPillboxRemoveBySelector">remove by selector</button>
      <button type="button" class="btn btn-default" id="btnPillboxRemoveByText">remove by text</button>
      <button type="button" class="btn btn-default" id="btnPillboxItems">log items to console</button>
      <button type="button" class="btn btn-default" id="btnPillboxDestroy">destroy and append</button>
    </div>
  </div>
</div> <!-- end docs-section -->