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.

Note
This component is released for 2.3 rectangular UI. When you create this component in circular screen, layout can be shown broken because screen hide index scroll bar. In that case, we recommend to use Circular Index Scroll Bar.

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:

JS code:

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

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

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

JS code:

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

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:

HTML code:

<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>
</div>

JS code:

      (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();
         });
      }());

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:

HTML code:

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

JS code:

   (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 = {};
      });
   }());

Options

Option Input type Default value Description
moreChar string "*" more character in index scroll bar
delimiter string "," delimiter in index
index string | Array "A","B","C","D","E",(...),"V","W","X","Y","Z","1" list of letters separated by delimiter or array of letters
supplementaryIndex function null set 2depth index

Events

Name Description
select

Event triggered after select index by user

This event has "detail" object and there is "index" property in the "detail"

detail.index provides information for selected index.