jQuery List Plugin

Sam Sehnert, Phil Taylor 1.2.1 (changelog) © Digital Fusion 2012, MIT

This is a jQuery plugin which allows the user to create a list with floating headings while scrolling, a-la iOS & iCal day view. The plugin allows arbitrary markup of the header and list items, and will work nicely with nested elements.

Contents

Getting Started

Here is the simplest possible implementation:

$('dl').list();

Here is some basic html you might use for your list:

<dl> <dt>Title</dt> <dd>Item One</dd> <dd>Item Two</dd> <!-- Etc... --> </dl>

Demos

Configuration Properties

PropertyDefaultDescription
headerSelectordtThe jQuery selector used to identify header elements.
zIndex1The zIndex for the floating header elements. Should be greater than all body parts.

Header Selector.

You can use any jQuery selector in order to define which elements are considered list headers. All other elements in the list are considered body elements.

$('dl').list({ headerSelector : 'li.header' }); <ul> <li class="header">Title</li> <li>Item One</li> <li>Item Two</li> <!-- Etc... --> </ul>

Events

EventParametersDetails
headingChangeEvent, Index, ElementThis event will be triggered whenever the heading changes to a new category.

headingChange

Triggered when the list title is completely visible when scrolling up, and completely hidden when scrolling down. The event will pass the event object as the first parameter, the index of the heading element in the heading collection (i.e., 2 for the second heading element), and the actual heading element itself.

$('dl').list().bind('headingChange',function( event, index, heading ){ /* Do something */ });

Methods

MethodReturn ValueDescription
.list( 'option', [ Object ] )
.list( 'option', [ String, String ] )
jQuery
String
Takes a config object, or config string/value and applies the configuration option to the calendar.
.list( 'version', [ Object ] )StringReturns the version number of the currently installed list plugin.
.list( 'destroy' )jQueryRemoves the list from the targeted element, and returns the element to its pre-initialisation state.
.list( 'header' )IntegerGets the index position of the header (relative to the headers collection).
.list( 'scrollTo', Integer )
.list( 'scrollTo', Integer, [ Mixed ] )
jQueryCall to scroll the list to the top of a specific heading index, optionally animating the scroll.

Compatibility

This plugin has been tested, and verified working in the following browsers with JavaScript enabled.

jQuery Browser Compatibility