Control Scripts

Control Scripts are scripts that affect the output of a template per record as a whole, instead of parts of the content. They are executed before the data is merged and can be used to control how different sections of the context are handled when the output is generated.

With a control script you can, among other things:

• Conditionally omit sections from print output
• Dynamically set the background image of a section
• Make the page numbering continue over all print sections
• 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.

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

This topic explains how to add a Control Script, how to use a Control Script to change the page numbering in Print output, and how to write a Control Script that splits one generated document into multiple files or attachments.

For examples and for more uses of Control Scripts, see the sample scripts in the Control Script API: Sample scripts.

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 New 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.
4. Write the script; see the Control Script API. If you are not familiar with scripting, also see Write your own scripts.

   Note: a newly added Control Script contains code to continue page numbering over all print sections, and two examples: one to select different sections of a Print context for an email and for print output, and one to select a web section.

Page numbering

Page numbering starts with page 1 for each section by default. If for a section restartPageNumbering is set to false (see Control Script API), that section will start with the page number following the last page of the previous section.

Assume that a template has four sections in the Print context and a Control Script sets the page numbering as follows:

1. Section A (1 page) restartPageNumber = true
2. Section B (1 page) restartPageNumber = true
3. Section C (1 page) restartPageNumber = false
4. Section D (1 page) restartPageNumber = true

the page numbering in the output will be:

1. Section A page 1
2. Section B page 1
3. Section C page 2
4. Section D page 1

Note that even if a section is not enabled, its restartPageNumber flag is still taken into account for composing the page number sequences. So, if the restartPageNumber flags are set as follows:

1. Section A (1 page) restartPageNumber = true
2. Section B (2 pages) restartPageNumber = false
3. Section C (3 pages) restartPageNumber = true, enabled = false
4. Section D (4 pages) restartPageNumber = false

the page numbering in the output will be:

1. Section A page 1
2. Section B page 2
3. Section D page 1 (page numbering is restarted due to section C's restartPageNumber = true)

This allows a first section in a page sequence range to be optional without further scripting.

To mimic behavior of earlier software versions each section has restartPageNumber = true by default when the first control script runs.

Parts: splitting one generated document into multiple files

In a Control Script, parts can be defined to determine which sections should be output to the same file. This way it is possible, for example, to split the Print context or the Web context into multiple email attachments.

Defining parts is done by setting the part field on a section; also see Control Script API.

• If a part name is given, then that delimits the start of a new part.
• A part ends at the last enabled section or at the last section before the start of a new part.

If no part name is set on any section, it is assumed that there is only one part, consisting of the default section (for Web and Email output) or of all sections (for Print output).

Example 1: no parts defined

Assume there are three Print sections: sections A, B and C. When generating Email output with the Print context as attachment, all three Print sections will be put together in one file and attached to the email.

Example 2: 2 parts

Assume there are three Print sections: sections A, B and C. In a Control Script a part name is defined for section C:

var section = merge.template.contexts.PRINT.sections['Section C'];
section.part = 'Part2';

When generating Email output with the Print context as attachment, the email will have two attachments:

• attachment 1: Section A, Section B
• attachment 2: "part2", which is Section C. The file name of this attachment is the part name.

Print section background

In the Print context, a PDF file can be used as a section's background (see Using a PDF file as background image).

In a Control Script, you can do the same, and more: you could for example specify a particular PDF file as a section's background, depending on the value of a field in the current record.

The Control Script should first enable a background, in case an initial background wasn't set via the user interface. Enabling a background is done by setting the source type for the background of the section to either a DataMapper PDF or an arbitrary PDF. For an arbitry PDF, the Control Script should specify a path.
After that, the background can be positioned, setting the section's background.position to ABSOLUTE or to FIT_TO_MEDIA.

For examples, see the Control Script API: Sample scripts.