Virtual List

In the Web environment, it is challenging to display a large amount of data in a list, such as displaying a contact list of over 1000 list items. It takes time to display the entire list in HTML and the DOM manipulation is complex.

The virtual list component is used to display a list of unlimited data elements. The component provides easy access to databases to retrieve and display data. The virtual list component is based on a result set which has a fixed size defined by the developer using the data-row attribute. A result set must be at least 3 times bigger than size of a clip (number of visible elements).

Table of Contents

  1. How to Create Virtual List
  2. Options
  3. Methods

How to Create Virtual List

To add a virtual list component to the application:

  1. Create a component container, which is a list element:
    <ul id="vlist" class="ui-listview ui-virtuallistview"></ul>
    
  2. Insert a virtual list HTML and JSON (virtuallist-db-demo.js) code:
    <script type="text/javascript" src="virtuallist-db-demo.js"></script>
    <script type="text/javascript" src="app.js"></script>
    <script type="text/javascript" src="../../lib/tau/js/virtuallist.js"></script>
    /* JSON DATA example in virtuallist-db-demo.js */
    var JSON_DATA =
    [
       {NAME:"Abdelnaby, Alaa"},
       {NAME:"Abdul-Aziz, Zaid"},
       {NAME:"Abdul-Jabbar, Kareem"},
       {NAME:"Abdul-Rauf, Mahmoud"},
       {NAME:"Abdul-Wahad, Tariq"}
       /* Other list items */
    ]
    
  3. Initialize the component and the list item updater function in the app.js file:
    /* Get HTML element reference */
    var elList = document.getElementById("vlist"),
        /* All config options can be found in virtual list reference */
        vlist = tau.widget.VirtualListview(elList,
        {
           dataLength: JSON_DATA.length,
           bufferSize: 40
        });
    /* Update list items */
    vlist.setListItemUpdater(function(elListItem, newIndex)
    {
       var data = JSON_DATA[newIndex];
       elListItem.innerHTML = '<span class="ui-li-text-main">' + data.NAME + '</span>';
    });
    

    The listItemUpdater attribute defines how the list element is updated depending on the data row index. If you do not define the attribute in the configuration, you can set the update feature with the setListItemUpdater() method.

    Note

    The virtual list manipulates DOM elements to be more efficient. It does not remove or create list elements before calling the list item update method. It means that the order of the <li> elements is volatile, and you must keep the list element clean from custom classes and attributes.

  4. When all configuration options are set, use the draw() method to draw the child elements and implement the virtual list:

    vlist.draw();
    
  5. When you no longer need the component, destroy it using the destroy() method:

    page.addEventListener("pagehide", function()
    {
       vlist.destroy();
    });
    

Options

The following table describes the virtual list configuration options.

Option Type Mandatory Description
dataLength Number Yes Defines the number of all data rows.
bufferSize Number No Defines the number of virtual list child elements in the result set.

The minimum value is 20 and default value is 100. As the value gets higher, the loading time increases while the system performance improves. Pick a value that provides the best performance without excessive loading time and is at least 3 times bigger than the number of displayed items on the device screen.

Orientation String No Defines the scrolling orientation. The default value is VERTICAL.

listItemUpdater Method reference Yes Defines the method which is called to draw a single list item.

The method takes the following parameters:

  • elListItem: HTML <li> element to be parsed
  • newIndex (Integer): Row index from the data set

Methods

Method Description
draw() When all configuration options are set, draws the child elements and implements the virtual list.
scrollTo(position) Scrolls the list to a defined position in pixels.
scrollToIndex(index) Scrolls the list to a defined index.
setListItemUpdater(function) Sets the list item updater function.