customd / jquery-list

A plugin to make lists with group headers that float while-you-scroll, ala iOS contacts.

jQuery Floating/Fixed List Header Plugin

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.

• View at the jQuery Plugin Registry.

Demos

The Demos for this plugin live under the examples/ directory. Open them directly in your web browser, or view the following online examples:

• Basic Demo
• Australian States & Cities Demo
• ScrollTo Demo
• headerChange Demo

The following are Demos not included in the examples/ directory and can only be viewed online:

• Showcasing jQuery List with a fake iPhone

Documentation

Basic list setup

The basic setup will work with any standard dl element with no extra config options.

$('dl').list();

If you want to use the plugin with any other HTML structure, you can use the 'headerSelector' setting to tell the plugin what elements to use as headers.

$('ul').list({ headerSelector : 'li.header' });

Other capabilities include methods which will scroll the list to any heading, with optional animation, and a method which will report the current heading that the user sees. You can also bind to an event which will fire whenever the currently viewed heading changes.

$('dl').list().bind( 'headingChange', myFunction );

Full plugin documentation

The Documentation for this plugin lives under the docs/ directory. Open it directly in your web browser, or see the online documentation.

jquery-list's Issues

How could I have the way to manually refresh list header?

Sometime the header of the list is not correct due to some problem with scrolling or DOM caching (I found this problem on jquery mobile while page swapping).

I would like to know how can I have a function that only refresh the current header to make sure that header still update according to the list position.

Does the markup have to be exact same?

Hi there,

Excellent plugin!

However, I've got a quick question. Does the markup have to be exactly the same?

<dl>
 <dt>Heading 1</dt>
 <dd>Item 1</dd>
 <dd>Item 2</dd>
 <dd>Item3></dd>
 <dt>Heading 2</dt>
 <dd> Item 4</dd>
 <dd>Item 5</dd>
 </dl>

Or can I have a different markup like below ie. each set of dt and dd would be wrapped by a containing div?

e.g. the above would be rewritten like below

  <dl>
  <div>
    <dt>heading 1</dt>
    <dd>Item1</dd>
    <dd>Item2</dd>
     <dd>Item3</dd>
   </div>

     <div>
     <dt>heading 2</dt>
     <dd>Item4</dd>
       <dd>item5</dd>
      </div>

      </dl>

Any ideas?

Headers dont change during scrolling on iOS with -webkit-overflow-scrolling

I have noticed an issue. If you use -webkit-overflow-scrolling:touch on iOS the headers don't change until after the user has stopped scrolling. This is probably because on iOS, the scroll event only gets fired when scrolling has stopped. One solution would be to use ontouchmove/start events along with the scroll event to change the headers with animation while the user is scrolling..

When scrolling up, the header flickers on a pixel

1. 
2. 
3. 

The above screenshots show me scrolling up very slowly. Take a look at the date on them.

There's simply one pixel during the scroll that the floating tag does not respond the way it should.

Header text flickers while scrolling up the list

If you have "Header 1" and "Header 2", and have scrolled down so Header 2 is stuck to the top of the screen, when you scroll back up to the point where Header 1 displaces it, the "Header 2" text will briefly flicker to read "Header 1" and then back again.