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, or omit Print sections from the output.

Some functionality is provided as a Scripting Wizard, for example Conditional Print Sections.

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.

The basics of script-writing in the Designer are explained in the following topic: Writing your own scripts.

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, 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 Standard 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 for each context, but Control Scripts always go first.

  • Control Scripts do not 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.
    Similarly, the query() function, which is used to select content from within a script, is unavailable in a Control Script.

Adding a Control Script

To add a Control Script:

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

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

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

    Note: Scripts can only have the same name when they are not in the same folder.

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

    Tip: 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 it and that shows what the script should look like.

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

Dynamically set a password on PDF attachments

Control Script: Securing PDF attachments

password, ownerPassword
Include/exclude sections:
  • Conditionally omit Print or Email sections
  • Output one section or another, based on the value of a data field

Use a Conditional Print Section script to in-/exclude a Print section based on a simple condition; see section

In all other cases take a look at the examples in the following topic: section.

enabled

Copy and add sections dynamically

Dynamically adding sections (cloning).

clone()

Set the margins of a Print section or Master Page margins

margins

Set a Master Page, Media, or Duplex printing for a Print section

sheetConfig

sheetConfig

Repeat the sheet configuration after a number of pages

sheetConfig

sheetConfig.positions.repeat

Dynamically change the page size of print sections and media

section, media

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

height, width