Using JavaScript

JavaScript files, libraries and frameworks can be added to a template, primarily for use in Web pages and Capture OnTheGo Forms. .

Which kind of library or framework you'll want to work with depends on the type of features you really desire. For a bit of help with that and a few examples, see this how-to: Using external libraries.

Some JavaScript files are added automatically: When you create a template with a COTG Template Wizard (see Capture OnTheGo template wizards), the Designer automatically adds the jQuery library v. 3.5 and the COTG library: cotg-2.1.0.js. This also happens when you add a Capture OnTheGo (COTG) element to a template that you didn't start with a COTG template wizard. For more information about this plugin, see Using the COTG plugin.Capture OnTheGo and Jumbotron template wizards automatically add the Foundation files v. 5.5.1 to the resources of the template. For more information about the use of Foundation in the Designer, see Using Foundation.

It is possible to open and edit any JavaScript file in the Designer: select File > Open, select All files (*.*) as the file type and then select a JavaScript file.

Adding JavaScript files to the Resources

Adding a JavaScript file

To add a JavaScript file to the resources:

  1. Add the file:

    • Right-click the JavaScript folder on the Resources pane, and click New JavaScript. Double-click it to open and edit it.
    • Alternatively, drag and drop the JavaScript file from the Windows Explorer to the JavaScript folder on the Resources pane.
    • Or import one or more JavaScript files from another template; see Import Resources dialog.

  2. Make some settings for the file: right-click the file on the Resources pane and select Properties.

    • Defer postpones the execution of the script until the page in which it is included has finished parsing. This attribute is required by APIs like Google Maps.
    • When async is checked, the script executes asynchronously with the rest of the page (while the page continues the parsing).

    When neither option is checked, the script is fetched and executed immediately, while the parsing of the page is paused.

Now the JavaScript file is ready to be used in your Web templates; see Including a JavaScript file in a Web context.

Adding a remote JavaScript file

A Remote JavaScript Resource is a file that is not located within your template but is hosted on an external web server , generally called a CDN. Popular hosted frameworks on CDN networks are:

When generating Web output, these files are referenced in the web page's header and are served by the remote server, not by the Connect Server module.

There are a few advantages to using remote resources:

  • These resources are not served by your server, saving on space, bandwidth and processing.
  • Using a popular CDN takes advantage of caching - a client having visited another website using that same CDN will have the file in cache and not re-download it, making for faster load times for the client.

To add a remote JavaScript:

  1. Right-click the JavaScript folder on the Resources pane, and click New Remote JavaScript.
  2. Enter a name for the file as it appears in the JavaScript resources. For better management, it's best to use the same file name as the remote resource.
  3. Enter the URL for the remote resource. This must be a full URL, including the http:// or https:// prefix, domain name, path and file name.
  4. Optionally, check defer or async to add the async or defer attribute to the <link> element in the <head> of the segment.
    Defer postpones the execution of the script until the page has finished parsing. This attribute is required by APIs like Google Maps.
    When async is checked, the script executes asynchronously with the rest of the page (while the page continues the parsing).
    When neither option is checked, the script is fetched and executed immediately, while the parsing of the page is paused.
  5. Optionally, for a Capture OnTheGo Form, you can check Use cached Capture OnTheGo resource, to prevent downloading a remote JavaScript file again if it has been downloaded before. The file should be available on a publicly accessible location, for example: a folder location on a corporate website, hosted by a CDN (Content Delivery Network) or shared via a Workflow process.

In Workflow, when using the Create Web Content task, check the Embed All Resources option to download and embed all remote resources. (See Workflow Help: Create Web Content.)

After adding the remote file, you may right-click it and select Download Resource. This allows you to maintain a central file, from which you can quickly download a copy to your template without having to copy & paste.

Note that a local copy of a remote resource is a snapshot; it is not automatically kept in sync with its remote content. You can download the remote resource again to overwrite the local copy with updated content. If you don't want a local copy to be overwritten you should rename it before downloading the remote resource again.

Using JavaScript files in a template

Including a JavaScript file in a Web context

To link a JavaScript file to the Web context, or to a certain Web section or COTG template:

  1. On the Resources pane, expand the Contexts folder, and then either right-click the Web context, or expand the Web context and right-click a Web section.
  2. Click Includes.
  3. From the File types dropdown, select JavaScripts.
  4. The available JavaScript files are listed at the left. Use the arrow buttons or double-click to move the JavaScript files that should be included to the right-hand list. Using the Up and Down buttons or drag-and-drop you can change the order of the files, too.
  5. Click OK.

JavaScript files that are linked to (i.e. included in) a section show a chain icon in the Resources pane (see Resources pane).

Any JavaScript files included in a section run after the scripts in the Scripts pane.

Using JavaScript in other contexts

Email clients do not support JavaScript. Therefore, Email contexts cannot include JavaScript resources.

When a JavaScript file is included in a Print section, the Designer itself acts as the browser. When generating Print output, it runs the JavaScript after generating the main page flow contents and the pagination, but before any Master Pages are added. So it is possible to change Print output (except content on Master Pages) by a JavaScript; for example, to add a barcode that includes the page number to each document. A warning is appropriate, however: changing the Print output may change the page flow and doing so at this point may result in bad output and/or serious errors or a crash of the software.

Previewing a template with JavaScript resources

When a section is previewed in the Designer, scripts in the Resources pane are interpreted by an internal browser.

JavaScript resources included in a Web section are only executed on the Live tab, not on the Preview tab.
Remember that the final output of a Web section is eventually processed by a client browser. Since you cannot predict what type of browser will be used, you should make sure your scripts are compatible with a wide range of browser types and versions.

JavaScript resources included in a Print section are executed on the Preview tab. (The editor for a Print section does not have a Live tab.)

The internal browser engine which is used as of version 2018.2, Gecko 38, is compliant with the ECMAScript 5 language specification.
This means that scripts using features described in ECMAScript 2015 (aka ES6) - such as the keyword let - will fail in the Preview and Live tab of the Designer.
Nevertheless, they should work fine when processed by a (modern) client browser. (See for example the browser compatibility table at the bottom of the Mozilla documentation for "let": Mozilla documentation.)