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.

Methods