Set Variables, Parameters, and Properties

Learn more about setting variables, parameters, and properties.

This section covers the following topics:

Set Variables

Updatable variables differ from standard XSL variables <xsl:variable> in that they're updatable during the template application to the XML data.

This allows you to create many new features in the templates that require updatable variables.

The variables use a "set and get" approach for assigning, updating, and retrieving values.

Use the following syntax to declare/set a variable value:

<?xdoxslt:set_variable($_XDOCTX, 'variable name', value)?>

Use the following syntax to retrieve a variable value:

<?xdoxslt:get_variable($_XDOCTX, 'variable name')?>

You can use this method to perform calculations. For example:

<?xdoxslt:set_variable($_XDOCTX, 'x', xdoxslt:get_variable($_XDOCTX, 'x' + 1)?> 

This sets the value of variable 'x' to its original value plus 1, much like using "x = x + 1".

The $_XDOCTX specifies the global document context for the variables. In a multi-threaded environment there may be many transformations occurring at the same time, therefore the variable must be assigned to a single transformation.

See Insert Running Totals for an example of the usage of updatable variables.

Set Parameters

You can pass runtime parameter values into the template.

Parameters can be referenced throughout the template to support many functions. For example, you can filter data in the template, use a value in a conditional formatting block, or pass property values (such as security settings) into the final document.

All name-value parameter pairs are passed to the template. You must register the parameters that you want to utilize in the template using the syntax described below.

To use a parameter in a template:

  1. Declare the parameter in the template.

    Use the following syntax to declare the parameter:

    <?param@begin:parameter_name;parameter_value?>
    

    where

    parameter_name is the name of the parameter

    parameter_value is the default value for the parameter (the parameter_value is optional)

    param@begin: is a required string to push the parameter declaration to the top of the template at runtime so that it can be referred to globally in the template.

    The syntax must be declared in the Help Text field of a form field. The form field can be placed anywhere in the template.

  2. Refer to the parameter in the template by prefixing the name with a "$" character. For example, if you declare the parameter name to be "InvThresh", then reference the value using "$InvThresh".

Example 4-1 Example: Pass an invoice threshold parameter

This example illustrates how to declare a parameter in the template that filters the data based on the value of the parameter.

The following XML sample lists invoice data:

<INVOICES>
 <INVOICE>
  <INVOICE_NUM>981110</INVOICE_NUM>
  <AMOUNT>1100</AMOUNT>
 </INVOICE>
 <INVOICE>
  <INVOICE_NUM>981111</INVOICE_NUM>
  <AMOUNT>250</AMOUNT>
 </INVOICE>
 <INVOICE>
  <INVOICE_NUM>981112</INVOICE_NUM>
  <AMOUNT>8343</AMOUNT>
 </INVOICE>
. . .
</INVOICES>

The following illustration shows a template that accepts a parameter value to limit the invoices displayed in the final document based on the parameter value.

The following table describes the fields for defining parameters as shown in the template in the previous illustration.

Field Form Field Help Text Entry Description

InvThreshDeclaration

<?param@begin:InvThresh?>

Declares the parameter InvThresh.

FE

<?for-each:INVOICE?>

Begins the repeating group for the INVOICE element.

IF

<?if:AMOUNT>$InvThresh?>

Tests the value of the AMOUNT element to determine if it's greater than the value of InvThresh.

13222-2

<?INVOICE_NUM?>

Placeholder for the INVOICE_NUM element.

$100.00

<?AMOUNT?>

Placeholder for the AMOUNT element.

EI

<?end if?>

Closing tag for the if statement.

EFE

<?end for-each?>

Closing tag for the for-each loop.

In this template, only INVOICE elements with an AMOUNT greater than the InvThresh parameter value are displayed. If you pass in a parameter value of 1,000, then the report that is shown in the following illustration is produced.

Notice the second invoice doesn't display because its amount was less than the parameter value.

Set Properties

The properties in the configuration file can alternatively be embedded into the RTF template.

The properties set in the template are resolved at runtime. You can either hard code the values in the template or embed the values in the incoming XML data. Embedding the properties in the template avoids the use of the configuration file.

For example, if you use a nonstandard font in the template, then rather than specify the font location in the configuration file, you can embed the font property inside the template. If you must secure the generated PDF output, then you can use the PDF security properties and obtain the password value from the incoming XML data.

To add a property to a template, use the Microsoft Word Properties dialog (available from the File menu), and enter the following information:

  • Name - Enter the property name prefixed with "xdo-"

  • Type - Select "Text"

  • Value - Enter the property value. To reference an element from the incoming XML data, enter the path to the XML element enclosed by curly braces. For example: {/root/password}

Embed a Font Reference

For this example, suppose you want to use a font in the template called "XMLPScript". This font isn't available on the server; therefore you must define where to find the font at runtime by setting the "font" property. Assume the font is located in "/tmp/fonts", then you would enter the following in the Properties dialog:

  • Name - xdo-font.XMLPScript.normal.normal

  • Type - Text

  • Value - truetype./tmp/fonts/XMLPScript.ttf

When the template is applied to the XML data on the server, the font is looked up in the /tmp/fonts directory. Note that if the template is deployed in multiple locations, then you must ensure that the path is valid for each location.

Secure a PDF Output

For this example, suppose you want to use a password from the XML data to secure the PDF output document. The XML data is as follows:

<PO>
 <security>true</security>
 <password>welcome</password>
 <PO_DETAILS>
 ..
</PO>

In the Properties dialog set two properties: pdf-security to set the security feature as enabled or not, and pdf-open-password to set the password. Enter the following in the Properties dialog:

  • Name: xdo-pdf-security

  • Type: Text

  • Value: {/PO/security}

  • Name: xdo-pdf-open-password

  • Type: Text

  • Value: {/PO/password}

Storing the password in the XML data isn't recommended if the XML persists in the system for any length of time. To avoid this potential security risk, you can use a template parameter value that's generated and passed into the template at runtime.

For example, you could set up the following parameters:

  • PDFSec - To pass the value for the xdo-pdf-security property

  • PDFPWD - To pass the value for the password

You would then enter the following in the Properties dialog:

  • Name - xdo-pdf-security

  • Type - Text

  • Value - {$PDFSec}

  • Name - xdo-pdf-open-password

  • Type - Text

  • Value - {$PDFPWD}

To set the template parameters, see Set Parameters.