BoltWire

Toc

Docs > Extensions > Plugins > Toc

The toc plugin is designed to make it easier to create a "table of contents" menu that expands and shrinks depending on which page you are on.

This plugin actually includes several functions, but in most cases the toc function will be sufficient for your needs. If you need to use the tocgroups or toclist function, you will need to enable the plugin in your site.config page.

Here's how it works:

Suppose you have a lot of pages in some section of your site. You can create a menu that expands and contracts based on where you are by simply using the toc function and the location you want to display the menu for. Typically, you would use the current page location and put it in a side menu:


[(toc {p})]


What you will see depends on your current location, and the pages available on your site. Suppose you had the following pages:

animals
animals.cats
animals.cats.lion
animals.cats.tiger
animals.dogs
animals.dogs.chihuaua
animals.dogs.wolf
plants
plants.flowers
plants.flowers.petunia
plants.flowers.rose
plants.trees
plants.trees.maple
plants.trees.oaks

In this case, [(toc animals)] would generate its sister links (plants) and child links (animals.cats and animals.dogs), but no grand children, or nieces and nephews. This would generate a menu like this--only the links would be active:

animals
     cats
     dogs
plants

If you click on animals.cats, it would expand that part of the menu only:

animals
     cats
          lion
          tiger
     dogs
plants

If you click on plants, the animal section would close and you would see a different menu:

animals
plants
     flowers
     trees

And so on. This makes it extremely easy to navigate around a busy section of your site.

How it works

Basically it taps into a tocgroups function which takes a page like plants.flowers.rose and returns a list of groups based on its page hierarchy:

plants
plants.flowers
plants.flowers.rose

And then it runs a standard search function using args from the toc function for each of those page groups. This means any pages in those directories will be included in the output. You can customize the toc function however, by adding standard search parameters like exclude, type, count, etc.

This function then outputs the links using the indent function--and yes, you can set the offset and leader value to shift the output one or more spaces to the left, or to use something beside blank spaces.

In other words, you can create the same effect, and or modify by using the tocgroups, search, and indent functions. But it gets a bit complicated. The toc function just combines everything in one simple shortcut.

List Order

In some cases you may want to change the order of the menu (ie, non-alphabetized) and have more control over what pages are displayed. For this we create a special toclist function.

To use this, you create a list page (like info.menu) and enter only the entries you want in the menu in the exact order they should appear. Then call the toc function, specifying the current page and the list page parameters, like this:


[(toc list=info.menu page=animal.dogs)]


In this case, lets assume we had saved the following unalphabetized list of page names to info.menu:

plants
plants.trees
plants.trees.maple
plants.trees.oaks
plants.flowers
plants.flowers.petunia
plants.flowers.rose
animals
animals.dogs
animals.dogs.wolf
animals.dogs.chihuaua
animals.cats
animals.cats.lion
animals.cats.tiger

Then the markup above would produce this menu:

plants
animals
     dogs
          wolf
          chihuahua
     cats

Using this approach, you don't have to worry about pages being included you don't want to show, or the menu expanding beyond a certain point. Only pages in your list will be display, based on your location in the site, and in the order you want..

This function is actually built off a completely separate toclist function. But to avoid requiring you to load the toc plugin in your site.config page to access it, we've designed the normal toc function to call it for you automatically whenever you provide a list parameter.

Hint: to generate your menu page, try running a search like this on a temporary test page then cut and paste the output, modifying it as desired, to the page you want:


[(search group=animals*,plants* fmt={+p})]


In conclusion, it's a whole lot easier to just use this plugin than to describe how it works!