Index Scroll Bar

The index scroll bar component shows on the screen a scroll bar with indices, and fires a select event when the index characters are clicked. The following table describes the supported index scroll bar APIs.

Table of Contents

1. How to create index scroll bar
2. Options
3. Events

How to create index scroll bar

For manual creation of Index Scroll Bar, you can use constructor from tau namespace:

var indexElement = document.getElementById('indexscrollbar'),
    indexscrollbar = tau.widget.IndexScrollbar(indexElement);

To add an index scroll bar component to the application, use the following code:

<div id="foo" class="ui-indexscrollbar" 
     data-index="A,B,C,D,E,F,G,H,I,J,K,L,M,N,O,P,Q,R,S,T,U,V,W,X,Y,Z"></div>

<script>
   (function() 
   {
      var elem = document.getElementById("foo");
      tau.IndexScrollbar(elem);
      elem.addEventListener("select", function(ev)
      {
         var index=ev.detail.index;
         console.log(index);
      });
   }());
</script>

You can retrieve the index value using the event.detail.index property.

In the following example, the list scrolls to the position of the list item defined using the li-divider class, selected by the index scroll bar:

<div id="pageIndexScrollbar" class="ui-page">
   <header class="ui-header">
      <h2 class="ui-title">IndexScrollbar</h2>
   </header>
   <section class="ui-content">
      <div style="overflow-y:scroll;">
         <div id="indexscrollbar1"
              class="ui-indexscrollbar"
              data-index="A,B,C,D,E,F,G,H,I,J,K,L,M,N,O,P,Q,R,S,T,U,V,W,X,Y,Z">
         </div>
         <ul class="ui-listview" id="list1">
            <li class="li-divider">A</li>
            <li>Anton</li>
            <li>Arabella</li>
            <li>Art</li>
            <li class="li-divider">B</li>
            <li>Barry</li>
            <li>Bibi</li>
            <li>Billy</li>
            <li>Bob</li>
            <li class="li-divider">D</li>
            <li>Daisy</li>
            <li>Derek</li>
            <li>Desmond</li>
         </ul>
      </div>
   </section>
   <script>
      (function() 
      {
         var page = document.getElementById("pageIndexScrollbar"), 
             isb;
         page.addEventListener("pagecreate", function(ev) 
         {
            var elem = document.getElementById("indexscrollbar1"), /* Index scroll bar element */
                elList = document.getElementById("list1"), /* List element */
                elDividers = elList.getElementsByClassName("li-divider"), /* List items (dividers) */
                elScroller = elList.parentElement, /* List's parent item (overflow-y:scroll) */
                dividers = {}, /* Collection of list dividers */
                indices = [], /* List of index */
                elDivider,
                i, idx;

            /* For all list dividers */
            for (i = 0; i < elDividers.length; i++) 
            {
               /* Add the list divider elements to the collection */
               elDivider = elDividers[i]; /* li element having the li-divider class */
               idx = elDivider.innerText; /* Get a text (index value) */
               dividers[idx] = elDivider; /* Remember the element */

               /* Add the index to the index list */
               indices.push(idx);
            }

            /*
               Change the data-index attribute to the index scroll bar element
               before initializing index scroll bar component
            */
            elem.setAttribute("data-index", indices.join(","));

            /* Create index scroll bar */
            isb = tau.IndexScrollbar(elem);

            /* Bind the select callback */
            elem.addEventListener("select", function(ev) 
            {
               var elDivider,
                   idx = ev.detail.index;
               elDivider = dividers[idx];
               if (elDivider) 
               {
                  /* Scroll to the li-divider element */
                  elScroller.scrollTop = elDivider.offsetTop - elScroller.offsetTop;
               }
            });
         });
         /* Destroy index scroll bar when page is hidden */
         page.addEventListener("pagehide", function(ev) 
         {
            isb.destroy();
         });
      }());
   </script>
</div>

The following example uses the supplementScroll argument, which shows a level 2 index scroll bar. The application code must contain a level 2 index array for each level 1 index character. The example shows a way to analyze list items and create a dictionary (secondIndex) for level 1 indices for the index scroll bar, and a dictionary (keyItem) for moving list items at runtime:

<div id="indexscrollbar2" class="ui-indexscrollbar"
     data-index="A,B,C,D,E,F,G,H,I,J,K,L,M,N,O,P,Q,R,S,T,U,V,W,X,Y,Z">
</div>
<ul class="ui-listview" id="ibar2_list2;>
   <li>Anton</li><li>Arabella</li><li>Art</li>
   <li>Barry</li><li>Bibi</li><li>Billy</li><li>Bob</li>
   <li>Carry</li><li>Cibi</li>
   <li>Daisy</li><li>Derek</li><li>Desmond</li>
</ul>

<script>
   (function() 
   {
      var page = document.getElementById("pageIndexScrollbar2");
          isb,
          index = [],
          supIndex = {},
          elIndex = {};
      page.addEventListener("pageshow", function(ev) 
      {
         var elisb = document.getElementById("indexscrollbar2"), 
             elList = document.getElementById("ibar2_list2"), /* List element */
             elItems = elList.children, 
             elScroller = elList.parentElement, /* Scroller (overflow-y:hidden) */
             indexData = getIndexData(
             {
                array: elItems,
                getTextValue: function(array, i) {return array[i].innerText;}
             });

         function getIndexData(options) 
         {
            var array = options.array,
                getTextValue = options.getTextValue,
                item,
                text,
                firstIndex = [],
                secondIndex = {},
                keyItem = {},
                c1 = null, c2 = null,
                i;
                
            for (i = 0; i < array.length; i++) 
            {
               item = array[i];
               text = getTextValue(array, i);
               if (text.length > 0) 
               {
                  if (!c1 || c1 !== text[0]) 
                  {	
                     /* New c1 */
                     c1 = text[0];
                     firstIndex.push(c1);
                     keyItem[c1] = item;
                     secondIndex[c1] = [];
                     c2 = text[1];
                     if (c2) 
                     {
                        secondIndex[c1].push(c2);
                     } 
                     else 
                     {
                        c2 = '';
                     }
                     keyItem[c1+c2] = item;
                  }
                  else 
                  {	
                     /* Existing c1 */
                     if (c2 !== text[1]) 
                     {
                        c2 = text[1];
                        secondIndex[c1].push(c2);
                        keyItem[c1+c2] = item;
                     }
                  }
               }
            }
            return 
            {
               firstIndex: firstIndex,
               secondIndex: secondIndex,
               keyItem: keyItem
            };
         }
         /* Update the data-index attribute to the index scroll bar element, with the index list above */
         elisb.setAttribute("data-index", indexData.firstIndex);
         /* Create index scroll bar */
         isb = new tau.IndexScrollbar(elisb, 
         {
            index: indexData.firstIndex, supplementaryIndex: function(firstIndex) 
            {
               return indexData.secondIndex[firstIndex];
            }
         });
         /* Bind the select callback */
         elisb.addEventListener("select", function(ev) 
         {
            var el,
                index = ev.detail.index;
                el = indexData.keyItem[index];
            if (el) 
            {
               /* Scroll to the li-divider element */
               elScroller.scrollTop = el.offsetTop - elScroller.offsetTop;
            }
         });
      });
      /* Destroy index scroll bar when page is hidden */
      page.addEventListener("pagehide", function(ev) 
      {
         isb.destroy();
         index.length = 0;
         supIndex = {};
         elIndex = {};
      });
   }());
</script>

Options

Events