You are here: Designer > API > Control Script API

Control Script API

When output is generated from a template, Control Scripts run before all other scripts. This topic lists features that can only be used in Control Scripts and provides some sample scripts. See Control Scripts for more information about how to use this kind of scripts.

Objects available to pre-merge scripts

Channel

This is an enumeration for the output channels. The active output channel is registered in merge.channel.

Value	Description
EMAIL	The merge request is for output to Email
PRINT	The merge request is for output to Print
WEB	The merge request is for output to Web
THUMBNAIL	The merge request is for generating a template preview

ContextType

This is an enumeration for the context types.

Value	Description
HTML_EMAIL	The context is the Email context
PRINT	The context is the Print context
WEB	The context is the Web context

Merge

The root level instance of the object merge is the entry point in Control Scripts for the objects and references required to query and modify various aspects.

Field	Type	Description
context	Context	The context rendered by this merge pass.
channel	Channel	The channel for which this merge pass is requested.
section	Section	The section being merged. Only available from non-control template scripts AND when the output channel is WEB (merge.channel == Channel.WEB) where it defines the requested page.
template	Template	Template containing the context. This field can be used to find out which contexts are available in the template.

Context

Context is an object representing the respective context in the template. Which contexts are available in the template can be queried using merge.template.contexts. The context being merged can be queried using merge.context.

Field	Type	Description
sections	Array	Array of sections inside this context defined in the template.
type	ContextType	The context type.

Template

Template is an object representing the template. Which contexts are available in the template can be queried using merge.template.contexts. The context being merged can be queried using merge.context.

Field	Type	Description
contexts	Array	Array of contexts available in the template.

Section

A section object relating to a section in the template. This type can be used to query and modify the output behavior for when the related context/section is merged.

Field	Type	Description
background	String	Print sections only. Used to set a PDF background on a Print section. See Control Script API.
enabled	boolean	Enables or disables this section for output. 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 (to emulate the behavior of previous versions): 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.
name	[READONLY] String	The name of the section as shown in the resources view. Note that sections cannot have an integer as name. The name should always include alphanumeric characters. See Renaming a section.
ownerPassword	String	Print sections only. Used to set the owner password for a PDF attachment (see Email PDF password).* 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.)
part	String	Name for the part. This is used for channels that can output separate and/or named parts. The Email output, for example, can attach 3 PDF's generated from the Print context. Part is used to specify where a new part starts and the title for the part. When used for Email attachments, the part title is used as the file name for the attachment.
password	String	Print sections only. Used to set the user password for a PDF attachment (see Email PDF password).* The user password will give limited access to the file.
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).

*The password(s) should be set on the first Print section when producing a single attachment or on the first section of each path when producing multiple ones. Each of the parts (attachments) may have a different (or no) set of passwords, thus allowing to mix secured and unsecured attachments in a single email.
Passwords set in the control script override the password set through the Email PDF password script. 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.)

BackgroundResource

This is an enumeration for the types of background resources for a Print section.

Field	Description
DATAMAPPER_PDF	A PDF file retrieved via the active Data Mapping Configuration. This can be the PDF file that was used as input file, or another type of input file, converted to PDF. From DataMapper input cannot be used in PrintShopMail Connect. The DataMapper is included only in PlanetPress Connect and PreS Connect.
NONE	No PDF background.
RESOURCE_PDF	A PDF file stored in the template or on the network. Note that it isn't possible to use a remotely stored PDF file as a section's background.

MediaPositon

This is an enumeration for the position of background resources (background.position) for a Print section.

Field	Description
ABSOLUTE	Places the PDF at a specific location on the page. Set the background's top (`background.top`) and left (`background.left`) measured from the top and left side of the section.
CENTERED	Centers the PDF on the page, vertically and horizontally.
FIT_TO_MEDIA	Stretches the PDF to fit the page size.

Pitfalls to avoid

When using merge.context or merge.section make sure to check for the appropriate conditions.

merge.section is only defined when when the output channel is Web. To make sure that it is defined, use the following if statement: if (merge.channel == Channel.WEB && merge.context.type == ContextType.WEB) { ... }.
When using merge.context.sections keep in mind that for example 'Section X' might only exist in your Print context, so using merge.context.sections['Section X'] without enclosing it in the if statement if (merge.context.type == ContextType.PRINT) {} will yield an error when the script runs for other contexts. Instead of enclosing it in an if statement, you can use the template object to access a specific context: merge.template.contexts.PRINT.sections['Section X'] .

Sample scripts

Conditionally skipping or printing Print sections

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

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

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

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

Setting the background of a Print section

The following script sets the background for a section called 'Policy' to RESOURCE_PDF and specifies a path for it, using a data value:

// Enable the section background and specify that the PDF should be read 
// from a resource file rather than using a PDF DataMapper background
merge.template.contexts.PRINT.sections['Policy'].background.source = BackgroundResource.RESOURCE_PDF;

// Specify the path
var resourceUrl = 'images/policy-' + record.fields.policy + '.pdf';
merge.template.contexts.PRINT.sections['Policy'].background.url = resourceUrl;

Positioning the background of a Print section

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