Control Script: Setting a Print section's background

In the Print context, a PDF file can be used as a Print section's background. To learn how to do this without a Control Script, see Using a PDF file as background image.
With a Control Script, a Print section's background can be set dynamically. 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. This topic shows how.

For information about Control Scripts in general, see Control Scripts and Control Script API. If you don't know how to write scripts, see Writing your own scripts.

Setting a background in script

The Control Script should first enable a background on the section, in case an initial background wasn't set via the user interface. This is done by setting the source type for the background of the section to either DataMapper PDF or Resource PDF (see BackgroundResource). For example:

merge.template.contexts.PRINT.sections['Policy'].background.source = BackgroundResource.RESOURCE_PDF;

For a DataMapper PDF, nothing else has to be done to set the background. For a Resource PDF, the Control Script should specify a path, for example:

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

Positioning, scaling and rotating the background

After a background has been selected, it can be positioned, scaled and rotated, using properties of the background object; see background.

To position the background, for example, set the section's background.position:

activeSection.background.position = MediaPosition.FIT_TO_MEDIA;

For all possible positions, see MediaPosition.

Setting a page range in script

When a PDF that serves as a dynamic section background has multiple pages, you can specify a range of pages to be used, in a control script.
Put the number of the first page in the range in the section's background.start field and the last page in background.end.
This requires you to set the background.allPages option to false, first. This option takes precedence, so when it is true, the entire PDF will be used, even if a page range has been set.

The following script sets the page range from 2 to 5:

merge.template.contexts.PRINT.sections['Policy'].background.allPages = false;
merge.template.contexts.PRINT.sections['Policy'].background.start = 2;
merge.template.contexts.PRINT.sections['Policy'].background.end = 5;

Example

This scripts sets a background on a Print section using absolute positioning.

var activeSection = merge.template.contexts.PRINT.sections['Section 1'];
activeSection.background.source = BackgroundResource.RESOURCE_PDF;
activeSection.background.url = "images/somepage.pdf";
activeSection.background.position = MediaPosition.ABSOLUTE;
activeSection.background.left = "10mm";
activeSection.background.top = "10mm";

You could replace the last three lines of the previous script by the following line to scale the Print section background to Media size:

activeSection.background.position = MediaPosition.FIT_TO_MEDIA;