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

Functions

Note: For cloned sections, functions are not available.

Function Description
clone() Clone this section. See Dynamically adding sections (cloning).
addAfter() Add a cloned section after this section.
addBefore() Add a cloned section before this section.
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;
}

Selecting different sections for Print output and Email PDF attachment

This script selects a different Print section for output, depending on the output channel (Email or Print).

Copy
var printSections = merge.template.contexts.PRINT.sections;

if(merge.channel === Channel.EMAIL){
    printSections['Section 1'].enabled = false;
    printSections['Section 2'].enabled = true;
}

if(merge.channel === Channel.PRINT){
    printSections['Section 1'].enabled = true;
    printSections['Section 2'].enabled = false;
}

Setting the name of Email PDF attachments

This script renames the file name of an attachment by setting the part name of a section (see Parts: splitting and renaming email attachments).

Copy
var section = merge.template.contexts.PRINT.sections['Section 1'];
section.part = 'Invoice ' + record.fields['InvoiceNo'];

Controlling multiple Email attachments

The following script attaches the following sections to an email:

  • Print section 3 + 4 as attachment with continued page numbers
  • Print section 6 as separate attachment (also see Control Scripts: splitting and renaming email attachments)
if (channel == Channel.EMAIL) { // only when generating Email output
if (merge.context.type == ContextType.PRINT) {
merge.context.sections['Section 1'].enabled = false;
merge.context.sections['Section 2'].enabled = false;
merge.context.sections['Section 3'].enabled = true;
merge.context.sections['Section 3'].part = "PDFAttach1";
merge.context.sections['Section 4'].enabled = true;
merge.context.sections['Section 4'].restartPageNumber = false;
merge.context.sections['Section 5'].enabled = false;
merge.context.sections['Section 6'].enabled = true;
merge.context.sections['Section 6'].part = "PDFAttach2";
}
}

Note: For another example, see this how-to: Output sections conditionally.

Note: If the Email PDF Password Script Wizard defines a password, and a template has a Control Script that creates multiple PDF attachments, all the attachments are secured by the same password by default. Using a Control Script, you can set set different passwords for attachments; see Control Script: Securing PDF attachments.

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

See also: BackgroundResource, MediaPosition and Control Script: Setting a Print section's background.

Cloning Print sections

For background information on cloning Print sections, see: Dynamically adding sections (cloning).

Cloning a section based on the number of records in a detail table

This script creates as many clones of a section as there are records in a detail table. It assigns the new sections a unique name.

Copy
var printSections = merge.template.contexts.PRINT.sections;
var numClones = record.tables['detail'].length;
for( var i = 0; i < numClones; i++){
    var clone = printSections["Section 1"].clone();
    clone.name = "my_section_clone_" + i;
    printSections["Section 1"].addAfter(clone);
}

Cloning a section based on data and assign a background PDF

This script clones a section based on data fields. It disables the source section first and then calls the addPolicy() function. addPolicy()clones the section, renames it and sets a PDF from the resources as its background. It explicitly enables the clone and then adds it to the Print context.

Copy
var printSections = merge.template.contexts.PRINT.sections;
merge.template.contexts.PRINT.sections["Policy"].enabled = false;
if(record.fields.policy_a == 1) {
    addPolicy('a');
}
if(record.fields.policy_b == 1) {
    addPolicy('b');
}
function addPolicy(policy){
    var resourceUrl = 'images/policy-' + policy + '.pdf';
    var clone = printSections["Policy"].clone();
    clone.name = "policy_" + policy;
    clone.background.url = resourceUrl;
    clone.enabled = true;
    printSections["Policy"].addAfter(clone);
}