Control Script: Setting a Print section's background

In the Print context, an image file can be used as a Print section's background; see Using a PDF file or other image as background.

If you want the section background to be switched automatically, depending on the value of a data field, you need a Control Script. There is a Script Wizard that can generate that script for you, provided that certain conditions are met; see: Dynamic Print section backgrounds.
Otherwise, you will have to write the Control Script yourself. This topic explains how to write a Control Script that sets a Print section's background.
Note that the settings made in a Control Script take precedence over the settings made in the Print Section Properties dialog.

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

Note: Any non-content features in the original PDF will get stripped out of the original PDF. These include document navigation (outline), local links, hyperlinks, annotations (markup annotations, comments, etc.), digital signatures, multimedia features, interactive forms, and tagged PDF features (marks in the page content will stay, but the logical structure is gone).

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 Resource PDF (see BackgroundResource). For example:

Copy

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

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

For a Resource PDF, the Control Script should specify a path, for example:

Copy

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

Note: 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:

Copy

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:

Copy

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.

Tip: 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()).

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

Copy

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:

Copy

activeSection.background.position = MediaPosition.FIT_TO_MEDIA;