reference JavaServer Page tag

Use the reference tag to display the values of properties or activity parameters and to allow users to enter values for Single Value properties or single elements of aggregate properties.

The output of the reference tag normally reflects the control rule associated with the property. For example, if the property's control rule contains HTML code for a selection box, the property appears on a form (in read-write mode) as a selection box. In unusual situations, you can override the output format using the format attribute of the reference tag.

After you become familiar with the reference tag options, you can save typing by using the equivalent, but briefer, p:r tag. See JavaServer Page tags — p:r tag.

Simple formats

Display the value of a property

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

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

To display the value of a property on another page:

<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. The index may be a constant value or a property reference: 

<pega:reference name="myPage.myProperty(83)" />
	<pega:reference name="myPage.myProperty(California)" />
	<pega:reference name="myPage.myProperty(.pyState)" />

Let a user enter a value

To allow a user to update or enter the value for a Single Value property, use the mode attribute and input keyword. 

<pega:reference name="myProperty" mode="input" />

Insert the value of an activity parameter

Use the Param keyword to identify an activity parameter value. 

<pega:reference name="Param.myParameter" />

Set the value of the $this-value keyword

Each use of the reference tag updates the activity property — the value of the $this-value keyword.

Complete syntax

In the syntax presentations below:

  • Square bracket characters [ and ] define optional parts of the tag. Do not type the brackets.
  • JSP delimiters <pega: and /> mark the start and end of the tag.
  • Replace any text in italics with your choice of value of that type.

The name attribute is required. The format and mode options are optional. The param element is used only in special cases, described below. 

<pega:reference name="[propertyref]" [format="option"]
	[mode="mode"] >
	[ <pega:param name="paramname" value="paramvalue" ref="propref" >
</pega:reference >
Attribute Value
name

Reference to a property (or in certain cases to a parameter value) in the context of the current stream rule.

For a property on a page other than the current page, identify the page name and its class on the Pages & Classes tab of the form.

You can use an indirect property reference here, such as $this-value or $page-message. If you use the $this keyword, the reference tag must appear within the body of a forEach, withEmbedded, or withReference JSP tag. See How to reference properties indirectly within tags.

If the run time context of a control rule, you can reference a parameter using the notation

name="param.zzzzzz"

where zzzzz is a scalar parameter defined on the Parameters tab of the Section form or control form. See Parameters.

format Optional. Include the optional format attribute to present the property using a control rule other than the one referenced in the property definition. Identify another control rule within double quotes.

You can use the format attribute only when the mode attribute is omitted or is set to display. Additionally, the name attribute must explicitly identify a property, not a parameter or symbolic reference.

If the control rule uses parameters, you can set parameter values using the parameter syntax. See Parameters. 

<pega:param name="name" value="value >

For example, assume the property named IsSmarterThanAverage normally is presented as a check box, because the control rule referenced in the property is Checkbox. Include format=" TFDropBox " to present this property as a drop-box containing True and False as choices.

mode Optional. The optional mode attribute controls additional facets of presentation and processing described below.

Even when the mode is display, you cannot present an entire Value List or Value Group property, only a single element of an aggregate property.

Values for the mode attribute

The optional mode attribute can have one of six keyword values. If you omit the mode attribute, the display value is defaulted.

Value Results
block The same as normal, except that line breaks are replaced by the string <br/>. If the string <br> appears, it is not altered.

You can't use the format attribute with mode="block".
display Instructs the system to use a control rule as read-only, detectable as ! $mode-input.) Stream processing adds a single space before the value and a single space after the value.

The $mode-display keyword is deprecated for new development; use JSP tags and the display option.

editable Presents the property in update mode so that a user can enter or select a value for the property. Editable overrides the input state of stream rule including the control.
input Presents the property in update mode so that a user can enter, or select, a value for the property.
javascript Useful when the result of the <pega:reference > is to become part of a JavaScript script. Presents the property value in read-only mode, with certain characters within the property value escaped to a backslash equivalent. No control is applied.

For example, assume the value of property MyProperty is This is a "demo". If a stream contains the fragment: 

var result="<pega:reference name=".MyProperty" mode="javascript" />";

The output of stream processing is:

var result = "This is a \"demo\"";
which is a valid JavaScript statement. Six characters are escaped:
Character Encoded Output
backspace \b
tab \t
formfeed \f
double quote \"
single quote \'
backslash \\
literal Causes the value of the property to be masked from HTML processing. Use this if the value may contain angle bracket characters or other HTML elements that are not to be interpreted.

When you save a stream rule that includes a reference tag with this mode, you may receive a security warning message:

>>Warning>> Using mode=literal can expose the system to cross-site scripting attacks - use with caution.
CAUTION:
For maximum security, do not use mode="literal" anywhere in the HTML code that formats a property value for a property that is an input value. For example, assume that a <textarea >on a non-autogenerated flow action form allows input of arbitrary text (including angle bracket characters) that is submitted to Pega Platform and returned to the browser in literal mode (not encoded). A malicious user could "inject" harmful JavaScript source code into the browser, a tactic loosely termed "cross-site scripting" or XSS.

Consider richtext mode as a more secure alternative.

In all modes other than literal, the angle brackets are converted to HTML entities (<, >), invalidating the JavaScript code.

In rare situations, your application may require mode="literal" in stream rules. For example, the JavaScript target of a button, executed with the onClick= attribute, may be dynamic. Design and test such cases with extreme care.

richtext Causes filtering of user-supplied HTML such as created by the RichTextEditor control. This is a more secure choice than literal. The filtering preserves the browser display appearance but removes inappropriate markup that might introduce or allow cross-site scripting.
text Causes the <BR> tag received in an input textarea to be converted to a new line character. Additionally, performs the conversions listed for the normal keyword.
stream On output, instructs 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 On output, converts 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 control rule identified in the property is ignored.

When you specify normal, stream processing does not place any space characters before and after the value (unlike the processing for the display keyword).

Mode examples

Property INFO has the value "Not <i>italic</i> or <b>bold</b>". The table shows the display that results from various modes, using an underscore to show added space characters.

Tag User display (read-only)
<pega:reference name="INFO" /> 
_Not <i>italic</i> or <b>bold</b>_
<pega:reference name="INFO" mode="display"/> 
_Not <i>italic</i> or <b>bold</b>_
<pega:reference name="INFO" mode="text"/> 
Not <i>italic</i> or <b>bold</b>
<pega:reference name="INFO" mode="stream"/> 
Not <i>italic</i> or <b>bold</b>
<pega:reference name="INFO" mode="literal"/> 

                Not
                italic
                or
                bold

Parameters for non-auto-generated control rules

The optional embedded <pega:param... > elements typically appear in system-generated HTML code for harnesses and flow actions. However, they can be handcrafted. These elements supplies parameter values stored on a parameter page for the property. (This page is similar to but distinct from the parameter pages of activities.)

The <pega:param... > element is used only when the reference JSP tag references a property that uses a non-auto-generated control rule that accepts parameters.

Typically, the name and data type of each parameter is recorded on the Parameters tab of the rule.

The <pega:param...> element requires the name attribute and either the value or ref attribute (not both).

Attribute Description
name Name of a parameter that appears on the Parameters tab of a control rule. This may be a scalar parameter or a complex parameter. Complex parameters include parentheses or a period character in the name.

Use the following syntax to identify complex parameters:

  • .MyValueList() — for a Value List or Value Group structure
  • .MyPageList().Prop1, MyPageList().Prop2 — for parameters Prop1 and Prop2 on the embedded pages of the Page List structure MyPageList()

As with scalar parameters, these complex parameters are not true properties — no Rule-Obj-Property rule exists for them — but they mimic the structure of the property types. Complex parameter definitions are accepted on the Parameters tab of the control rule form.

value Optional. Enter a literal constant consistent with the data type of the parameter String, Boolean, or Integer as the source of the value for the parameter. If the name attribute identifies a complex parameter, the value attribute is required.
ref Optional. Enter a property reference (consistent with the data type of the parameter) as the source of the value. This can use the scratchpad and $save() function to retrieve a value saved to the scratchpad earlier with the Save JSP tag.

You can't use the ref attribute to set the value of a complex parameter.

For example, the standard control rule named accepts three parameters named ThousandsSeparator, Precision, and Locale. A reference JSP tag can supply constant parameters using this syntax: 

<pega:reference name=".LoanAmount" mode="display" format="Decimal">
	<pega:param name="ThousandsSeparator" value="-1" />
	<pega:param name="Precision" value="3" />
	<pega:param name="Locale" value="en-us" />
</pega:reference>

The following examples illustrate setting the value of complex parameters:

<pega:reference name=".GameResults" >
	<pega:param name=".ListElement(4)" value="Boston"/>
	<pega:param name=".GroupElement(NYC)" value="Yankees" />
	<pega:param name=".Embedded(4).Embedded(MA).Size" value="3.14" />
	<pega:param name=".MyList(<append>)" value="Maine" />
</pega:reference>

JavaServer Page tags