AutoAnchor Menu Standalone Usage

Usage Concepts

In general to use the script you need to perform a series of scatter-gather operations where:

Scatter will distribute named anchors to specific points of the document (e.g. to top, bottom or to header tags H1..H9
Gather will assemble menu from the scattered named anchors.

Those operations can be done several times, each scattered anchor will be gathered only once (this functionality can be overriden). Correct sequence of scatters-gathers will produce ordering within the menu.

For example:

Links to top and to bottom can be put at the beginning and/or at the end of the menu;
Links to main headers (e.g. H1) could be at the beginning of the menu and less significant (e.g. H2 etc) after that or could be mixed to produce hierarchy.

Usage Instructions

To use the script do the following:

Download script code, put it on your server and reference the script in page header;
Create headers for sections of your article (e.g. using H. tags)
Initialize AutoAnchor instance:

var a = AutoAnchorMenu(obj, options);

Where:

obj	Id or instance of the container to put generated menu into.
options	Associative array of options.

Options include:

entryMarkup	Html code for single menu entry. In it, `#anchor` will be replaced with anchor name and $title$ will be replaced with header text. Default: `<a href="#anchor">$title$</a><br/>`
entryPostfix	Html code to include after single menu entry. Will be placed after any submenu items of the menu item. No default.
levelDown	Html code that will be inserted before entry with a level lower than previous entry. Default: `<div style="margin-left:10px">`
levelUp	Html code that will be inserted before entry with a level higher than previous entry. Default: `</div>`
handledProperty	Marker variable that tells if a scattered anchor has already been handled. Changing this value after a menu has been agthered allows using second AutoAnchor Menu from already scattered anchors. Default: `autoAnchorGathered<menu sequence>`
startClass	When scattering to tag name everything before tag with this class will be ignored. Useful when page contains same `H...`tags for chrome (e.g. menu titles), not only article. Default: `auto-anchor-start-marker`
stopClass	When scattering to tag name everything after tag with this class will be ignored. Useful when page contains same `H...`tags for chrome (e.g. menu titles), not only article. Default: `auto-anchor-stop-marker`
namesFromHeaderText	Create anchor names from header texts stripping unwanted characters and replacing spaces with underscore. Please note that header texts must be unique. Default: `true`

AutoAnchor instance can be initalized during one of the following:

During the normal HTML parsing flow if menu you want to create is located after the aticle in HTML.
In domready event handler if you're using a framework that supports that (such as jQuery or MooTools).
In load event handler (not recommended).

After that:

Use the AutoAnchor instance to perform scatter-gather operations:

scatter(to, level) Scatters anchors to specific tags in the document.

to - tag name (such as 'H2') or an array of tag objects to scatter the anchors to.
level - Assign level of the future menu that entries from those anchors should take. 1 by default.

For example:
.scatter('H1').scatter('H2', 2) - will produce hierarchial menu where menu items created from H2's will be of lower level than H1.
.scatter('H1').scatter('H2') - will produce a flattened menu.

scatterTop(title, level)
scatterBottom(title, level) Scatters anchors at the top and at the bottom of the document respectively.

The following invocation will generate a menu that has links to top and to bottom and a two-level menu with links to H1 and H2:

var anch = AutoAnchorMenu();

anch.scatterTop('To top')
    .scatterBottom('To bottom')
    .gather()
    .scatter('h1')
    .scatter('h2', 2)
    .gather();