Lists in jqDock
As of v2.0, for either an ordered (OL) or unordered (UL) list, jqDock will construct a new Dock using each list item’s first image (or anchor surrounding that image) as a menu item, and it will return the new Dock menu element in the jQuery object, in place of the original list element.
The new Dock behaves exactly like any other Dock, and can be even be destroyed, whereupon the original list it was based on is returned to its initial state. Handlers already bound directly to images (or their parent anchors) will be transferred to the new Dock, but handlers already bound to either the list or the list items will not. The new Dock will also get the id (if there is one) of the original list, but not the class(es).
What do you need to do? In the simplest case, nothing. For example, if you had HTML along the lines of…
<ul id='menu1' class='jqDockAuto' data-jqdock-align='top' data-jqdock-labels='true'>
<li><a href='#' title='Favourites'><img src='images/favourites.png' alt='' /></a></li>
<li><a href='#' title='Pictures'><img src='images/pictures.png' alt='' /></a></li>
<li><a href='#' title='Music'><img src='images/music.png' alt='' /></a></li>
<li><a href='#' title='Videos'><img src='images/videos.png' alt='' /></a></li>
<li><a href='#' title='Uploads'><img src='images/uploads.png' alt='' /></a></li>
… then jqDock would do everything automatically for you.
- an anchor … if the sole child of that anchor is the first image within the list item, or
- the first image within the list item … if that image does not have an anchor as its parent
There is one subtle difference between list and non-list initialisation : because the conversion of a list is the first thing done by jqDock’s initialisation process, the converter will actually filter out ‘illegal’ menu items, so it is possible to end up with a Dock that contains fewer menu items than there were list items in the original list. This is slightly different to a ‘standard’ non-list initialisation, where the initialisation would simply fail to produce a Dock if it encountered any ‘illegal’ menu items.
Warning : Please be aware that the list content gets modified! The first image (or its anchor parent) in each list item gets moved to the new Dock structure. Also, if the list has an id, it gets transferred across to the element at the top of the new Dock. Note that everything gets replaced if you ‘destroy‘ the Dock.
There is also a utility that will pre-convert a list, should you have a need for it. It does not initialise jqDock, it merely builds the new Dock structure from the provided list, in the same way that the initialisation would.
// converter takes an element; if a jQuery collection is supplied, only the first element
// in the collection is used;
// it returns the original element if it is not a list or if it has already been converted;
// otherwise, it returns the element at the top of the new Dock structure
var convListElem = $.jqdock.convert( $('ul') );
// if you need to know whether or not the conversion was successful...
var isConverted = !$(convListElem).is('ul');
// you could pre-bind some handlers to the new element, and initialise jqDock...
Please note the warning above. Also, you can not ‘destroy‘ the new Dock structure unless/until it has been initialised by jqDock.