You are here: start » toc

Table of Contents (TOC)

The term “TOC” is commonly used in the CMSimple_XH community to refer to the main navigation menu of a site. If you're using a ready-made template there's not much to say about it—just use it. If you want to modify the navigation of an existing template or create your own, read on.

Basic Variations

Plain toc()

The most basic way to create the TOC is to call toc() in the template:

<?php echo toc();?>

This shows a collapsed menu where only the currently selected branch is expanded.

Limited toc()

You can add two additional parameters to the call of toc(): the starting and ending level for the menu. This way you can limit the menu levels that will be shown in the menu. A common use case is to display the top level page links only in a horizontal menu:

<?php echo toc(1, 1);?>

In addition to this you can have a (vertical) submenu for the subpages of the current page via:

<?php echo toc(2, 3);?>

Here is plenty of room for your creativity.

Advanced toc()

The code that creates the TOC is split in two parts: function li() outputs the actual (X)HTML and function toc() builds the list of pages to be displayed and calls li() with this list. Since CMSimple_XH 1.5.4 it's possible to write an own function that will be used instead of li(). You just have to add it as third parameter to toc():

<?php echo toc(null, null, 'my_li');?>

You can get pretty fancy when writing your own li(), but a common use case is to make only a slight variation to the existing li(). To ease future updates/upgrades, make a copy of li() store it in userfuncs.php, rename and modify it. Then change your template to call your own li(). This way it won't get overwritten, when you install a new version of CMSimple_XH.

li()

Using toc() will only output the (X)HTML of those pages that can be seen in the partially expanded tree view of the TOC. This is not suitable for dropdown menus, where all pages have to be written to the (X)HTML. To cater for that you can use the following idiom:

<?php echo li($hc, 'menulevel');?>

Of course you can use this for “static” menus (as opposed to dropdown menus), too.

Advanced Features

There a some AddOns available which can replace toc()/li() to give you advanced features. You may want to check them out: Advanced TOC, dhtml_menu, flashTOC, xTOC and xTOC28.

Styling

toc()/li() emits the TOC as nested unordered lists (<ul>), where each menu item is a list item (<li>). The labels are rendered as <a>, except for the currently selected page, whose label is rendered as <span> (it is just text inside its <li> in CMSimple_XH before 1.6). This structure is quite customary for menus and can be easily stlyed with CSS (there are a lot of tutorials out there which will help, even if they're not particularly related to CMSimple_XH).

Besides this structure, CMSimple_XH sets a class for every menu item (<li>): .doc, .docs, .sdoc or .sdocs. .doc/.sdoc is set for leaves (i.e. pages without subpages); other menu items get .docs/.sdocs. You can use these classes to indicate to visitors where to look for subpages. .sdoc/.sdocs marks the currently chosen page and its superpages (see Configuration); other menu items get the class .doc/.docs. This is useful to highlight the viewed page(s) in the TOC.

Configuration

Under Settings→CMS you'll find several options related to the TOC.

Menu→Sdoc may be set to “parent” or left blank. In the latter case only the very page that is viewed is marked in the TOC (gets the class .sdoc resp. .sdocs); in the former case the complete path of pages down to the selected one is marked this way, what is particularly reasonable for dropdown menus.

Show_hidden→Pages_toc may be left blank or set to “true”. Only in the latter case hidden pages will show up in the TOC, when they are currently viewed.

Menu→Color and Menu→Highlightcolor may work with some templates, but don't rely on it. If in doubt, try it out.

 
You are here: start » toc
Except where otherwise noted, content on this wiki is licensed under the following license: GNU Free Documentation License 1.3
Valid XHTML 1.0 Valid CSS Driven by DokuWiki