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

Using a remote Control Script

A remote Control Script is not located within your template but is located in a network folder or hosted on an external web server.

To add a remote Control Script:

  1. Right-click the Control folder on the Scripts pane, and click New > Remote Control Script.

  2. Enter a name for the file as it should appear in the Control Scripts folder. For better management, it's best to use the same filename as the remote resource.

  3. Enter the URL for the remote script, which must be a JavaScript (.js) file. If the file is located on an external web server, this must be a full URL, including the http:// or https:// prefix, domain name, path and file name.
    If the file is located on your network you can click the Browse button or enter the path and file name manually.

    The complete syntax with the "file" protocol is: file://<host>/<path>. If the host is "localhost", it can be omitted, resulting in file:///<path>, for example: file:///c:/resources/scripts/myControlScript.js.
    If the file is located on another server in your network, the path must contain five slashes after "file:".

    Note: Mapped network drives are usually not accessible to the server. Use a UNC path instead (e.g. file://///myserver/myfolder/myControlScript.js).

Tip: To refresh the remote resources in a Designer view, use the Refresh option in the menu (View > Refresh) or the Refresh button at the top of the Workspace.

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

Split and rename Print email attachments

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 Print, Web or Email 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.

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 (cloning sections)

Create a Clone Section script with the wizard: Cloning sections.

Or, create a Clone Section script manually: Clone Section scripts.

clone()

Add a header to an email

section, examples: Adding custom ESP handling instructions.

headers

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