tocpagebreak

(mPDF ≥ 2.0)

tocpagebreak — Insert a table of contents

Description

<tocpagebreak [ $paging ] [ $links ] [ $toc-orientation ] [ $toc-margin-left ] [ $toc-margin-right ] [ $toc-margin-top ] [ $toc-margin-bottom ] [ $toc-margin-header ] [ $toc-margin-footer ] [ $toc-odd-header-name ] [ $toc-even-header-name ] [ $toc-odd-footer-name ] [ $toc-even-footer-name ] [ $toc-odd-header-value ] [ $toc-even-header-value ] [ $toc-odd-footer-value ] [ $toc-even-footer-value ] [ $toc-preHTML ] [ $toc-postHTML ] [ $toc-bookmarkText ] [ $name ] [ $toc-page-selector ] [ $toc-sheet-size ] [ $toc-resetpagenum ] [ $toc-pagenumstyle ] [ $toc-suppress ]

[ $orientation ] [ $resetpagenum ] [ $pagenumstyle ] [ $suppress ]

[ $margin-left ] [ $margin-right ] [ $margin-top ] [ $margin-bottom ] [ $margin-header ] [ $margin-footer ]

[ $odd-header-name ] [ $odd-header-value ] [ $even-header-name ] [ $even-header-value ] [ $odd-footer-name ] [ $odd-footer-value ] [ $even-footer-name ] [ $even-footer-value ] [ $page-selector ] [ $sheet-size ] [ $outdent ] />

Add a new page to the document, marking the point at which a Table of Contents (ToC) will be inserted in the document at the end of writing. The numerous parameters specify both paging details for the continuing document, and for the ToC when it is generated.

Note: From mPDF 5.7 the layout of a table of contents can be controlled using CSS. $font $font-size and $indent have become redundant.

Note: When writing a DOUBLE-SIDED document, the ToC will always start on an ODD page. Therefore there is no option to specifiy the pagebreak $type as in <pagebreak> - using <tocpagebreak> will always continue the document on an ODD page.

Note: Page numbering was suppressed in the ToC prior to mPDF v 6.0. From v6.0 onwards, you can specify the page numbering throughout the ToC .

Note: The ToC is generated at the end of the document. Unless otherwise specified, the ToC will inherit the page margins, headers/footers and orientation of the last page written to the document.

Note: From mPDF 2.3 you can include more than one ToC in the document using the attribute $name.

Note: If <tocpagebreak> occurs at the start of a blank (ODD) page, no new page(s) will be added. This was added in mPDF 2.3 to allow a ToC to be placed on the first page, or to allow a ToC to follow another ToC.

In this case, any properties for the continuing document are ignored. If you define several ToCs following immediately on from one another, set the properties in the first ToC you define (including the $resetpagenum).

Attributes

The first set of attributes specify characteristics for the ToC, which is generated automatically at the end of the document when Output() is called.

$paging = 1|on|0|off

Specify whether to show page numbers in the ToC.

BLANK or omitted uses a default value of true.

Default: 'ON'

Values (case-insensitive)

'ON' or '1': show page numbers in the ToC.
'OFF' or '0': do not show page numbers in the ToC.

$links = 1|on|0|off

Specify whether to generate hyperlinks in the ToC.

BLANK or omitted uses a default value of false.

Default: 'OFF'

Values (case-insensitive)

'ON' or '1': show hyperlinks in the ToC.
'OFF' or '0': do not show hyperlinks in the ToC.

$toc-orientation = L|P|landscape|portrait

This attribute specifies the orientation of the ToC pages.

BLANK or omitted leaves the orientation unchanged i.e. at the end of the document (before the ToC is generated)

Values (case-insensitive)

'L' or 'landscape': Landscape
'P' or 'portrait': Portrait

$toc-margin-left

$toc-margin-right

$toc-margin-top

$toc-margin-bottom

$toc-margin-header

$toc-margin-footer

Set the page margins for the ToC.

Values can be specified using any valid CSS LENGTH e.g. px, pt, em, mm.

If you are writing a DOUBLE-SIDED document, the margin values will be used for ODD pages; left and right margins will be mirrored for EVEN pages.

BLANK or omitted leaves the current margin unchanged i.e. the margins current at the end of the document.

"0" (zero) will set the margin to zero.

$toc-odd-header-name

$toc-even-header-name

$toc-odd-footer-name

$toc-even-footer-name

Selects a header or footer by name to use for the ToC. The header/footer must already have been defined using defHeaderByName(), defFooterByName(), defHTMLHeaderByName() or defHTMLFooterByName().

If you are writing a SINGLE-SIDED document, the values for ODD will be used for all pages, and values for EVEN will be ignored.

BLANK or omitted leaves the header/footer unchanged. NB BLANK will not unset the header. Set $toc-$odd-header-value to '-1' to turn the header off.

Note: You must add the prefix html_ before the name if it is a HTMLHeader.

$toc-odd-header-value

$toc-even-header-value

$toc-odd-footer-value

$toc-even-footer-value

Specify whether to show a header or footer in the ToC. The header/footer must already have been defined using defHeaderByName(), defFooterByName(), defHTMLHeaderByName() or defHTMLFooterByName().

If you are writing a SINGLE-SIDED document, the values for ODD will be used for all pages, and values for EVEN will be ignored.

BLANK or omitted or '0' leaves the header/footer state unchanged.

Values (case-insensitive)

1 or 'on': Show the selected header/footer in the ToC.
-1 or 'off': Hide the selected header/footer in the ToC.

$toc-preHTML

Specify the HTML code to appear before the ToC.

The HTML code cannot contain any of the characters: <, >, &, ' or " and must use the appropriate HTML entities e.g. <tocpagebreak toc-prehtml="<h1>Contents</h1>">

It is recommended that you use htmlspecialchars(‘Your html code’, ENT_QUOTES) for this.

BLANK or omitted will enter no text

$toc-postHTML

Specify the HTML code to appear after the ToC.

The HTML code cannot contain any of the characters: <, >, &, ' or " and must use the appropriate HTML entities e.g. <tocpagebreak toc-posthtml="<p>Comments after the Contents table</p>">

It is recommended that you use htmlspecialchars(‘Your html code’, ENT_QUOTES) for this.

BLANK or omitted will enter no text.

$toc-bookmarkText

Specify the text as it will appear as a BOOKMARK for the ToC e.g. ‘Content list’.

The text cannot contain any of the characters: <, >, &, ' or " and must use the appropriate HTML entities e.g. <tocpagebreak toc-bookmarkText="Contents table >>">

It is recommended that you use htmlspecialchars(‘Your bookmark text’, ENT_QUOTES) for this.

BLANK or omitted will not create a BOOKMARK.

$name

Specify which ToC to include at this point, if using more than one ToC in the document. $name can be any alphanumeric characters (except just “0”) and is case-insensitive.

BLANK or omitted or 0 uses the default ToC.

$toc-page-selector

Select a named CSS @page for the ToC.

BLANK or omitted or leaves the CSS page unchanged.

See Using @page for more information

$toc-sheet-size

$toc-sheet-size can be specified either as:

a pre-defined page size,
or as two LENGTH values separated by a space, representing width and height e.g. '210mm 297mm'. em, ex and % are not accepted. Note that this is different from the ‘size’ property of the page-box used with the CSS @page selector.

Default: BLANK - makes no change to the current sheet-size

Values (case-insensitive)

'A0'-'A10', 'B0'-'B10', 'C0'-'C10'
'4A0', '2A0', 'RA0'-'RA4', 'SRA0'-'SRA4'
'Letter', 'Legal', 'Executive', 'Folio'
'Demy', 'Royal'
'A' (Type A paperback 111x178mm)
'B' (Type B paperback 128x198mm)
<LENGTH>{2} e.g. '210mm 297mm'

All of the pre-defined values can be suffixed with "-L" to force a Landscape page orientation document e.g. "A4-L"

$toc-resetpagenum = 1 - ∞

Sets/resets the document page number to $resetpagenum starting on the ToC. (The value must be a positive integer).

BLANK or omitted or 0 leaves the preceding page number sequence unchanged.

$toc-pagenumstyle = 1|A|a|I|i|[+ any value supported for list-style-type]

Sets/resets the page numbering style to use in the ToC (values as for cf. lists)

BLANK or omitted leaves the current page number style unchanged.

Values (case-sensitive)

'1': Decimal - 1,2,3,4…
'A': Alpha uppercase - A,B,C,D…
'a': Alpha lowercase - a,b,c,d…
'I': Roman uppercase - I, II, III, IV…
'i': Roman lowercase - i, ii, iii, iv…

$toc-suppress = on|off|1|0

$suppress = 'on' will suppress document page numbers in the ToC

BLANK or omitted leaves the current condition unchanged.

Values (case-insensitive)

1 or 'on': Suppress (hide) page numbers in the ToC
0 or 'off': Show page numbers in the ToC

Other attributes

The rest of the attributes are defined exactly as for <pagebreak>. Note that these attributes define page numbering, margins, headers/footers for the document as it continues from this point on; in the final document this will be the part of the document immediately after the ToC.

Please refer to <pagebreak> for further details.

Changelog

Version	Description
2.0	Tag was added.
2.2	Default values for $font-size, $paging and $links were redefined.
2.3	$name attribute was added.
3.0	$toc-bookmarkText changed to decode htmlspecialchars
4.3	Parameters $page-selector, $sheet-size, $toc-page-selector and $toc-sheet-size were added
5.7	$outdent parameter added $font, $font-size and $indent redundant
6.0	Parameters added: $toc-resetpagenum, $toc-pagenumstyle, $toc-suppress

Examples

<html>
    Text of introduction...

    <tocpagebreak />

    <tocentry content="Chapter 1" />Text of main book...
</html>

tocpagebreak

Description

Attributes

Changelog

Examples

See Also