1<html>
2<head>
3<title>Generated Content: Table of Contents</title>
4<link rel="stylesheet" type="text/css" medial="all" title="Default" href="css/help.css"/>
5</head>
6<body>
7<h1>Generated Content: Table of Contents</h1>
8<h2>Features and limitations</h2>
9<p>The TOC is generated using H1-H9 tags from the original document; you don't need to
10do anything specific with these tags, they're included automatically. If you've enabled
11hyperlinks rendering, TOC items will be clickable, pointing to the appropriate pages.<p>
12<p>TOC may be placed at the beginning or at the end of the document on separate page or
13it may be inserted at the appropriate place <strong>in</strong> the document. In the latter
14case you should insert the following code in the document:
15<pre>
16&lt;div id="html2ps-toc"&gt;&lt;/div&gt;
17</pre>
18If this DIV is not empty, TOC will be rendered after content (it is not replaced).
19</p>
20<p>Note that TOC feature will <strong>not</strong> work in batch mode from the same reasons
21page numbering doesn't. In batch mode TOC will be generated for <strong>each</strong> document
22in batch.</p>
23
24<h2>How can I control TOC appearance?</h2>
25<p>TOC appearance may be controlled by following CSS selectors:</p>
26<table>
27<tbody>
28<tr>
29<td>.html2ps-toc</td>
30<td>Applies to the TOC as a whole</td>
31</tr>
32<tr>
33<td>.html2ps-toc-wrapper</td>
34<td>Applies to every TOC item</td>
35</tr>
36<tr>
37<td>.html2ps-toc-L-wrapper</td>
38<td>Applies to TOC item of the given level of nesting</td>
39</tr>
40<tr>
41<td>.html2ps-toc-name</td>
42<td>Applies to the textual TOC item name</td>
43</tr>
44<tr>
45<td>.html2ps-toc-L-name</td>
46<td>Applies to the textual TOC item name on the Lth level of nesting</td>
47</tr>
48<tr>
49<td>.html2ps-toc-page</td>
50<td>Applies to TOC page number</td>
51</tr>
52<tr>
53<td>.html2ps-toc-L-page</td>
54<td>Applies to TOC page number on the Lth level of nesting</td>
55</tr>
56<tr>
57<td>#html2ps-toc-X</td>
58<td>Applies to Xth TOC item as a whole</td>
59</tr>
60<tr>
61<td>#html2ps-toc-name-X</td>
62<td>Applies to Xth TOC item name</td>
63</tr>
64<tr>
65<td>#html2ps-toc-page-X</td>
66<td>Applies to Xth TOC item page number</td>
67</tr>
68</tbody>
69</table>
70<p>Note that every TOC item may be represented by a following code:<p>
71<pre>
72&lt;div id="html2ps-toc-X" class="html2ps-toc-wrapper html2ps-toc-L-wrapper"&gt;
73&lt;div id="html2ps-toc-name-X" class="html2ps-toc-name html2ps-toc-L-name"&gt;NAME&lt;/div&gt;
74&lt;div id="html2ps-toc-page-X" class="html2ps-toc-page html2ps-toc-L-page"&gt;PAGE NUMBER&lt;/div&gt;
75&lt;/div&gt;
76</pre>
77
78<h2>How can I generate TOC using the webinterface?</h2>
79<p>Provide 'toc' parameter (set the "Table of contents" flag) and choose one of 'after', 'before' or 'placeholder' values for 'toc-location' parameter
80(select appropriate value from "Place TOC at" pull-down).</p>
81
82<h2>How can I generate TOC using API?</h2>
83<p>
84Use the following PHP code:
85<pre>
86$pipeline->add_feature('toc', array('location' => $location_code);
87</pre>
88where $location_code should contains one of the 'after', 'before' or 'placeholder' values.
89</p>
90
91<h2>How can I override the default TOC generator behaviour?</h2>
92<p>You may override the following:</p>
93<ol>
94<li>items being selected as TOC items;</li>
95<li>how document is being modified (the place TOC is added to);</li>
96</ol>
97<p>First of all, access the feature object:
98<pre>
99$toc_feature =& FeatureFactory::get('toc');
100</pre>
101(note that it is bad-bad-bad idea to create feature objects by yourself;
102use FeatureFactory factory class instead).</P>
103<p>
104After this, you may use 'set_anchor_locator' and 'set_document_updater' to override
105these behaviours. Both methods accepts single parameter: an behaviour (strategy) object.
106It should implement one 'run' method taking $toc_box (preparent document element for the TOC),
107$media and $document as parameters. Anchor locating strategy object should return an array,
108every element of which is an associative array containing the following items:
109<ul>
110<li>'name' &mdash; TOC item text</li>
111<li>'level' &mdash; nesting level</li>
112<li>'anchor' &mdash; ID of the target element</li>
113<li>'element' &mdash; target element itself</li>
114</ul>
115Document updater strategy object does not need to return anything.
116</p>
117<p>
118For sample code refer to features/toc.php file.
119</p>
120
121</body>
122</html>
123