Control Scripts

When output is generated from a template, Control Scripts run before all other scripts, when a record is merged with a context. They determine how different sections of the context are handled. They can, for example, make the page numbering continue over all Print sections, split Email attachments, or omit Print sections from the output.

Some knowledge of JavaScript is needed to edit Control Scripts, just as for any other self-made scripts, because there is no Control Script Wizard; see Writing your own scripts.

This topic explains how to add a Control Script and it gives an overview of what Control Scripts can do. It will also tell you where you will find information about each feature, including examples.

What Control Scripts are

Control Scripts are a special kind of Designer script. They can manipulate the way output is generated from a template. They allow you, for example, to change the page numbering in Print output, to split one generated Print document into multiple Email attachments, or to set a Print section's background dynamically. (These are only a few examples; for more uses of Control Scripts see What to use a Control Script for.)

Control Scripts differ from template scripts in two ways:

Control Scripts run before all other scripts. When a template consists of several contexts, and these contexts are combined in the output - for example, when an Email is generated with the Print context as attachment - all scripts run once before each context; Control Scripts first.

Control Scripts don't have a selector, like the other scripts do. A selector selects parts of the content of a section and stores them in the results object, so that they can be modified in the script. As Control Scripts don't have a selector, the results object can't be used there. Control Scripts don't touch the content - meaning, the text flow - of the sections.

Adding a Control Script

To add a Control Script:

On the Scripts pane at the bottom left, click the black triangle on the New button and click New Control Script. A new script appears in the list.

Double-click the new script to open it. The script editor appears.

Change the name of the script so that it reflects what the script does.

Write the script; see the Control Script API. If you are not familiar with scripting, also see Writing your own scripts.

New Control Scripts added to the template contain code to continue the page numbering over all print sections, and two examples: one to select different sections of a Print context for email and print output, and one to select a web section.

What to use a Control Script for

Control Scripts let you change the way a template is merged, by giving access to the template with all its contexts and sections in a script. A Control Script may, for example, omit, group and clone sections; add a background to a Print section; or add a header to an email. A number of the things that you can do with them is listed in the table below, with a link to a topic that explains how to do them and that shows what the script should look like.

Control Scripts differ from template scripts in two ways:

Control Scripts don't touch the content - meaning, the text flow - of the sections. They don't have a selector, like the other scripts do. A selector selects parts of the content of a section and stores them in the results object, so that they can be modified in the script. As Control Scripts don't have a selector, the results object can't be used there.

In a Control Script, section usually is the most important object. To get a quick overview and lots of examples, see section. For help on specific tasks, see the table below.

Task

See topic

Field/function of section object

Change the page numbering of Print sections

Control Script: Page numbering

restartPageNumbering

Set the background image of a Print section

Control Script: Setting a Print section's background

background.source, background.url, background.position

Split Email attachments and rename them

Parts: splitting and renaming email attachments

part

Dynamically set a password on PDF attachments

Control Script: Securing PDF attachments

password, ownerPassword

Include/exclude sections:

Conditionally omit sections
Output one section or another, based on the value of a data field
Select one print section as PDF attachment if the output is to be emailed, and another print section if the output is to be printed.

section, take a look at the examples.

enabled

Add sections dynamically

Dynamically adding sections (cloning).

clone()

Add a header to an email

section, example: Adding custom ESP handling instructions.

headers