Prev Next

How to Define a Custom Script Fragment

You can create a Template Fragment to return data from a Model Script. You do this by creating a Script that returns an XML string in a specific format. You add a reference to this Script in the 'Template Fragment Document Options', then add fields within the 'Custom' section of your Template Fragment that refer to the data returned by the Script.

Creating a Script Fragment

Step

Action

See also

1

Using the Scripting window, create a Model Script that returns a string in XML format.

See the examples of:

  • A Script that returns data in the appropriate XML format (Example Template Fragment Script)
  • The XML format that the Script must return so that it can be used by a Template Fragment (Example Output of a Template Fragment Script)
 Scripting Example Template Fragment Script Example Output of a Template Fragment Script

2

Open or create a Template Fragment in the Document Template Editor.

Right-click on the Template background and click on the icon.

The 'Document Options' dialog displays.

 Document Templates Creating a Template Fragment

3

Select the 'Custom Query' tab and, in the 'Template Fragment type' panel, select the 'Custom Script' option.

A blank field displays to the right of the options.

4

Click on the drop-down arrow and select your Script from the list.

5

In the main text field on the tab, type the entry point of your Script that returns the XML data.

For example, if you were using the example script mentioned in step 1, in JScript, then the entry point would be:

     MyRtfData(#OBJECTID#);

To convey Package information, you can replace #OBJECTID# with #PACKAGEID#. (Also, for VBScript, omit the semi-colon at the end.)

This applies to the calling statement (not the script that is called), which can also reference:

  • #Branch# - gets the IDs of the child Packages of the current Package being processed, working recursively down to the lowest level of sub-Package; this is only valid when processing a Package - elements return a 0 value
  • #UserName# - gets the name of the user logged into version control
  • #Author# - takes the user name from the 'Author' field in the 'General' page of the 'Preferences' dialog, so the defined search can be performed on objects created by that user (this value can be manually re-set in the 'Preferences' dialog)
  • #Package# - (as for #PACKAGEID) gets the package_ID of the currently-selected Package

6

Click on the OK button to close the 'Document Options' dialog.

7

In the Document Template Editor, in the 'Sections' panel, select the 'Custom' checkbox to generate the Custom section.

 Setting Sections for Reporting

8

Within the 'Custom' section, right-click and select the 'Insert Custom Field' option.

A prompt displays for the name of the field to create.

9

In response to the prompt, type the name of the data field that is being returned by your script.

Referring to the example from step 1, you would add DateGen.

Click on the OK button.

10

Repeat steps 8 and 9 for each data field that you want to include in your report.

Add any other formatting and content you need, to the Template Fragment.

11

Save the Template Fragment, and add it to a normal Document Template.

 Adding Fragments to a Document Template

Notes

  • Scripts have a limit of 60 seconds per call before control is returned to the Document Generator

Learn more