Defining and assigning variables

When designing a template, it might be necessary to calculate values or to make data attributes available in contexts where they are normally unavailable. For these situations, you can define variables and assign them values. The values can be static data or can be data available in the current context.

About this task

Variables can be used as placeholders for data calculated at run time (variable assignments) or can be provided in the document specification. Unlike data attributes, you can also use variables in master pages.
There are two types of variables:
  • User-defined variables: User-defined variables are defined by the template designer. A user-defined variable can be internal or external.
    • Internal user-defined variables: Specify a variable as internal to perform calculations or to temporarily store information, such as a variable that is used to bring data into the master pages. Internal variables are not displayed in the document specification; therefore, you cannot provide them with values.
    • External user-defined variables: Specify a variable as external when you provide it with a value. External variables are displayed in the document specification. See Creating a document specification.
  • IBM Engineering Lifecycle Optimization - Publishing variables: These internal variables can be used in the document template.
    Review the internal variables available:
    Table 1. PUB internal variables
    Variable Description
    _cell_number The cell number in a current row. If the element is not a cell, the value is 0. You can use _cell_number from either the Data expression or the Script expression tab.
    _element_id The element number within the template. Kept internally in the template and used for debugging. You can use _element_id from either the Data expression or the Script expression tab.
    _element_level The recursive level of an element. If there is no value set for the element in the Recursive Level property in the Data tab, the value is 1. You can use _element_level from either the Data expression or the Script expression tab.
    _row_number The row number in a current table. If the element is not contained by a row element, the value is 0. You can use _row_number from either the Data expression or the Script expression tab.
    _sessionInfo Runtime property information from the template or document specification. In the Script expression tab, select the _sessionInfo variable and enter the script. Use empty quotation marks without a value inside to generate the default value for the property in the output. Script examples:
    _sessionInfo.getDocspecProperty(property, );
    _sessionInfo.getTemplateProperty(property, );
    _sessionInfo.getDatasourceProperty("data_source_name",property, );
    _sessionInfo.getOutputProperty("output_type",property, );
    _sessionInfo.docspecVersion
    _sessionInfo.templateVersion
    _sessionInfo.engineVersion
    _sessionInfo.buildNumber

    For the getDocspecProperty, you can use existing document specification properties or create custom metadata properties.
    _sessionLogger For debugging purposes, you can display customized information, error, warning, or debugging messages in the TEMP\rpe\rpe.log file, Console view, or Problems view. The messages display in the location that is defined in the log4j2.xml file.

    The default setting is to display information messages in the Console view, but not in the rpe.log file.

    In the Script expression tab, select the _sessionLogger variable and enter the script. You can generate log entries with one of the following methods:
    1. _sessionLogger.debug(message)
    2. _sessionLogger.info(message)
    3. _sessionLogger.error(message)
    4. _sessionLogger.warn(message)

    When you are deciding what to enter as the message in your script, consider using a visual callout, like your initials or username, and using variables from your template to make meaningful messages.
    _sessionUtils In the Script expression tab, you can use this variable to run a function on the script called tidyXHTML. This variable is useful when you notice blocks of white space in the output that is created by improper XHTML coding. With the _sessionUtils variable, a string argument is processed and the XHTML is cleaned up so that the extra white space does not display in the output.

    Example: _sessionUtils.tidyXHTML(text);

    When you use the _sessionUtils variable, also select the XHTML Input and XHTML Output options in the Script expression tab.
    Note: Templates that include this variable can be loaded into older versions of PUB, but the scripts cannot be evaluated correctly.

Procedure

  1. In the Outline view, click Variables > Insert > New Variable. The New Variable window opens.
  2. Enter the variable details in the following fields:
    1. Name: Enter the name of the variable.
      The variable name must use valid Java™ or JavaScript identifiers since they are used in scripts. Rules for JavaScript identifiers:
      • Must start with a letter, underscore (_), or dollar sign ($)
      • Subsequent characters can be digits (0-9)
      • Letters are case-sensitive
      • ISO 8859-1 or Unicode letters, such as å or ü, can be used
      • \uXXXX Unicode escape sequences as characters can be used
    2. Description: Enter the description for the variable.
    3. Default Value: Enter the value for the variable.
    4. Access: Select whether the variable is internal or external from the list.
      • Internal variables are not displayed in the document specification, so you cannot provide them with values.
      • External variables are displayed in the document specification and you can provide values to them.
  3. To assign a variable to an element:
    Tip: Assign variables to container elements whenever possible. The variable is applied to the elements within the container element. For example, you might want to use a variable within a table so that a new row is created for each variable. If you assign a variable to the table element, a table might be created for each variable. Sometimes these consecutive tables merge, but sometimes they display as separate tables. If you add a container element inside the table and drag the row into the container element, then assign the variable to the container element, a single table is created with rows for each variable.
    A table element with a container element. Inside the container element is a row element with three cell elements.
    1. Right-click the element and click Data > Edit Assignments.
      The Assignment Editor window opens.
    2. Click Add.
      The Select Variable window opens.
    3. Enter a name for the variable and click OK.
    4. Click OK in the Assignment Editor window.

Results

The selected variable is defined and assigned to the current element.
When you assign a variable to an element, the element displays an Variable assignment icon icon in the template content editor.
Paragraph element with a query and a variable assignment

What to do next

Tip: You can search for a list of variable assignments that are used in an element by right-clicking the element that the variable is assigned to and selecting Search > Variable references in element. The Search view opens and a list of variable assignments displays. You can double-click a variable assignment in the results to edit it.

You can search for a list of variable assignments, attributes, and queries used in an element by right-clicking an element and selecting Search > All references in element. The Search view opens and a list displays. You can double-click an item in the results to edit it.