Circular Index Scroll Bar

Circular index scroll bar component shows on the screen a circular indicator with an index and support to scroll.

If you spin the rotary quickly, an indicator will be displayed and you can move in an index unit.

The indicator will disappear if no rotary action is detected for a second.

This component fires a select event when the index characters are selected.

Note
This component is supported since 2.3.
This component is optimized for circular UI. The component may not be shown properly in rectangular UI.
If you want information for support to both circular and rectangular UI, see here

Table of Contents

  1. How to create circular index scroll bar
  2. Options
  3. Events
  4. Methods
    1. value

How to create circular index scroll bar

For manual creation of circular index scroll bar, you can use constructor from tau namespace:

var circularindexElement = document.getElementById('circularindexscrollbar'),
    circularindexscrollbar = tau.widget.CircularIndexScrollbar(circularindexElement, {index: "A,B,C"});

Constructor has one require parameter element which are base HTMLElement to create component. We recommend get this element by method document.getElementById.

Second parameter is options and it is a object with options for component.

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

<div id="indexscrollbar" class="ui-circularindexscrollbar"
     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("indexscrollbar");
      tau.widget.CircularIndexScrollbar(elem);
      elem.addEventListener("select", function(event)
      {
         var index = event.detail.index;
         /* Print selected index */
         console.log(index);
      });
   }());
</script>

The index value can be retrieved by accessing event.detail.index property.

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

<div id="pageIndexScrollbar" class="ui-page">
   <header class="ui-header">
      <h2 class="ui-title">CircularIndexScrollbar</h2>
   </header>
   <div id="indexscrollbar" class="ui-circularindexscrollbar"></div>
   <section class="ui-content">
      <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>
   </section>
</div>
<script>
   (function()
   {
      var page = document.getElementById("pageIndexScrollbar"),
          indexScrollbar;

      page.addEventListener("pageshow", function(ev)
      {
         var indexScrollbarElement = document.getElementById("indexscrollbar"),
             listviewElement = document.getElementById("list1"), /* List */
             listDividers = listviewElement.getElementsByClassName("li-divider"), /* List dividers */
             dividers = {}, /* Collection of list dividers */
             indices = [], /* Index list */
             scroller,
             divider,
             i, idx;

         /* For all list dividers, */
         for (i = 0; i < listDividers.length; i++)
         {
            /* Add the list divider elements to the collection */
            divider = listDividers[i];
            idx = divider.innerText;
            dividers[idx] = divider;

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

         scroller = tau.util.selectors.getScrollableParent(listviewElement);

         /* Create CircularIndexScrollbar */
         indexScrollbar = new tau.widget.CircularIndexScrollbar(indexScrollbarElement, {index: indices});

         /* Add SnapListview item "selected" event handler */
         /* You should update the information for current index */
         listviewElement.addEventListener("selected", function(ev)
         {
            var indexValue = ev.target.textContent[0];
            indexScrollbar.value(indexValue);
         });

         /* Add IndexScrollbar index "select" event handler */
         indexScrollbarElement.addEventListener("select", function(ev)
         {
            var divider,
                idx = ev.detail.index;

            divider = dividers[idx];
            if (divider && scroller)
            {
               /* Scroll to the li-divider element */
               scroller.scrollTop = divider.offsetTop - scroller.offsetTop;
            }
         });
      });

      page.addEventListener("pagehide", function(ev)
      {
         indexScrollbar.destroy();
      });
   }());
</script>

Options

Option Input type Default value Description
delimiter string "," delimiter in index
index string | Array "A","B","C","D","E",(...),"V","W","X","Y","Z","1" indices list

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.

Methods

Summary

Method Description
string value() 

Get or Set index of the circular index scroll bar

value

Get or Set index of the circular index scroll bar

string value() 

Return current index or set the index

Return value:

Type Description
string In get mode return current index value

Code example:

<div id="circularindexscrollbar"></div>
<script>
   var circularindexElement = document.getElementById("circularindexscrollbar"),
       circularIndexScrollbar = tau.widget.CircularIndexScrollbar(circularindexElement),
       /* Return current index value */
       value = circularIndexScrollbar.value();
   /* Set the index value */
   circularIndexScrollbar.value("C");
</script>