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 String

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

*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

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.

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:

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";
}
}
For another example, see this how-to: Output sections conditionally.
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);
}
  
  • Last Topic Update: 24/01/2017 09:32
  • Last Published: 7/6/2017 : 9:49 AM