Adding a JavaScript code element

Use a JavaScript code element for each block of code you are using in a template.
Restriction: New feature icon The JavaScript code element is available only in version 2 templates.

About this task

JavaScript can range from simple arguments to complex scripts.
  • For simple arguments, you can apply script to the content of an element, such as a Text element. Double-click the text element, select the Script Expression tab, and enter a script.
  • For complex scripts, you can use this task to apply your script by using the JavaScript code element.
The following are benefits to using the JavaScript code element over the Script Expression tab of an element:
  • You can reuse scripts from other users.
  • You can group calculations without worrying about the order of their execution.
  • You can create normal and complex data structures, such as collections, and continually add to them.
    Tip: Starting in Rational® Publishing Engine V2.1 release, you can call the function that is defined in one JavaScript code element in another JavaScript code or Script Expression by setting a Library script property on the script code. To set the Library script property, go to the Properties view of the JavaScript Code element and select the Specific tab, enable the Library script check box. For more information about the library script property, see JavaScript code element properties.

The JavaScript file utils.js is included in your installation files and in the predefined Document Builder component files for you to use for simple JavaScript, like including the current date in report output.

To see a list of the existing JavaScript code in your template, click Template > Review JavaScript. The Search view opens and a list of elements that use JavaScript is displayed. Native filters are not considered JavaScript in this context. Native filters are not listed in the search results.

Procedure

  1. Save your template before you start to work with JavaScript.
  2. In the Palette view, select the JavaScript code icon JavaScript code element and drag it into the template content editor.
  3. Double-click the JavaScript code element.
  4. In the Script Expression tab, select a variable from the tree to apply the JavaScript code to.
  5. Enter the JavaScript code by using one of these options:
    • Write a script manually in this window
    • Copy and paste a script from an outside editor into this window
    • Click Include script and selecting a file from your computer, a remote server, or from the Document Builder component
  6. Optional: If you copied the script from XHTML, you can:
    • Select the XHTML Input option to allow the XHTML tags that are contained in the script to be edited.
    • Clear the XHTML Input option to remove all XHTML tags from the script.
    If you are copying rich text or you are using rich text in conditions, you must select the XHTML Input option.
    Important: Invalid XHTML causes document generation to fail. Verify that your XHTML is valid before you save your changes.
  7. Optional: If you are generating the template into XHTML output, you can:
    • Select the XHTML Output option to parse the script and render the script as rich text.
    • Clear the XHTML Output option to treat the script as plain text.
    This selection applies to all of the data source attributes in the expression. You cannot mix plain text and XHTML in your script.

    If you are copying rich text or creating rich text on an ad hoc basis, you must select the XHTML Output option.

  8. After you enter the script, click Test script to validate the code. If errors exist in your JavaScript, document generation might not complete successfully.
  9. Click OK to save the changes. The block of code collapses in the element. You can expand the code to view it in the template content editor.

Working in the JavaScript editor

Use the JavaScript editor to work on your script with syntax coloring and content assist.

About this task

Syntax coloring specifies how the JavaScript source code is rendered with its own color and style. To change the default syntax color preferences, in Document Studio select Windows > Preferences > JavaScript > Editor > Syntax Coloring.

Content assist shows in a pop-up window a list of valid alternatives for completing the current line of code. To activate content assist, press Ctrl + Space.

This is a screen capture of the JavaScript editor.

Procedure

  1. Double-click the JavaScript code element. The Input code for JavaScript code element window opens.
  2. Optional: If you are including a new script from another file, click Include script and select a file from your computer, a remote server, or from the Document Builder component. Click OK.

    For files selected from your computer or a remote server, a copy of the JavaScript code from your selected file opens in the JavaScript editor.

    For files selected from the Document Builder, the Use Script Reference window opens. You must choose whether to include the JavaScript as a reference link in the template:
    • If you select Yes, the link to the JavaScript (.js) file is embedded inside a <Script> tag. For example, the following reference link is added into the JavaScript editor that you must not modify:
      <Script src= "library://api/scripts/51"></Script>
      Remember: When you run document generation from the template, and you have a JavaScript as a reference link in the template, the Document Builder must be up and connected to Document Studio. For details, see Connecting to the Document Builder component topic.
    • If you select No, a copy of the JavaScript code from your selected file opens in the JavaScript editor.
  3. Optional: Click Open in editor to enter the script in an Eclipse JavaScript editor. The script opens in a new editor tab as a temporary .js file, such that you can edit the JavaScript and manage the script through the options in the Outline view. After you edit the script, save your changes and close the temporary JavaScript editor tab to return to the Input Code for JavaScript Code Element window.
  4. Click Test script to validate the code.
  5. Click OK to save the changes and exit the window.

Feedback