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