Multi-Page Content
The Drawing library enables you to generate multi-page content in PDF, prevent unwanted page-splits within specific elements, and render page templates.
For more information on how to render multi-page content with the PDF Export component, refer to its documentation.
Rendering Multi-Page Content
To render a multi-page PDF file, set multiPage: true on the Group object that you pass to exportPDF (the master group). As a result, the master group contains only Group shapes—one shape per page (page groups). Each page group inherits the PDF options that you pass to the master group, unless it overrides them individually.
A page group can override the following options from the master group:
paperSize—Sets a different paper format or size for that page.margin—Sets different page margins for that page.landscape—Rotates that page independently of the others.
If the
paperSizeoption of the master group is set to"auto"and a page group does not override it, the paper size of that page is calculated from the content of that page group alone. This means that the pages of the final document might end up with different sizes.
Manual Page Breaking
To manually specify the page breaks, use the drawDOM method which allows you to create multi-page PDF content. As a result, a page break, which matches the forcePageBreak CSS selector, occurs before each element.
Automatic Page Breaking
The drawDOM method supports automatic page breaking. To enable it, set the paperSize and margin options—content that overflows a page automatically continues on the next one. You can still combine this with forcePageBreak to manually force additional break points.
For more information, refer to the known limitations of the Drawing library and the PDF Export component.
Repeated Table Headers
When you export a long table to a multi-page PDF with drawDOM, the <thead> row appears only on the first page by default, which makes the following pages hard to read. To render the table header at the top of every page the table spans, set the repeatHeaders option to true in the DrawOptions.
This option takes effect only for multi-page output—that is, when a paperSize or a forcePageBreak selector triggers page breaking.
For more information on how to render recurrent table headers with the PDF Export component, refer to its documentation.
Page Templates
When you request multi-page output through the forcePageBreak or paperSize options, you can additionally specify a page template. The page template is inserted into each page before the output is produced and you can position it relative to the page by using CSS. The template must be a function that receives the number of the current page (pageNum) and the total number of pages (totalPages).
Preventing Page Breaking in Elements
To prevent specific elements from being split across pages, use the keepTogether option, which accepts a CSS selector that you can pass to querySelector.
In the following example, all elements with the "prevent-split" CSS class stay within the boundaries of a single page and their content is never split. If such an element falls on a page margin, it moves to the next page in full.