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.

Most scripts can be made using one of the script Wizards. 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 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.

How scripts work

A script is a small set of instructions to the program, written in JavaScript.

When 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 (Control Scripts first).

All scripts, except Control Scripts, must have a selector. The selector can be text, an HTML element and/or a CSS selector. Running a 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.

Next, the script can modify the selected pieces of content, using values from the record that is merged to 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.

Creating a new script

Writing a 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.
3. Choose which kind of selector you want to use. Running a 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, 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 them easier to recognize 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 without the angle brackets: p.
  • HTML elements with a specific CSS class (.green). In the script Wizard, click Selector and type the class name, including the preceding dot: .green.
  • An HTML element with a specific ID (#intro). In the script Wizard, click Selector and type the ID, including the preceding #: #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 http://www.w3schools.com/cssref/css_selectors.asp for more selectors and combinations of selectors.
• 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.

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 profiling scripts.

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

1. In the template, click the element for which you want to create a script.
2. On the Attributes pane at the top right, type an ID. (In HTML, IDs start with #, but in this field you should type it without the preceding #).
3. Click the label to the left of the ID input field (ID)to make a new script with the ID that you typed as a selector.

Writing a script

1. Create a new script (see: Creating a new 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.

   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: http://www.w3schools.com/js/js_syntax.asp and http://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.

   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 other keyboard shortcuts see: Text editors: Source tab, JavaScript, CSS, Script Editor.

   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.

   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').

   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 - in this case they are cells with the CSS class 'amount' - will be set to green; if the value is below zero, the text color will be set to red.

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

   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 Designer Scripts API.

• Last Topic Update: 09:08 AM Jun-29-2017
• Last Published: 2019-05-22 : 2:52 PM