jQuery plugin: tocBuilder

tocBuilder is a jQuery plugin that builds a table of contents from heading tags. If you don't want to use heading tags, you can use any other tag to which you apply the CSS class 'tocEntry' and a custom attribute in the form "data-tocLevel='1'".

The plugin is applied to the div (or other element) that you want to contain a clickable table of contents. Your jQuery selector should return a single element; if your selector returns multiple elements, only the first is used.

By default, the plugin will build a table of contents from tocEntry CSS classes, levels 1-6. For example:

$('#myDiv').tocBuilder()

will locate all elements in your document that have a 'tocEntry' CSS class. For example, elements such as this:

<p class='tocEntry' data-tocLevel='1'>Level 1 heading</p>

<p class='tocEntry' data-tocLevel='2'>Level 2 heading</p>

It will use the text of each target element to create a hyperlink in myDiv element. By default, it will also append a 'back' link from each element to the TOC so that you can navigate back, although back links can be turned off using the options.

You can create multiple TOCs on separate elements. If you do this, it works best if you use different levels for each TOC, otherwise you get two 'back' links on each heading.

Downloads

tocBuilder.js, the plugin.
tocBuilder.css, associated CSS styles.

Options

backLinkText
String. The text to show on 'back' links. The default is 'Back'.: endLevel
Integer. The end level to use for the TOC. The default is 6, but if you wanted to exclude levels greater than 4 from the TOC, for example, you could change it to 4.: insertBackLinks
Boolean. The default is 'true', which causes a 'back' hyperlink to be appended to the target element. If set to 'false', no back link is inserted. Note that you can change the text of the 'back' link using the 'backLinkText' option.: startLevel
Integer. The starting level to use for the TOC. The default is 1, but if you wanted to exclude level 1 from the TOC, for example, you could change it to 2.: textCallback
Delegate. A function to be called when parsing the heading text. The function takes one argument, the jQuery object for the matched heading, and it should return a string, which is the text of the heading. If no delegate is provided, elem.text() is used.: type
String. The type of elements to use for building the TOC: set to 'headings' or 'classes'. The default is 'classes', which will locate all elements in the document that have a CSS class of 'tocEntry'. The TOC level is read from a custom attribute called 'data-tocLevel' whose value should be an integer in the range startLevel to endLevel (see below). 'headings' causes it to use heading tags.

Methods

Methods are called using the pattern recommended by the plugin authoring tutorial. That is, the method name is a string argument to the plugin. For example:

$('#myDiv').tocBuilder('disable');

Arguments are passed after the method name:

$('#myDiv').tocBuilder('disable', true);

The following methods are available:

disable | disable, true
Empties the target element of all TOC links, removes all back links, and hides the TOC element. If you specify true, the TOC element is kept visible.: init | init, options
Reinitializes the TOC. If you do not provide new options, the original ones are used, otherwise the new options are applied.: rebuild
Rebuilds the TOC using the original options. This is useful if you have dynamically changed the content of the DOM and the headings or heading text has changed.

CSS

tocBuilder assumes some CSS class names, which you can find in the tocBuilder.css download, above. The 'tocEntry' class is merely used as a selector class if you don't want to use heading tags. In addition, the plugin applies the following classes to content that it inserts into the DOM:

tocBackTarget
This is applied to the contentless A tag inserted at the top of the TOC element which is used a target for 'back' links.: tocLink
This is applied to A tags which are entries in the TOC.: tocBackLink
This is applied to the A tag back link. This needs to be styled because it is appended to the heading itself and will inherit its style.: div.tocLevel1 to div.tocLeveln
Each A tag in the TOC is wrapped in a div so that you can style the indentation and padding for the different levels. It looks best if you create a different class for each level so that the headings are distinguished.

Short Examples

The following example would create a TOC in myDiv using levels 1-6. 'tocEntry' CSS classes are used as the selector:

$('#myDiv').tocBuilder();

The following examples create two TOCs on separate divs:

$('#myDiv').tocBuilder({ type: 'headings', startLevel: 1, endLevel: 3, backLinkText:
        'Return to TOC 1' });

$('#myOtherDiv').tocBuilder({ type: 'headings', startLevel: 4, endLevel: 6, backLinkText:
        'Return to TOC 2' });

The following example would create a TOC using heading tags 1-6:

$('#myDiv').tocBuilder({ type: 'headings'});

The following example would create a TOC using heading tags 2-4, with a back link of 'Return to TOC':

$('#myDiv').tocBuilder({ type: 'headings', startLevel: 2, endLevel: 4, backLinkText:
        'Return to TOC' });

The following example would create a TOC without back links:

$('#myDiv').tocBuilder({ insertBackLinks: false });

The following example would create a TOC using standard headings but would call the tocCallback function in order to retrieve the heading text.

$('#myDiv').tocBuilder({ type: 'headings', textCallback: tocCallback });

Longer Examples

tocBuilder Examples