Testing scripts

The quickest way to test that scripts work as expected, is to click the Preview tab at the bottom of the workspace.

You can even do this while creating a new script, either with a Script Wizard or in the expanded script editor. Click Apply at the bottom of the script editor to see the effect of the script on the Preview tab of the Designer.

In Preview mode you get warnings, such as when a table or field name is unknown, and errors, such as when unknown properties are referenced.

Note that scripts that use values of data fields can only be effective when a data file is open. See Loading data.

Note: Post Pagination Scripts run only when a Print section is previewed or outputted.
To verify the results of Post Pagination Scripts on a certain Master Page, preview the Print section to which that Master Page is applied.

Testing for errors

Information in the Scripts pane

One way to see whether a script is functional is to take a look at the Scripts pane.

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

Icons on the name of scripts in the Scripts pane can show that there is a warning, information or error. If one of these icons appears, you can hover over it to see more details.

  • The (i) information icon shows that the selector of the script does not produce a result in the current section. Note that standard scripts and post pagination scripts are not executed if their selector does not match any elements. A control script is always executed, assuming the script is enabled.

  • The (!) warning icon appears, for example, when a script refers to an unknown field in the record set, or when ; is missing after a statement.

  • The (x) error icon displays when the script results in an error, for example, when it uses an undeclared variable.

Information in the script editor

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.

Tip: To do a quick search for a certain script or piece of code, type a search text in the filter field located below the buttons in the Scripts pane.

Doing a Preflight

In addition to the icons and messages in the Scripts pane, a preflight can show if your scripts function as expected before generating output:

  1. On the menu, select Context > Preflight.

  2. Select All, or enter a selection of records. You can specify individual records separated by semi-colons (;) or ranges using dashes. For example: 2,4,6-10 would print pages 2, 4, 6, 7, 8, 9 and 10.

  3. Click OK.

Preflight executes the template without actually producing output.
The Preflight window displays any issues once it’s done. It will tell, for example, which selectors were not encountered in the template.
Double-click a script warning/error (either in the Preflight Progress dialog or in the Preflight Result view) to open the script in the script editor. The relevant line will be highlighted.

Tip: Be aware that scripts run in a specific order (see The script flow: when scripts run). When one script unintentionally influences the results of another script, changing the order of the scripts in the Scripts pane may help (see Changing the order of execution).

Note: An image with an unknown file extension is represented by a red cross in the output, but no error is logged unless the image refers to a local file that does not exist on disk.
Image file extensions that the software recognizes are: AFP, BMP, EPS, GIF, JPG/JPEG, PCL, PDF, PNG, PS, SVG, and TIF/TIFF.

Using the Script Debugger

The Designer's Script Debugger allows you to set breakpoints in scripts and step through them. It simulates an output run with only the current record and shows an overview of the state of all local and global variables, while the Workspace displays the partially merged document.

There are two ways to start the Script Debugger:

  • Click the Debug Scripts button in the toolbar of the Scripts pane. The Script Debugger will pause and accept input as soon as it processes the first script.

  • Right-click an enabled script in the Scripts panel and choose Debug from the contextual menu. The Script Debugger will pause and accept input as soon as it processes the selected script.

If the selected script is never processed, a message will pop up. This can happen when:

  • The selector has no matches at any time. (This may depend on other scripts, since scripts can add or remove content.)
  • The script is excluded through the properties of its parent folder.

For an explanation of the buttons in the Script Debugger, see Script Debugger.

Testing for speed issues

To measure the time that the execution of scripts will take:

  • On the Context menu, click Profile scripts.

Profiling means running the scripts in the template, with the current record, to see how fast scripts in the Scripts pane execute. It helps greatly in troubleshooting performance issues caused by scripts.

After running the Script Profiler you can see in which sections the script has run:

  • Hover the mouse over a value in the column Count to see the number of times that the script has run, per section.

You can also see the breakdown of the execution time across different execution stages:

  • Hover the mouse over a value in the column Elapsed to see the time elapsed (in milliseconds) since the start of the session. In the Scripts Profiler, the scripts are by default sorted based on the values in the Elapsed column, from high to low.
  • Hover the mouse over a value the column Delta to see the difference between the time elapsed (in milliseconds) in the previous session and in the current session.

The script execution stages are:

Query: the time it takes to find the selector in the template.

Tip: Looking for text is a rather lengthy operation. Use an ID or class (possibly in combination with a text) instead of a text selector to make the query faster. For more tips, see Optimizing scripts.

Execution: the time it takes to execute the script. If you are an experienced JavaScript coder you may be able to optimize the code to speed up the execution of the script.

Tip: Functions that actually change the content of the template (for example,append()) are comparatively time consuming. Avoid using such functions in a loop. For more tips, see Optimizing scripts.

Note that the times vary slightly per run of the Script Profiler. Run the Script Profiler a number of times and calculate an average from the results, before trying to speed up the execution of a script.

Script Profiler settings

Number of runs

By default, the Script Profiler runs on 1000 instances of all the scripts. To test on a higher or lower number of instances:

  1. On the menu, select Window > Preferences.

  2. Click Scripting.

  3. Set a number of iterations (maximum one billion) and click OK.

Sorting

In the Scripts Profiler, the scripts are by default sorted based on the values in the Elapsed column, from high to low. Click any of the columns to sort the scripts according to the values in that column.

Script timeout

When testing scripts, either by toggling to Preview mode or by using the Script Profiler, a script timeout is active in the Designer, so that scripts that need a very long time to run are stopped after a set time. You can adapt this timeout to your needs, as follows:

  1. On the menu, select Window > Preferences.

  2. Click Scripting.

  3. Set a timeout in seconds (for example: 2s) and click OK. The minimum timeout is 1 second.

Note: The script timeout is not active when generating output.