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

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

Functions

Note: For cloned sections, functions are not available.

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

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

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