Merge pull request #132 from gearsdigital/feature/simplify-options-item-builder-api

simplify options item builder api

Author: lcdsantos

public/index.html

@@ -254,15 +254,37 @@ <h2>Options</h2>
 
     /*
      * Type: String or Function
-     * Description: Define how each option should be rendered inside its <li> element.
+     * Description: Define how each option should be rendered inside its &lt;li&gt; element.
      *
      *              If it's a string, all keys wrapped in brackets will be replaced by
      *              the respective values in itemData. Available keys are:
-     *              'value', 'text', 'slug', 'disabled'.
+     *              'value', 'text', 'slug', 'index'.
      *
-     *              If it's a function, it will be called with the following parameters:
-     *              (itemData, element, index). The function must return a string,
-     *              no keys will be replaced in this method.
+     *              If it's a function, it will be called with the following parameter:
+     *              (itemData). The function must return a string. If available all keys
+     *              will be replaced by the respective values in itemData.
+     *
+     *              itemData&lt;Object&gt; {
+     *                 className // Type: String.          Description: option class names.
+     *                 disabled  // Type: Boolean.         Description: option is disabled true/false
+     *                 selected  // Type: Boolean.         Description: option is selected true/false
+     *                 element   // Type: HTMLDomElement.  Description: current select element
+     *                 index     // Type: Number.          Description: current option index
+     *                 slug      // Type: String.          Description: option slug
+     *                 text      // Type: String.          Description: option text
+     *                 value     // Type: String.          Description: option value
+     *              }
+     *
+     *              EXAMPLE:
+     *
+     *              function(itemData) {
+     *                  return '<span class="item-{index}">{text}</span>';
+     *              }
+     *
+     *              // you're free to build and return your own strings
+     *              function(itemData) {
+     *                  return itemData.text + '(' + itemData.index + ')';
+     *              }
      */
     optionsItemBuilder: '{text}',
 

public/jquery.selectric.js

@@ -9,7 +9,7 @@
  *    /,'
  *   /'
  *
- * Selectric ϟ v1.11.0 (Sep 23 2016) - http://lcdsantos.github.io/jQuery-Selectric/
+ * Selectric ϟ v1.11.0 (Sep 24 2016) - http://lcdsantos.github.io/jQuery-Selectric/
  *
  * Copyright (c) 2016 Leonardo Santos; MIT License
  *
@@ -542,23 +542,33 @@
     /**
      * Generate every option markup
      *
-     * @param  {number} i   - Index of current item
-     * @param  {object} elm - Current item
+     * @param  {number} index   - Index of current item
+     * @param  {object} itemData - Current item
      * @return {string}       HTML for the option
      */
-    getItemMarkup: function(i, elm) {
+    getItemMarkup: function(index, itemData) {
       var _this = this;
       var itemBuilder = _this.options.optionsItemBuilder;
+      // limit access to item data to provide a simple interface
+      // to most relevant options.
+      var filteredItemData = {
+        value: itemData.value,
+        text : itemData.text,
+        slug : itemData.slug,
+        index: itemData.index
+      };
 
       return _this.utils.format('<li data-index="{1}" class="{2}">{3}</li>',
-        i,
+        index,
         _this.utils.arrayToClassname([
-          elm.className,
-          i === _this.items.length - 1 ? 'last'     : '',
-          elm.disabled                 ? 'disabled' : '',
-          elm.selected                 ? 'selected' : ''
+          itemData.className,
+          index === _this.items.length - 1  ? 'last'     : '',
+          itemData.disabled                 ? 'disabled' : '',
+          itemData.selected                 ? 'selected' : ''
         ]),
-        $.isFunction(itemBuilder) ? itemBuilder(elm, elm.element, i) : _this.utils.format(itemBuilder, elm)
+        $.isFunction(itemBuilder)
+          ? _this.utils.format(itemBuilder(itemData), itemData)
+          : _this.utils.format(itemBuilder, filteredItemData)
       );
     },