Setting Variables, Parameters, and Properties

Learn more about setting variables, parameters, and properties.

This section covers the following topics:

Setting Variables

Updatable variables differ from standard XSL variables <xsl:variable> in that they are 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 Inserting Running Totals for an example of the usage of updatable variables.

Setting Parameters

You can pass runtime parameter values into the template.

These can then 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.

Note:

For BI Publisher Enterprise users, 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".
  3. If you are not using BI Publisher Enterprise, but only the core libraries:

    At runtime, pass the parameter to the BI Publisher engine programmatically.

    Prior to calling the FOProcessor API create a Properties class and assign a property to it for the parameter value as follows:

    Properties prop = new Properties();
prop.put("xslt.InvThresh", "1000");

Example: Passing 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.

Description of GUID-63CF6524-9E69-4405-BF53-7D7064519802-default.gif follows
Description of the illustration GUID-63CF6524-9E69-4405-BF53-7D7064519802-default.gif

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 is 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.

Description of GUID-8370C604-7825-45F6-A42F-70D70706233D-default.gif follows
Description of the illustration GUID-8370C604-7825-45F6-A42F-70D70706233D-default.gif

Notice the second invoice does not display because its amount was less than the parameter value.

Setting Properties

BI Publisher properties that are available in the BI Publisher Configuration file can alternatively be embedded into the RTF template.

The properties set in the template are resolved at runtime by the BI Publisher engine. 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.

See Configuration File Reference in Administrator's Guide for Oracle Business Intelligence Publisher.

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 BI Publisher PDF security properties and obtain the password value from the incoming XML data.

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

  • Name - Enter the BI Publisher 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}

Embedding a Font Reference

For this example, suppose you want to use a font in the template called "XMLPScript". This font is not available on the server; therefore you must tell BI Publisher where to find the font at runtime. You tell BI Publisher where to find the font 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, BI Publisher looks for the font 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.

To set the font properties, see Font Definitions in Administrator's Guide for Oracle Business Intelligence Publisher.

Securing 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 is not 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 is 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 Setting Parameters.