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.

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

Events

Methods

Summary

string value (  ) 

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();
        // sets the index value
        circularIndexScrollbar.value("C");
    </script>

Where to Go Next

• UI Component Reference