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:

Square bracket characters [ and ] define optional parts of the directive. Do not type the brackets.
Curly brace characters { and } mark the start and end of the directive.
Replace any text in italics with your choice of value of that type.

{[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. In releases before V5.4, the directive keyword `$mode-display` indicated read-only output. The `$mode-display` keyword is deprecated for new development; use `!mode-input` instead.
`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 (`<>`, `&` 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:

Find or create a second control rule.
Decide whether the property's value is to appear in an input field, or only be displayed.
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)}

Directives

Open topic with navigation