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	Print sections only. 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 Print or Web section for output (see Examples). Note that even if a section is disabled, the part and restartPageNumber fields are still effective to define the parts division and page numbering over multiple sections when applicable. The default enabled state for sections (before any control script runs) is as follows: For Web channel requests, the requested web section is enabled by default. It is possible to redirect to another section by disabling the requested section and enabling another section. For Email channel requests on the Web context, only the default section is enabled by default. It is possible to enable different or multiple sections, to control which sections will be attached to the email. For Email channel requests on the Print context all Print sections are enabled by default. It is possible to enable different or multiple sections to control which sections will be attached to the email. For Print channel requests on the Print context all sections are enabled by default.
headers	String	Email sections only. Used to set custom email headers. For examples, see Adding custom ESP handling instructions.
margins	Margins	Print sections only. 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 two 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	Print sections only. 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.
part	String	Name for the part. part is used to specify where a new part starts and the title for the part. This is used to split Email attachments. The Email output can, for example, attach 3 PDFs generated from the Print context. The part name will be used as the file name for the attachment. See Parts: splitting and renaming email attachments.
password	String	Print sections only. 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	Print sections only. 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	Print sections only. Overrides the Master Page, Media and Duplex printing options of first/middle/last/single or all sheets in a Print section.

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

Functions

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

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

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 Parts: splitting and renaming email attachments)
• Web sections A and B as separate attachment
  

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";
} else if (merge.context.type == ContextType.WEB) {
	merge.context.sections['default Section'].enabled = false; // disable whatever is the default section
	merge.context.sections['Section A'].enabled = true;
	merge.context.sections['Section A'].part = "WebPartA";
	merge.context.sections['Section B'].enabled = true;
	merge.context.sections['Section B'].part = "WebPartB";
}
}

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

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

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.

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.

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);
}