Standard Script API

This page lists the global objects and functions that are available in Standard Scripts, created inside the Scripts pane. Click through to an object or function to get a description and examples.

Most of these objects and functions are also available in Control Scripts (Control Scripts) and Post Pagination Scripts (Post Pagination Scripts).
For objects and functions restricted to Control Scripts see Control Script API, and for the Post Pagination Script API see Post Pagination Script API.

The basics of script-writing in the Designer are explained in the following topic: Writing your own scripts.

Objects

Object	Description
results	This object - of the type: QueryResults - is used to manipulate the content of the template. It contains the HTML element or set of HTML elements that match the selector of the script, specified in the script editor. This object is not available in Control Scripts, because that type of script doesn't have a selector (see Control Scripts).
this	A Standard script or Post Pagination script that has its scope set to "Each matched element" (see Setting the scope of a script) will be called in a loop over the elements that match the selector of the script - the `results` (see results). In such a script, `this` is an object of the type QueryResult. It represents the current element in the loop. This object is not available in Control Scripts, because that type of script doesn't have a selector (see Control Scripts).
record	The record in the main data set that is currently being merged. To get the value of a field in the record, use `record.fields['fieldname']` or `record.fields.fieldname`.
logger	Global object that allows you to log messages.
locale	Defines which locale to use. (See Locale.) Note that the value is read-only.
formatter	Global object that allows you to format values (such as a date or number).
automation	This object encapsulates the properties of the Workflow process that triggered the current operation. Not available in PrintShopMail Connect.
merge	The `merge` object is mainly used in Control Scripts. It gives access to the template with all of its contexts, sections and runtime parameters. It doesn't give access to the content of the sections. To change the content of a section, you would create a script with a selector and use the `results` object in the script (see results).
contentitem	(Print output only.) The `contentitem` object holds the Print Content Item that is written to the Connect database when generating Print output. It allows you to add custom properties to the Print Content Item, in the form of key-value pairs (a JSON string). Note: The `contentitem` object is not available in PrintShopMail Connect, due to the absence of a Connect database.

Global functions

Function	Description
fatalError(message)	Triggers a fatal error that aborts content creation.
loadhtml()	Loads HTML data from an HTML (snippet). The returned HTML can be placed into a variable or into a set of HTML elements.
loadjson()	Loads JSON data from a URL. This is a simple way to retrieve content from external systems.
query()	Performs a query in the template's contents and creates a new result set containing the HTML elements that match the given CSS selector.
resource()	This function returns information about an image resource. It can also be used to check if a file exists.
translate()	Gets the translation of a source text with an (optional) context. It returns the message as-is if no translation is found.

Looping over elements

If the selector of a script matches more than one element in a template, you may want the script to loop over them.

One way to do this is by setting the script's scope set to "Each matched element" (see Setting the scope of a script). The script will be called in a loop over the elements that match the selector of the script. It can access each matched element directly via the this object. For an example, see: this.

Otherwise, there are a number of iterator functions that you can use, such as each(), for(..in...) and for...of.

Examples of iterator functions

Function	Description
each()	A generic iterator function, to iterate over the elements in the result set.
for(... in ...)	Iterates over the enumerable properties of an object, in arbitrary order. For each distinct property, statements can be executed.
for...of	The for...of statement executes a loop that operates on a sequence of values sourced from an iterable object. See Mozilla's documentation. Note: A for...of loop currently cannot be used in combination with 'const'.

Function

Description

each()

A generic iterator function, to iterate over the elements in the result set.

for(... in ...)

Iterates over the enumerable properties of an object, in arbitrary order. For each distinct property, statements can be executed.

for...of

The for...of statement executes a loop that operates on a sequence of values sourced from an iterable object. See Mozilla's documentation.

Note: A for...of loop currently cannot be used in combination with 'const'.