# 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

- Demos
- Download
- Configuration
- Events
- Methods
- Compatibility

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

- Basic Example
- Australian Cities - Custom List Structure
- ScrollTo Method Example
- headerChange Event Example

## Configuration Properties

Property | Default | Description
--- | --- | ---
headerSelector | dt | The jQuery selector used to identify header elements.
zIndex | 1 | The 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

Event | Parameters | Details
--- | --- | ---
headingChange | Event, Index, Element | This 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

Method | Return Value | Description
--- | --- | ---
.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 ] ) | String | Returns the version number of the currently installed list plugin.
.list( 'destroy' ) | jQuery | Removes the list from the targeted element, and returns the element to its pre-initialisation state.
.list( 'header' ) | Integer | Gets the index position of the header (relative to the headers collection).
.list( 'scrollTo', Integer ) .list( 'scrollTo', Integer, [ Mixed ] ) | jQuery | Call 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.

- Safari 4+
- Chrome 9+
- Internet Explorer 8+

jQuery Browser Compatibility