mPDF Manual – HTML control tags

pagebreak

(mPDF ≥ 1.0)

pagebreak — Add a new page

Description

<pagebreak$orientation ] [ $type ] [ $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 ] [ $page-break-type ] />

Add a new page to the document. All properties set by a pagebreak will continue on subsequent pages until reset.

The attribute $type can specify certain conditions which determine how many pages are added. If writing a DOUBLE-SIDED document, a conditional page-break ($type = "E" or "O") will add a new page only if required to make the current page match the type (i.e. ODD or EVEN); a page-break with $type = "NEXT-ODD" or "NEXT-EVEN" will add one or two pages as required to make the current page match the type (i.e. ODD or EVEN).

Number of pages added:

    DOUBLE-SIDED
$type SINGLE-SIDED Currently ODD page Currently EVEN page
BLANK 1 1 1

'O' or 'ODD'

0 0 1

'E' or 'EVEN'

0 1 0

'NEXT-ODD'

1 2 1

'NEXT-EVEN'

1 1 2

Attributes

$orientation = L|P|landscape|portrait

This attribute specifies the orientation of the new page.

BLANK or omitted leaves the current orientation unchanged

Values (case-insensitive)

  • 'L' or 'landscape': Landscape
  • 'P' or 'portrait': Portrait
$type = E|O|even|odd|next-odd|next-even

If $type is specified when writing a DOUBLE-SIDED document, the page-break is conditional; a new page will only be added if necessary to meet the specified condition. 

If not writing a DOUBLE-SIDED document, a page-break $type = "E" will be ignored, whilst a page-break $type = "O' will always force a new page.

BLANK or omitted will force a new page unconditionally.

Values (case-insensitive)

  • 'O' or 'odd': Add a new page if required to make current page an ODD one.
  • 'E' or 'even': Add a new page if required to make current page an EVEN one.
  • 'NEXT-ODD': Add one or two pages as required to make the current page ODD.
  • 'NEXT-EVEN': Add one or two pages as required to make the current page EVEN.
$resetpagenum = 1 - ∞

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

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

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

Sets/resets the page numbering style (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…
$suppress = on|off|1|0

$suppress = 'on' will suppress document page numbers from the new page onwards (until $suppress = 'off' is used)

BLANK or omitted leaves the current condition unchanged.

Values (case-insensitive)

  • 1 or 'on': Suppress (hide) page numbers from the new page forwards.
  • 0 or 'off': Show page numbers from the new page forwards.
$margin-left
$margin-right
$margin-top
$margin-bottom
$margin-header
$margin-footer

Sets the page margins from the new page forwards.

All values should be specified as LENGTH in any valid CSS form.

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. NB 0 (zero) will set the margin to zero.

$odd-header-name
$even-header-name
$odd-footer-name
$even-footer-name

Selects a header or footer by name to use from the new page forwards. The header/footer must already have been defined using <pageheader>, <pagefooter>, <htmlpageheader>, or <htmlpagefooter>.

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 "" will not unset the header. Use $odd-header-value to turn the header off.

$odd-header-value
$even-header-value
$odd-footer-value
$even-footer-value

Specify whether to show or hide the named header or footer from the new page forwards. The header/footer must already have been defined using <pageheader>, <pagefooter>, <htmlpageheader> or <htmlpagefooter>.

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': Start using the selected header/footer from the new page onwards.
  • -1 or 'off': Stop using the selected header from the new page onwards.
$page-selector

Select a named CSS @page.

BLANK or omitted or leaves the CSS page unchanged.

See Using @page for more information

$sheet-size

$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"

$page-break-type = slice|clone|clonebycss

Values:

  • 'slice'- no border and no padding are inserted at a break. The effect is as though the element were rendered with no breaks present, and then sliced by the breaks afterward
  • 'cloneall' - each page fragment is independently wrapped with the borders and padding of all open elements
  • 'clonebycss' - open elements which have the (custom) CSS property box-decoration-break: clone set to “clone” are independently wrapped with their border and padding
  • BLANK or omitted - default page break type is used - as specified by defaultPagebreakType variable

Changelog

Version Description
1.3 Values NEXT-ODD and NEXT-EVEN for $type were added. Parameters $resetpagenum , $pagenumstyle and $suppress were added. 
2.0 Parameters $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 were added.
3.0 $resetpagenum changed to allow positive integers above 1
4.2 Parameter $page-selector was added
4.3 Parameter $sheet-size was added
6.0 Parameter $page-break-type was added

Examples

Example #1

<html>

Text of introduction...

<p>Text of main book...

</html>

Example #2 - Defining new margins and page orientation

<html>

Text of introduction...

<p>Text of main book...

</html>

Example #3 - Changing headers/footers

<html>
    <htmlpageheader name="myHeader2">

    <div style="text-align: center; font-weight: bold;">
        My document
    </div>

    </htmlpageheader>

    <p>Text of introduction...
    <p>Text of main book...

</html>

Notes

See Also

Fork me on GitHub