(:Description Handy Client-side Table of Contents:)
(:keywords headings :)
>>recipeinfo<<
Summary: {$Description}
Version: 20070218
Prerequisites: PmWiki version 2.1.27
Status: stable
Maintainer: [[~Kathryn Andersen]]
Categories: [[!TOC]], [[!Markup]]
File: Attach:handytoc.zip
(:if exists {$Name}-Talk:)Discussion: [[{$Name}-Talk]](:ifend:)
>><<
!! Questions answered by this recipe

How can I create a table of contents for included files?
How can I create a table of contents for a page whose content is generated via pagelist?

!!Description

Most of the existing table-of-contents recipes have this limitation: they can only generate a table of contents from the information in the source of the page they're used in.  If data is included later (either with [=(:include :)=], or, even more tricky, with [[IncludeUpload]]) then they don't have the data to base
the table-of-contents on.

This recipe solves that problem by generating the table-of-contents with JavaScript, which is run after the page has finished loading,
so all the data is there.

Of course, the downside is that it requires JavaScript to be turned on; which many users and browsers may not.
Caveat emptor.

!! Notes

!!!Activation

To activate this recipe, unzip the archive; this will create a handytoc-(version) directory;
you then need to move or copy the contents of this into your pmwiki directory.
The directory contains:
:'''cookbook/handytoc.php''':File contains markup and functions.
:'''pub/handytoc/''':Directory contains CSS and JavaScript files.

Add the following line to your local/config.php:

[@
include_once("$FarmD/cookbook/handytoc.php");
@]


!!!Usage

The simplest usage is to just put the [@(:htoc:)@] directive on the page where you want to have a table-of-contents.

You can add a title to your table of contents simply by adding it to the directive:

[@
(:htoc This is my table of contents:)
@]

There are also options.

||'''Option'''||'''Example'''||'''Description'''||
||start||start=2||What level of header the table of contents starts at||
||end||end=3||What level of header the table of contents ends at||
||ignoreh1||ignoreh1=true||The ignoreh1= option can be either true or false.  If true, then if there is only one H1 header in the content, then it will be ignored.  If false, it won't be (providing that the start option equals 1).||
||class||class=htoneline||set the class name for the div that the table of contents is inside.  Useful for additional CSS styling for different kinds of ToCs.||

!!!!Examples

[@
(:htoc start=2:)
@]
The above will start with h2 headers.

[@
(:htoc end=3:)
@]
The above will end at h3 headers.

Note that if there are no H1 headers inside the content at all, then the table-of-contents will start at level 2
automatically, even of the headers are in an odd order.

!!!Configuration variables

These can be set in local/config.php

||'''Name'''||'''Description'''||'''Default'''||
||$HandyTocStartAt||Define the (default) level the table-of-contents starts at||1||
||$HandyTocEndAt||Define the (default) level the table-of-contents ends at||6||
||$HandyTocIgnoreSoleH1||If 'true', then if there's only one h1 header in the content, it will be ignored.||'true'||
||$HandyTocPubDirUrl||Url of directory where the HandyToc css and js files are||$FarmPubDirUrl/handytoc||

!!!CSS Styling

The table of contents is put inside a div with id='htoc', and the table-of-contents title (if there is one) is put
in a H3 header.  While the recipe comes with its own CSS styling (in pub/handytoc/handytoc.css) this can
be overridden with your own custom CSS in pub/css/local.css

If the "class=" option is used, then the class is set for the ''same'' div; that is, it will be

    <div id="htoc" class="classname">

so keep that in mind when using this option.

There is also a .htoneline (handy-toc one line) class in the CSS file, which can be used (with the "class=" option)
to make the table-of-contents all on one line, with | separators between each item.  This is useful for
pages where the headers are, say, single letters of the alphabet (as may happen with indexes).
The CSS for this, however, may not work in less-advanced browsers.

!!!Limitations

This does not have a show/hide button like some of the other TOC recipes; if it's defined for that page,
then it's there all the time.
If you want to show and hide the toc, you can use the [[Show Hide]] recipe with markup such as the
following:

[@
(:showhide init=hide div=htoc lshow='Show Table of Contents' lhide='Hide Table of Contents':)
@]

Note that this recipe will not work if the skin you are using does not have <!--HTMLFooter--> markup in it.

!! Release Notes

%comment% If the recipe has multiple releases, then release notes can be placed here.  Note that it's often easier for people to work with "release dates" instead of "version numbers".
* (2007-02-18) Added "class=" option, and .htoneline CSS class
* (2007-02-17) Put the JavaScript calls into $HTMLFooterFmt only if the markup is present.
* (2007-02-11) Added $HandyTocIgnoreSoleH1 and ignore=h1
* (2007-02-08) Now only looks inside #wikitext (page content); also fixed problems with different header levels in random order.  Now XHTML compliant!
* (2007-02-07a) fixed overlooked bug (forgot to rename something)
* (2007-02-07) Initial version

!! Comments
(:if false:)
This space is for User-contributed commentary and notes.
Please include your name and a date along with your comment.
Optional alternative:  create a new page with a name like "ThisRecipe-Talk" (e.g. PmCalendar-Talk).
(:if exists {$Name}-Talk:)See Discussion at [[{$Name}-Talk]](:if:)
Russell Montgomery 10/11/2011 - The zip file indicates the version is 20070217 not 20070218

!!!Markup issue
'''[[~SteP]] 2010-11-21:''' Thanks for this recipe. Version 20070218 doesn't like mixing [@(:htoc:)@] with other markup on a single line. To remove this limitation change the code as follows:
[@
Markup("handytoc", "directives", 
  "/\\(:htoc\s*(.*?):\\)/e",  //added ? after *
  "HandyTocProcessMarkup(\$pagename, '$1')");
@] 

!! See Also

(:pagelist link=Category.TOC name=-{*$FullName}:)

!! Contributors


!! Sandbox

(:htoc:)