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;

A DataMapper PDF is, as you would expect, a PDF generated by the DataMapper. A Resource PDF is a PDF from another source.

For a DataMapper PDF, nothing else has to be done to set the background. For a PDF from another source, 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 the background

After that, the background can be positioned, setting 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 is true by default and 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.start = 5;


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"; = "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;
  • Last Topic Update: 24/01/2017 09:32
  • Last Published: 7/6/2017 : 9:49 AM