section

The section object can be used to query and modify how the section (and the related context) will be outputted. It is one of the most important objects in Control Scripts (see Control Scripts and Control Script API).

Retrieving a section

A section can be retrieved using merge.template.contexts.ContextType.sections["section name"], for example: merge.template.contexts.PRINT.sections["Section EN"].

A section can also be retrieved via merge.context.sections['section name']. Remember, however, that when several contexts need to be merged (for example, when the Print context is attached to an email), the script needs to check if the current context is of the type that contains the desired section (for example: if (merge.context.type == ContextType.PRINT) {}). When sections in different contexts have the same name, it is safer to use merge.template.contexts.ContextType.sections["section name"].

Fields

Field	Type	Description
background	Background	Used to set a PDF background on a Print section. See Control Script: Setting a Print section's background and BackgroundResource.
enabled	Boolean	Enables or disables this section for output (see Examples). Note that even if a Print section is disabled, the `restartPageNumber` field is still effective to define the page numbering over multiple sections when applicable. All Print sections are enabled by default. It is possible to enable different or multiple sections to control which sections will be outputted.
height	String	The height of the section using a Measurement string. For example, "11in" is 11 inches. In a Control Script this property can be used to set the height of the section. In other scripts it is only possible to get the height of the section (read-only).
html()		Gets or sets the HTML of the body element.
margins	Margins	Used to set the print margins of a section. You can set the bottom, left, right and top margin using a Measurement string; for example, "2in" sets a margin to 2 inches.
meta	Object	The `meta` object can hold additional information about a section. This property is initially empty, and reset after every record. `Meta` entries can be added in a script (preferably a Control Script). The values stored in `section.meta` can have any type; they are not converted to strings. `Meta` entries can be read in a Standard Script and in Handlebars expressions. Note: If a `meta` entry is added by a Standard Script, it cannot be accessed in a Handlebars expression, since Handlebars expressions are evaluated before Standard Scripts run.
minPages	Number	Minimum number of pages in the section. The default is 1.
name	String	Used to get or set the name of the section. Note that section names must be unique and that sections cannot have an integer as its name. The name should always include alphanumeric characters. To rename email attachments, use the field `part`.
ownerPassword	String	Used to set the owner password for a PDF attachment.* Setting only the owner password creates a secured PDF that can be freely viewed, but cannot be manipulated unless the owner password is provided. (Note that the recipient needs Adobe Acrobat to do this, because the Acrobat Reader does not allow users to enter the owner password.) See Control Script: Securing PDF attachments.
pagination	Pagination	Post Pagination scripts only. Contains the total page count, sheet count and start/end page numbers of a single section.
password	String	Used to set the user password and owner password for a PDF attachment to the same value. See Control Script: Securing PDF attachments.*
restartPageNumber	Boolean	Enables or disables a restart of the page numbering. When generating Print output this can be used to let page numbering continue over multiple sections. The default value is `false`, meaning that each section will start with page 1 (to emulate behavior of previous versions).
sheetConfig	SheetConfig	Overrides the Master Page, Media and Duplex printing options of first/middle/last/single or all sheets in a Print section.
width	String	The width of the section using a Measurement string. For example, "8.5in" is 8.5 inches. In a Control Script this property can be used to change the width of the section. In other scripts it is only possible to get the width of the section (read-only).

* The password(s) should be set on the first Print section when producing a single attachment, or on the first section of each part when producing multiple attachments. Each of the parts (attachments) may have a different (or no) set of passwords.
Passwords set in the Control Script override the password set through the Email PDF password script (see Email PDF password). This allows you to change or remove the password from a specific part. Removal is done by setting the password field to null or "" (empty string).

Note: When a Control Script changes the size of a section, it should also change the size of the linked Media; this is not done automatically. While the output may still look good, a size mismatch can cause an issue if a script or another component assumes that the media size matches the section size.
In case of a size mismatch a preflight will show a warning (see Doing a Preflight).

Batching settings

Batching improves performance and reduces memory use for templates that generate many pages per record. On the rare occasions where this may cause issues in the output, the following fields can be used to change the settings.

Field	Type	Description
batchedDOMPagesThreshold batchedPrintWindowThreshold	Integer	Cutoff point for batched pagination / batched printing. Default: 15. Batching can be disabled by setting the property to a high value (eg. 99999). Setting it to 0 causes an error.

Field

Type

Description

batchedDOMPagesThreshold

batchedPrintWindowThreshold

Integer

Cutoff point for batched pagination / batched printing. Default: 15.

Batching can be disabled by setting the property to a high value (eg. 99999). Setting it to 0 causes an error.

Functions

Note: For cloned sections, only the html() function is available.

Function	Description
clone()	Clone this section.
addAfter()	Add a cloned section after this section.
addBefore()	Add a cloned section before this section. Note that with multiple clones, the next clone is always added after the previous clone. With `addBefore()`, the code `original.addBefore(clone1); original.addBefore(clone2);` will result in "clone1, clone2, original". With `addAfter()` the code `original.addAfter(clone1); original.addAfter(clone2);` results in "original, clone1, clone2".
html()	Sets the initial HTML of the body element.
paginate()	Post Pagination Scripts only. Paginates the content of a Print section.

Examples

Conditionally skipping or printing Print sections

This script disables all Print sections and then re-enables one of them, depending on a value in the current record.

var printSections = merge.template.contexts.PRINT.sections;
printSections['Section EN'].enabled = false;
printSections['Section FR'].enabled = false;

if(record.fields.Language === 'FR'){
	printSections['Section FR'].enabled = true;
} else {
	printSections['Section EN'].enabled = true;
}

Positioning the background of a Print section

These scripts both set the background of a Print section to the same PDF, but they position it differently.

Using abolute positioning

Copy

var activeSection = merge.template.contexts.PRINT.sections['Section 1'];
activeSection.background.source = BackgroundResource.RESOURCE_PDF;
activeSection.background.position = MediaPosition.ABSOLUTE;
activeSection.background.left = "10mm";
activeSection.background.top = "10mm";
activeSection.background.url = "images/somepage.pdf";

Scaling to Media size

Copy

var activeSection = merge.template.contexts.PRINT.sections['Section 1'];
activeSection.background.source = BackgroundResource.RESOURCE_PDF;
activeSection.background.position = MediaPosition.FIT_TO_MEDIA;
activeSection.background.url = "images/somepage.pdf";