Writing your own scripts

Personalization can be taken a lot further than just inserting names and addresses, and hiding or showing text or images. Every bit of information in your communications can be made entirely personal, using scripts.

In OL Connect, a script is a small set of instructions to the program, written in JavaScript.
When OL Connect generates the actual output – letters, web pages or emails -, it opens a record set and merges it with the template. It takes each record, one by one, and runs all scripts for it (in a specific order, see The script flow: when scripts run).

Any kind of personalization is done via scripts, but you don't have to write every script yourself. In many situations you can use a Script Wizard, which will do that for you (see Personalizing content).
For a block of variable data, such as an address, the Text Script Wizard is a perfect fit.
Paragraphs can be made conditional with a Conditional Script Wizard.
For dynamic images, you can use the Dynamic Image Script Wizard.
In an Email context, you are provided with a number of Email Script Wizards to set the sender, the recipients and the subject of the email.

However, when you want to do something that goes beyond what you can do with a Wizard, like creating a conditional paragraph with a condition that is based on a combination of data fields, you have to write the script yourself.

This topic explains how scripts work and how you can create and write a script yourself.

Script types

There are three types of scripts in the Designer: Control Scripts, Standard Scripts and Post Pagination Scripts.

Control Scripts

When output is generated from a template, Control Scripts run before all other scripts, when a record is merged with a context. They determine how different sections of the context are handled. They can, for example, make the page numbering continue over all Print sections, split Email attachments, or omit Print sections from the output.

Some functionality is provided as a Scripting Wizard, for example Conditional Print Sections.

Control Scripts don't touch the content of the sections themselves, but they can change the way a template is outputted. For more information about Control Scripts and their use, see Control Scripts.

Tip: Do you find yourself copy-pasting the same function into every new script? You can avoid this by defining your function in a Control Script. Control Scripts are executed first, so the function will then be available in all Standard Scripts and Post Pagination Scripts.

Handlebars Helpers

A Handlebars Helper - a function that can be used in expressions - is also defined in a Control Script.

Helpers can be made with the Handlebars Text Helper wizard (see Using the Helper Wizard) or you can write them yourself (see Creating custom Helpers).

Standard Scripts

Standard Scripts can change the contents of sections in a template. This type of script must have a selector. The selector can be text, an HTML element and/or a CSS selector (see Selectors in OL Connect).

Running a Standard Script starts with looking for pieces of content in the template that match the script's selector.
The results of this query can vary from one occurrence of a simple text (for example: @EMAIL@) to a large collection of HTML elements. For example, when the selector is p, the HTML tag for a paragraph, all paragraphs will be collected and passed to the script.

Tip: Hover over the name of a script in the Scripts pane to highlight parts of the template that are affected by the script.

Next, the script can modify the selected pieces of content, using values from the record that is merged with the template at the time the script runs. It can, for example, hide, replace or add text or change the style of those pieces of content. This is how scripts personalize documents.

Tip: Content added by a script isn't visible in Design mode, but is visible and can be inspected in Preview mode.

Note: In a Print context, the scripts in the Scripts pane run once for each section and then once for each Master Page (see Master Pages).

Note: The context for user scripts does not reset across records. This means that if a script uses a variable that is not declared or initialized in that script, the variable retains its value from the previous record. This is by design. It allows you, for example, to maintain a running total across all records of a job.

Post Pagination Scripts

Post Pagination Scripts are run in a Print context after the content has been paginated. Because they can search through the output of all Print sections, and modify Print sections (one at a time), they may be used to create a Table Of Contents (TOC), as explained in the topic: Creating a Table Of Contents.

For more information see Post Pagination Scripts.

Creating a new Standard Script

Writing a Standard Script starts with this procedure.

  1. On the Scripts pane at the bottom left, click New. A new script appears in the list. Double-click on it to open it.

  2. Change the name of the script, so that it reflects what the script does.

    Note: Scripts can only have the same name when they are not in the same folder. (See Managing scripts.)

  3. Choose which kind of selector you want to use. Running a Standard Script starts with searching the template for pieces of content that match the script's selector. The collected pieces of content are passed on to the script (all at the same time, or one by one - see Setting the scope of a script), so that the script can modify them.
    The selector can be:

    • Text, for example: @lastname@, or {sender}. The text doesn't have to have any special characters, but special characters do make it easier to recognize the text for yourself. In the Script Wizard, click Text and type the text to find.
    • A selector (HTML/CSS):
      • HTML elements of a certain type, such as a paragraph: <p>. In the Script Wizard, click Selector and type the HTML tag in the Selector field without the angle brackets: p.
      • HTML elements with a specific CSS class (eg. green). In the Script Wizard, click Selector and type the class name in the Selector field, preceded by a dot: .green.
      • An HTML element with a specific ID (eg. intro). In the Script Wizard, click Selector and type the ID in the Selector field, preceded by #: #intro.

        In an HTML file, each ID should be unique. This means that a particular ID can be used only once in each section.

      • Etcetera. See MDN Web Docs - CSS selectors for more selectors and combinations of selectors; also see Selectors in OL Connect for selectors that can only be used in OL Connect.
    • A selector and text. This is text inside an HTML element (or several HTML elements) with a specific HTML tag, CSS class or ID. In the Script Wizard, click Selector and Text.

    Tip: When output speed matters, choose selector or selector and text. Searching text is a rather lengthy operation, compared to searching for HTML elements and/or CSS selectors. See also: Optimizing scripts.

Quick-start a script for a specific ID or class

There is a shorter route to create a script for an element with a specific ID or class:

  1. In the Outline pane at the left, click the element for which you want to create a script.

  2. On the Attributes pane at the top right, type an ID or class.

  3. On the Attributes pane, click the label to the left of the ID or Class input field (ID or Class) to make a new script with that ID or class as selector.

Drag-and-drop a data field to start a script

Here is another way to start a script with a class selector.

  1. Right-click a section in the Resources pane and select Properties.

  2. Uncheck the option to Evaluate Handlebars expressions and click OK.

  3. Open that section and drag-and-drop a data field from the Data Model into the content.

What happens is that:

  • A placeholder for the value of the data field shows up in the text. It looks as follows: @FIELDNAME@.

  • A script appears in the Scripts pane at the bottom left.

The script replaces the placeholders in the content with the value of a data field in the current record.

As long as the option Evaluate Handlebars expressions is inactive, drag-and-drop will create a script and insert a placeholder that looks like this: @fieldname@. When the option is active, drag-and-drop inserts an expression like {{fieldname}}.

Writing a script

  1. Create a new script (see: Creating a new Standard Script, Adding a Control Script or Adding a Post Pagination Script), or double-click an existing script in the Scripts pane on the bottom left.
    If the script was made with a Script Wizard, you have to click the Expand button before you can start writing code. This will change the Script Wizard into an editor window.

    Caution: When you change an expanded text script and save it, it becomes impossible to edit the script using the Script Wizard again.

  2. Write the script. Click Apply from time to time to see if the script works as expected. This will be visible on the Preview tab in the main workspace.

Syntax rules

Every script in the Designer must follow JavaScript syntax rules. For example, each statement should end with ; and the keywords that can be used, such as var to declare a variable, are JavaScript keywords. There are countless tutorials available on the Internet to familiarize yourself with the JavaScript syntax.
For a simple script all that you need to know can be found on the following web pages: https://www.w3schools.com/js/js_syntax.asp and https://www.w3schools.com/js/js_if_else.asp. A complete JavaScript guide for beginners can be found here: https://developer.mozilla.org/en-US/docs/Web/JavaScript.
A few examples can be found in a How-to: Combining record based conditions.

Tip: In the editor window, press Ctrl + Space to see the available features and their descriptions.
Use the arrow keys to select a function or object and press Enter to insert it in the script.
Type a dot after the name of the function or object and press Ctrl + space again to see which features are subsequently available.
For more keyboard shortcuts, see Keyboard shortcuts.

Two basic code examples

Writing a script generally comes down to modifying the piece(s) of content collected from the template with the script's selector, using values, or depending on values of the record that is being merged to the template at the moment the script runs.

Modifying the template

To access and change the results of the query that is carried out with the selector (in other words: to modify the output), use the object results.

The following script (with the selector p) changes the text color of all paragraphs to red with a single line of code:

results.css('color', 'red')

It does this for each and every customer, because it does not depend on a value from the record that is being merged to the template.

Using values from the record in a script

To access the record that is being merged to the template when the script runs, use the object record (see record).

Suppose you want to display negative amounts in red and positive amounts in green. Assuming that there is an AMOUNT field in your customer data, you could write the following script (with the selector: td.amount, that is: table cells with the class 'amount').

Copy 
var amount = record.fields.AMOUNT; 
if (amount >= 0)    
    {results.css('color', 'green');}
else if (amount < 0) {    
    results.css('color', 'red');
    }

When this script executes, it stores the value of the AMOUNT field from the current record in a variable and evaluates it. If the value is zero or higher, the color of text in the results - the table cells in this case - will be set to green; if the value is below zero, the text color will be set to red.

Tip: For more examples of using conditions, see this how-to: Combining record-based conditions.

If an expanded script contains errors or if there are warnings, icons appear in the overview ruler on the right hand side of the editing area. These icons are shown relative to their position in the script and do not move as you scroll down. You can click on an icon to quickly jump to the error or warning. Script errors are highlighted by a red icon, and warnings in yellow. The topmost icon will display red if any errors exist in the script at all.

Designer API

Features like results and record do not exist in the native JavaScript library. These are additional JavaScript features, designed for use in Connect scripts only. All features designed for use in the Designer are listed in the Designer's API, with a lot of examples; see Standard Script API.

Setting the scope of a script

The selector of a script can match multiple elements. By setting the scope of the script you can determine whether you want to run the script once, or once for each element that matches the selector. The second option is especially useful when a script targets rows or cells in a Dynamic Table (see Using scripts in Dynamic Tables).

To set the scope of a script, click on Options at the bottom of the Script Editor window. The options are:

  • Result set: The script will run once, regardless of the number of elements that match the selector. It will have access to all elements that match the selector via the results object (see results). The each() function could be used to iterate over elements in the results.

  • Each matched element: The script runs once for each element that matches the selector. The current element is accessible via the this object (see this). If the script targets (something in) a row that is bound to a detail table, the current detail record is accessible via this.record.

Note: The scope of Control Scripts can't be set, because they don't have a selector.