Generated Content: Table of Contents

Features and limitations

The TOC is generated using H1-H9 tags from the original document; you don't need to do anything specific with these tags, they're included automatically. If you've enabled hyperlinks rendering, TOC items will be clickable, pointing to the appropriate pages.

TOC may be placed at the beginning or at the end of the document on separate page or it may be inserted at the appropriate place in the document. In the latter case you should insert the following code in the document:

<div id="html2ps-toc"></div>

If this DIV is not empty, TOC will be rendered after content (it is not replaced).

Note that TOC feature will not work in batch mode from the same reasons page numbering doesn't. In batch mode TOC will be generated for each document in batch.

How can I control TOC appearance?

TOC appearance may be controlled by following CSS selectors:

.html2ps-toc	Applies to the TOC as a whole
.html2ps-toc-wrapper	Applies to every TOC item
.html2ps-toc-L-wrapper	Applies to TOC item of the given level of nesting
.html2ps-toc-name	Applies to the textual TOC item name
.html2ps-toc-L-name	Applies to the textual TOC item name on the Lth level of nesting
.html2ps-toc-page	Applies to TOC page number
.html2ps-toc-L-page	Applies to TOC page number on the Lth level of nesting
#html2ps-toc-X	Applies to Xth TOC item as a whole
#html2ps-toc-name-X	Applies to Xth TOC item name
#html2ps-toc-page-X	Applies to Xth TOC item page number

Note that every TOC item may be represented by a following code:

<div id="html2ps-toc-X" class="html2ps-toc-wrapper html2ps-toc-L-wrapper">
<div id="html2ps-toc-name-X" class="html2ps-toc-name html2ps-toc-L-name">NAME</div>
<div id="html2ps-toc-page-X" class="html2ps-toc-page html2ps-toc-L-page">PAGE NUMBER</div>
</div>

How can I generate TOC using the webinterface?

Provide 'toc' parameter (set the "Table of contents" flag) and choose one of 'after', 'before' or 'placeholder' values for 'toc-location' parameter (select appropriate value from "Place TOC at" pull-down).

How can I generate TOC using API?

Use the following PHP code:

$pipeline->add_feature('toc', array('location' => $location_code);

where $location_code should contains one of the 'after', 'before' or 'placeholder' values.

How can I override the default TOC generator behaviour?

You may override the following:

items being selected as TOC items;
how document is being modified (the place TOC is added to);

First of all, access the feature object:

$toc_feature =& FeatureFactory::get('toc');

(note that it is bad-bad-bad idea to create feature objects by yourself; use FeatureFactory factory class instead).

After this, you may use 'set_anchor_locator' and 'set_document_updater' to override these behaviours. Both methods accepts single parameter: an behaviour (strategy) object. It should implement one 'run' method taking $toc_box (preparent document element for the TOC), $media and $document as parameters. Anchor locating strategy object should return an array, every element of which is an associative array containing the following items:

'name' — TOC item text
'level' — nesting level
'anchor' — ID of the target element
'element' — target element itself

Document updater strategy object does not need to return anything.

For sample code refer to features/toc.php file.