jQPlanize plugin for jQuery

The planize jQuery plugin adds some hierarchical data organization features to given DOM node containing HTML headings (you know, the h1 .. h6 tags).

As an example, how is hard to browse this long page without a table of content? Now click . Now, you see?

The source code and an issue tracker are hosted at Google.

See it in action!

The examples below will run on the current page HTML source code. At any time you can .

Headings enumeration for the whole document

$('html *').planize();

Headings enumeration starting from H2

$('html *').planize({ min_level: 2 });

Headings enumeration starting from H2, with a custom number suffix

$('html *').planize({ min_level: 2, number_suffix: ')' });

Headings enumeration starting from H2 headings and Table of Contents generation

$('html *').planize({ min_level: 2, generate_toc: true, toc_elem: $('#toc') });

H2 headings enumeration only, and Table of Contents generation

$('html *').planize({ min_level: 2, max_level: 2, generate_toc: true, toc_elem: $('#toc') });

Installation instructions

Installation is fairly simple. Just add these lines within the <head> tag of your HTML document: 

<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.2.6/jquery.js"></script>
<script type="text/javascript" src="http://jqplanize.googlecode.com/svn/trunk/jquery.planize.js"></script>

Note: Maybe storing your own local copy of the jquery.planize.js would be a great idea.

Basic usage

This is a jQuery plugin, so you can apply a custom method to a DOM element or a collection of DOM elements matching a jQuery selector call:

$('#myDiv').planize();        // Will match the div with the "myDiv" id in the page
$('div.pageblock').planize(); // Will match all divs with class "pageblocks"
etc.

Configuring jqplanize is done by passing a Javascript object to the planize() function:

$('#myDiv').planize({ generate_toc: true });

Here are the available configuration object parameters:

add_anchors
generates anchors for each header (automatically set to true if generate_toc is set to true)
callback
a function called when processing is finished. The toc_elem object will be passed back as an argument.
debug
prints pretty debug messages into the firebug or opera console, if available
generate_toc
generates an html unordered list containing the table of content of the document
min_level
min heading level needed to be included in toc and be renumbered (0 = all headings)
max_level
max heading level needed to be included in toc and be renumbered (0 = all headings)
number_suffix
heading identifier suffix, eg. ) in 1.2.3)
number_separator
separator for numbers, eg. . in 1.2.3)
toc_elem
the dom element where the toc will be append
toc_title
the title of the table of content

Known issues

The bookmarklet

You can drag the bookmarklet below to your personal bookmark bar, so you'll be able to generate the table of content on (quite) every page you browse on the web:

Planize this

FAQ

Why didn't you use the ordered list feature of the HTML spec?
Because it's lame.
Why the hell the code is so ugly?
This is my first jQuery plugin authoring attempt, that's maybe why.
Why didn't you use a recursive function to generate TOC subitems code?
Because parsing a linear array of headings and generating a nested list is not that easy, but I can't wait seeing your patch.
Can I send you a patch?
Of course, use the issue tracker for that purpose.
Can I report an issue?
Of course, use the issue tracker for that purpose. Try to attach a patch if you can.
Can you grant me a commit access to the subversion repository?
Send me a patch first, if I think it's cool you'll have your commit account.

License

This plugin is licensed under the MIT license. That means:

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

About me

My name is Nicolas Perriault, I'm a french developer based near Paris. Feel free to browse my blog, mainly in french.