TOCpagebreak()

(mPDF ≥ 2.0)

TOCpagebreak — Insert a table of contents in the document

Note: A new function TOCpagebreakByArray() was added in mPDF 5.0 which is recommended as much simpler to use.

Description

void TOCpagebreak ( [ string $font [, float $font-size [, int $indent [, mixed $paging [, mixed $links [, string $toc-orientation [, float $toc-margin-left [, float $toc-margin-right [, float $toc-margin-top [, float $toc-margin-bottom [, float $toc-margin-header [, float $toc-margin-footer [, string $toc-odd-header-name [, string $toc-even-header-name [, string $toc-odd-footer-name [, string $toc-even-footer-name [, int $toc-odd-header-value [, int $toc-even-header-value [, int $toc-odd-footer-value [, int $toc-even-footer-value [, string $toc-preHTML [, string $toc-postHTML [, string $toc-bookmarkText [, string $resetpagenum [, string $pagenumstyle [, string $suppress [, string $orientation [, float $margin-left [, float $margin-right [, float $$margin-top [, float $$margin-bottom [, float $$margin-header [, float $margin-footer [, string $odd-header-name [, string $even-header-name [, string $$odd-footer-name [, string $$even-footer-name [, mixed $$odd-header-value [, mixed $even-header-value [, mixed $odd-footer-value [, mixed $$even-footer-value [, string $name [, string $pageselector [, string $toc-pageselector [, string $sheet-size [, string $toc-sheet-size [, string $outdent [, int $toc-resetpagenum [, string $toc-pagenumstyle [, mixed $toc-suppress ]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]])

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.

Any values set for these are ignored, but they are kept as useless parameters to allow backwards compatibility.

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 AddPage() - using TOCpagebreak() will always continue the document on an ODD page.

Note: Page numbering is always suppressed in 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 parameter $name.

Note: If TOCpagebreak() is used 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.

Parameters

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

$font

From mPDF ≥ 5.7 CSS styles are used to control layout of ToCs. Any value set for this is ignored.

Set the font-family for the ToC.

BLANK or omitted uses default font-family for the document.

$font-size

From mPDF ≥ 5.7 CSS styles are used to control layout of ToCs. Any value set for this is ignored.

Sets the font size for the ToC in points (pt)

BLANK or omitted or 0 uses the default font-size for the document.

$indent

From mPDF ≥ 5.7 CSS styles are used to control layout of ToCs. Any value set for this is ignored.

Sets the value in millimetres to indent each level of the ToC from the left margin.

BLANK or omitted uses a default value of 5mm.

$paging = true | 1 | false | 0

Specify whether to show page numbers in the ToC.

BLANK or omitted uses a default value of true.

Default: true

Values

true or 1: show page numbers in the ToC.
false or 0: do not show page numbers in the ToC.

$links = true | 1 | false | 0

Specify whether to generate hyperlinks in the ToC.

BLANK or omitted uses a default value of false.

Default: false

Values

true or 1: show hyperlinks in the ToC.
false or 0: do not show hyperlinks in the ToC.

$toc-orientation

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.

All values should be specified as LENGTH in millimetres.

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 e.g. '<h1>Contents</h1>'. Note that in contrast with the HTML equivalent <tocpagebreak> the text does not need to use HTML-entities.

BLANK or omitted will enter no text

$toc-postHTML

Specify the HTML code to appear after the ToC e.g. '<p>Comments to go below the ToC</p>'. Note that in contrast with the HTML equivalent <tocpagebreak> the text does not need to use HTML-entities.

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'.

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-pageselector

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

$sheet-size

Can be specified either as:

string for a pre-defined page size, see values below, e.g. 'A5'
or as an array of width and height in millimetres e.g. array(210,297).

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)

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

$outdent

Set a negative indent for the last line of each ToC entry.

Values should be BLANK string or any valid CSS LENGTH.

This will cause the line to extend beyond the right margin; you can prevent this by setting PADDING-RIGHT equal to this value.

Default: 0

$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 = true | false | 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 true: Suppress (hide) page numbers in the ToC
0 or false: Show page numbers in the ToC

The rest of the parameters are defined exactly as for AddPage(). Note that these parameters 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 AddPage() for further details. But note there are differences in the order of the parameters especially take care with $orientation

Changelog

Version	Description
2.0	Function was added.
2.2	Default values for $font-size, $paging and $links were redefined.
2.3	$name attribute was added.
4.3	Parameters $pageselector, $sheet-size, $toc-pageselector and $toc-sheet-size were added
5.7	$outdent parameter added and parameters $font, $font-size and $indent redundant and ignored
6.0	Parameters added: $toc-resetpagenum, $toc-pagenumstyle and $toc-suppress

Examples

<?php
$mpdf = new \Mpdf\Mpdf();

$mpdf->WriteHTML('Introduction');
$mpdf->TOCpagebreak();

$mpdf->TOC_Entry("Chapter 1", 0);
$mpdf->WriteHTML('Chapter 1 ...');

$mpdf->Output();

TOCpagebreak()

Description

Parameters

Changelog

Examples

See Also