Learn more about setting variables, parameters, and properties.
This section covers the following topics:
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.
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:
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.
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.
Notice the second invoice does not display because its amount was less than the parameter value.
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.
Note:
See the appendix "Configuration File Reference in Administrator's Guide for Oracle Business Intelligence Publisher for more information about the BI Publisher Configuration file and the available properties.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.
For more information about setting font properties, see the section 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}
For more information about template parameters, see Setting Parameters.