caphList

jQuery.fn. caphList

A jQuery plug-in which provides a high performance scrollable list component. This plug-in creates container and wrapper element to arrange the item view, and calculates the item view count per a page to fit container size, and then creates current, previous and next page. The item views in each page are updated by the given template view and item data, and then they are arranged to the corresponding position on each page. This plug-in updates the item views in each page when moving to the previous or next page by scrolling the wrapper element to previous or next position.

You can create it easily by only setting options and template view. Note that the template view should be a focusable.

At first, prepare data to be decorated. Usually use AJAX to request the data. (Refer to the details in http://api.jquery.com/jQuery.get/.)

 var items;

 $.get('/someUrl', function(response) {
     items = response;
 });

And then, define a template view to decorate the items in the list.

 <div id="list1"></div> <!-- container element -->

 <!-- template view -->
 <script id="template1" type="text/template">
     <div class="item" focusable><%= index %></div> <!-- you can also use each object of array throughout 'item' variable. e.g. <%= item.title %> -->
 </script>

This plug-in instantiates a template once per item from a collection. Each template instance gets its own scope, where the 'item' variable is set to the current collection item, and 'index' is set to the item index. Special properties are exposed on the local scope of each template instance, including:

type variable description
Object item the current collection item.
number index iterator offset of the repeated element (0..length-1).
boolean first true if the repeated element is first in the iterator.
boolean last true if the repeated element is last in the iterator.
boolean even true if the iterator position index is even (otherwise false).
boolean odd true if the iterator position index is odd (otherwise false).

Refer to the template syntax details in https://lodash.com/docs#template.

Finally, create a 'caphList' using the prepared resources such as 'items' and 'template1'.

 $('#list1').caphList({
     items: items,
     template: 'template1'
 });

After initializing, each element has an initialized instance 'caphList' as property. You can refer to the instance and use helpful methods.

 $('#list1').caphList({
     ...
 })[0].caphList.resize();

The followings are all available methods.

method description
update() Update the item views. You should call this method to update item views when appending new data to collection or removing the existing data from the tail of collection. This method will update only visible item views if necessary.
reload() Update the entire item views. If you change the all data of collection, you should call this method to update item views.
resize() If you change the list size manually, you should call this method. The window's resize event is processed automatically.
moveLeft() Move to the left item.
moveRight() Move to the right item.
moveUp() Move to the up item.
moveDown() Move to the down item.

The above example creates a list with the following structure.

 <div id="list1" class="caph-list-container"> <!-- container -->
     <div class="caph-list-wrapper> <!-- wrapper -->
         <div>
             <div class="item" focusable>0</div> <!-- template view -->
            </div>
            <div>
             <div class="item" focusable>1</div> <!-- template view -->
         </div>
         <div>
             <div class="item" focusable>2</div> <!-- template view -->
         </div>
         ...
     </div>
 </div>

By default, the scroll direction is 'horizontal'. If you want to change the scroll direction to vertical, set the 'direction' option to 'vertical'.

 $('#list1').caphList({
     items: items,
     template: 'template1',
     direction: 'vertical'
 });

You can also change the class name of container and wrapper.

 $('#list1').caphList({
     items: items,
     template: 'template1',
     containerClass: 'container',
     wrapperClass: 'wrapper'
 });

Then, you can see a list with the following structure.

 <div id="list1" class="container"> <!-- container -->
     <div class="wrapper> <!-- wrapper -->
         ...
     </div>
 </div>

Note that container and template view should have their own size such as width and height. Because this plug-in arranges the views based on that sizes. Suppose that style is defined like below.

 .container {
     width: 1000px;
     height: 600px;
 }

 .item {
     width: 100px;
     height: 200px;
 }

If you create a 'caph-list' like below, its row count will be 3 and column count will be 10.

 $('#list1').caphList({
     items: items,
     template: 'template1',
     containerClass: 'container'
 });

So if your data count is greater than 30, you can scroll the list horizontally after reaching the last column.

You can change the scroll effect by setting 'duration' and 'ease' option. These option values are same as CSS3 transition value. Refer to the 'transition-duration' and 'transition-timing-function' in http://www.w3schools.com/css/css3_transitions.asp.

The followings are all available options.

type option description
Object[] items The data to be decorated to the views. Note that it can't be used together with itemLoader option.
string itemLoader The item loader to request required data to be decorated to the views. You can specify the item loader name which is registered to the jQuery.caph.ui.listItemLoaderProvider. Each template instance gets its own scope, where the 'item' variable is set to the current collection item. Special properties are exposed on the local scope of each template instance like using items option. Note that it can't be used together with items option.
string template The template to be used when decorating the views. You can use template element id or HTML. You can use the https://lodash.com/docs#template syntax in the template definition.
string direction The scroll direction such as 'horizontal' and 'vertical'. Default value is 'horizontal'.
string containerClass The container element's class name. Default value is 'caph-list-container'. You have to set the size such as 'width' and 'height'.
string wrapperClass The wrapper element's class name. Default value is 'caph-list-wrapper'.
string duration The scroll duration. Default value is '0.5s'. Refer to the details in http://www.w3schools.com/cssref/css3_pr_transition-duration.asp.
string ease The scroll timing function. Default value is 'ease-out'. Refer to the details in http://www.w3schools.com/cssref/css3_pr_transition-timing-function.asp.
boolean loop The continuous circular loop mode. Default value is false. If this option is set to true, move to the first item view when moving to the next item view on the last item view. The opposite situation is same. This option can't be used with itemLoader option.
number delay The millisecond which indicates the scroll delay time. Default value is 100.
number initialItemIndex The initial item index. Default value is 0. This value should be less than the item count.
number mouseScrollAreaSize The mouse scroll area pixel size. Default value is 20. If the mouse pointer is located from the edge of the list container up to as much as mouse scroll area pixel size, the list is scrolled to the corresponding direction.
number pageBufferSize The page buffer size. One page consists of the number of visible item views. It prepares the previous and next page just as much as the given page buffer size to scroll wrapper smoothly. Default value is 1.
Function onDecorateItemView The callback handler which is called after decorating an item view using template. This callback handler receives one parameter which contains each item view's element and scope.
Function onFocusItemView The callback handler which is called when an item view is focused. This callback handler receives one parameter which contains current list indices such as item index, row index, column index, page index, maximum page index, item count and item view count per page.
Function onReachStart The callback handler which is called when reaching the item view at the very left or top. This callback handler receives one parameter which contains current list indices such as item index, row index, column index, page index, maximum page index, item count and item view count per page.
Function onReachEnd The callback handler which is called when reaching the item view at the very right or bottom. This callback handler receives one parameter which contains current list indices such as item index, row index, column index, page index, maximum page index, item count and item view count per page.
Function onScrollStart The callback handler which is called when the scroll is started. This callback handler receives one parameter which contains current list indices such as item index, row index, column index, page index, maximum page index, item count and item view count per page.
Function onScrollFinish The callback handler which is called when the scroll is finished. This callback handler receives one parameter which contains current list indices such as item index, row index, column index, page index, maximum page index, item count and item view count per page.