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.
Note that the settings made in the Control Script take precedence over the settings made in the Print Section Properties dialog.

Encrypted PDF files are not supported in PDF pass-through mode.

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 orResource 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;

An image with an unknown file extension is represented by a red cross in the output, but no error is logged unless the image refers to a local file that does not exist on disk.
Image file extensions that the software recognizes are: AFP, BMP, EPS, GIF, JPG/JPEG, PCL, PDF, PNG, PS, SVG, and TIF/TIFF.

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.

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

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

Setting a page range automatically sets background.allPages to false (see background).
On the other hand, when you first define a page range and then set background.allPages to true, this disables the page range.

You could use the resource() function to check the number of pages or for example the page height and width before setting it as a background (see resource()).

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;