background

The background object holds the PDF background of a Print section (see section and Control Script: Setting a Print section's background).

Setting a page range using the start and end fields automatically sets background.allPages to false.
When you first define a page range and then set background.allPages to true, the page range will be disabled.

Fields

Field

Type

Description
allPages Boolean Show all pages from the PDF.
end Number The end page of the PDF to use as a background for the section.
left Measurement The left offset of the PDF background (only when absolute positioning is selected).
position MediaPosition Set the position of the PDF background (Absolute, centered, fit to media).
rotation Number Set the rotation of the PDF background to 0, 90, 180 or -90 degrees.
scale Number or Object

Set the size of the PDF background as a percentage of the original image. Accepted values are:

  • A numeric value.

  • A string containing a number and percentage character: "<number>%".

  • An object with two properties, "x" and "y", with numeric values: "{ x: 100, y: 100 }". If x and y are different the image will be stretched.
source BackgroundResource Set the source of the PDF background (NONE, Datamapper, PDF Resource).

Setting the background to NONE does not reset any other option, such as the position and scale of the background.
start Number The start page of the PDF to use as a background for the section.
top Measurement The top offset of the PDF background (only when absolute positioning is selected).
url String The location of the PDF to use as a background for the section. Three different forms of URLs are supported:
  • A relative path to an image resource; this always starts with "images/". For a file named background.pdf, stored inside the template resources, the URL would be images/background.pdf.
  • A URL (either file:, http:, or https:). The complete syntax for an external file is: file://<host>/<path>. If the host is "localhost", it can be omitted, resulting in file:///<path>, for example: file:///c:/resources/images/image.jpg.
  • An absolute Windows-style path.

A relative path and a URL are expected to be URL encoded. For example, a space needs to be encoded as %20.
An absolute Windows-style path does not need to be URL encoded, but in JavaScript any backslashes in a String need to be double-escaped: "C:\\Images\\Image.pdf".

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;

For more examples, see Control Script: Setting a Print section's background.