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.
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 (in a specific order, see The script flow: when scripts run).
This topic explains how scripts work and how you can create and write a script.
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 , 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.
Script types
There are generally two types of scripts in the Designer: Control Scripts and template scripts.
Control Scripts don't touch the content of the themselves, but they change the way a template is outputted, for example by selecting or omitting sections from the output. For more information about Control Scripts and their use, see Control Scripts.
Template scripts can change the contents of sections in a template. This type of script must have a . The selector can be text, an HTML element and/or a CSS selector (see Selectors in Connect). Running a template 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.
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 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.
In a Print context, the scripts in the Scripts pane run once for each section and then once for each (see Master Pages). Creating a new script
Writing a template script starts with this procedure:
- On the Scripts pane at the bottom left, click New. A new script appears in the list. Double-click on it to open it.
- Change the name of the script, so that it reflects what the script does.
- 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 it easier to recognize the text for yourself. In the Script Wizard, click Text and type the text to find.
- A selector (HTML/CSS):
- 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: Testing scripts.
There is a shorter route to create a script for an element with a specific ID:
- In the template, click the element for which you want to create a script.
- 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 #).
- 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
- 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.
-
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 few examples can be found in a How-to: Combining record based conditions.
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.
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 - 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.
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 Script API.
|
|