Reference directive

Use the Reference directive to display the values of properties, to allow users to enter values for properties, and to insert parameter values.

The output of the Reference directive uses the control rule associated with this property. For example, if the property's control rule (identified in the Property Stream field of the Property form) contains HTML code for a selection box, the property displays as a selection box. In unusual situations, you can override the output by using a variant of the Reference directive.

JSP equivalent

The pega:reference JavaServer Page tag provides a functionally identical capability. See JSP Tags — reference.

Simple formats

Display the value of a property

To display the value of a Single Value property that's on the primary page:

{.myProperty}

<pega:reference name="myProperty" />

To display the value of a property on another page:

{myPage.myProperty}

<pega:reference name="myPage.myProperty" />

If the property has a mode of Value List or Value Group, use an index (subscript) to identify one element in the list or group:

{myPage.myProperty(1)}
{myPage.myProperty(mySubscript)}

Let a user enter a value

To allow a user to update or enter the value for a Single Value property, use the INPUT keyword. For clarity, add the optional AS keyword or the AS keyword and an equal sign. These three examples are equivalent:

{.myProperty INPUT}
{.myProperty AS INPUT}
{.myProperty AS = INPUT}

Insert the value of an activity parameters

Use the Param keyword to identify an activity parameter value.

{Param.myParameter}

Complete syntax

In the syntax presentations below:

{[REFERENCE][[page].]property[(index)][AS [=]][option]}

The dot before the property is optional if page is not specified. The option is one of these optional keywords. If you omit any keyword, processing assumes DISPLAY. values. (You can spell out a keyword or use any prefix, such as I, IN, or INP for INPUT.)

Option

When to Use

DISPLAY

This keyword instructs the system to use a control rule in read-only mode, detectable as !$mode-input. Stream processing adds a single space before the value and a single space after the value.

INPUT

Add INPUT to present a property in update mode so that a user can enter, or select, a value for the property. For example:

{.myText INPUT}

If the control rule referenced in the myText property definition instructs the system to display the property as a text box in update mode, it displays myText as a text box.

LITERAL

If the value of a property is an HTML text fragment, and is to be processed as HTML, add the LITERAL option to the Reference directive. For example:

{.myText LITERAL}

TEXT

Use this option for textareas. Add the TEXT option to a Reference directive if the property defines a text area, and you want the <BR> tag to be converted to a new line character.

BLOCK

Use this option to display a value that was entered into an input textarea in the same format as entered (but without a surrounding textarea.)

Add the BLOCK option to a Reference directive to process the property to display HTML tags without interpreting them.

If the source text contains a newline character, the system replaces it with <BR/> tag. It also performs the conversions listed for the NORMAL keyword, so that the exact value of the property is displayed, even if it includes characters that are usually interpreted as HTML elements.

STREAM

Use this option to instruct the system to replace line breaks with <BR> followed by one space character. This can be useful in situations when the line length is not appropriate.

Add the STREAM option to a Reference directive to instruct the system to process the property to display HTML tags without interpreting them.

In addition, the system replaces each newline character and <BR> with a space. It also performs the conversions listed for the NORMAL keyword, so that the exact value of the property appears, even if it includes characters that are usually interpreted as HTML elements.

NORMAL

Use this option to convert the <,>, & and * characters to the corresponding HTML entities (&lt;&gt;, &amp; and &ast; respectively) so that they appear correctly in the resulting display or output.

The NORMAL keyword also causes stream processing to ignore the control rule referenced in the property definition, and does not place any space character before and after the value.

Overriding HTML associated with a property

To cause a property's value to appear differently in different HTML pages or different applications, you can override the control rule normally associated with the property.

This uses the special syntax:

{[REFERENCE][[page].]property[(index)] mode [ =] stream-name}

where mode is INPUT or DISPLAY and stream-name identifies a control rule.

To do this:

  1. Find or create a second control rule.
  2. Decide whether the property's value is to appear in an input field, or only be displayed.
  3. Use either the INPUT keyword or the DISPLAY keyword.

To make this value appear in an input field (modifiable), use the INPUT keyword with the name of the control rule that is to override the one referenced in the property.

To make the value appear display-only, use the DISPLAY keyword with the name of the control rule that is to override the one referenced in the property.

Examples:

{.myProperty INPUT Rule-HTML-Property instance}

{.myProperty DISPLAY Rule-HTML-Property instance}

Replace the italicized Rule-HTML-Property instance with the name of the Rule-HTML-Property instance that is to override the one referenced in the property.

If you find it easier, type an equal sign between DISPLAY or INPUT and the stream-name.

{.myProperty DISPLAY = Rule-HTML-Property instance}

If a property name matches a directive name

In rare cases, the name of your custom property is the same as the name of a directive. In this case, either include the REFERENCE keyword or enter white space between the opening delimiter and the reference. For example, if your property is named WHEN, use the REFERENCE keyword:

{REFERENCE .WHEN}

{REFERENCE myPage.myProperty(1)}

Related topics How to reference properties indirectly within directives

Directives