Back Forward reference JavaServer Page tag

JavaServer Pages tags

 zzz Show all 

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 HTML Property rule associated with the property. For example, if the property's HTML Property 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.

TipAfter 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.

 zzz 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 must be a constant value:

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

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" />

 zzz Complete syntax

In the syntax presentations below:

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 >




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 runtime context of an HTML Property rule, you can reference a parameter using the notation


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


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

NoteYou 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 HTML property 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 HTML Property rule referenced in the property rule is Checkbox. Include format="TFDropBox" to present this property as a drop-box containing True and False as choices.


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

NoteEven when the mode is display, you can't present an entire Value List or Value Group property, only a single element of an aggregate property.

 zzz 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.




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".


Instructs the system to use an HTML Property rule as read-only, detectable as !$mode-input.) Stream processing adds a single space before the value and a single space after the value.

OldIn releases before V5.4, the keyword $mode-display indicated read-only output. The $mode-display keyword is deprecated for new development; use JSP tags and the display option.


Presents the property in update mode so that a user can enter, or select, a value for the property.


AdvancedUseful 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 HTML property rule 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:


Encoded Output

backspace  /b
tab  /t
formfeed  /f
double quote  /"
single quote  /'
backslash  //

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.

CautionWhen 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.

CautionFor 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 Process Commander 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.

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.


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.


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 is displayed, even if it includes characters that are usually interpreted as HTML elements.


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 HTML Property rule identified in the property rule 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).


Similar to normal, but <BR> elements in the HTML source are converted to a newline character, preserving line breaks.

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.


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

 zzz Parameters for HTML Property rules

AdvancedThe optional embedded <pega:param... > elements typically appear in system-generated HTML code for harness rules and flow action rules. 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 an HTML property rule that accepts parameters.

Typically, the name and data type of each parameter is recorded on the Parameters tab of the rule. For a partial list, see Standard HTML Property rules accepting parameters.

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




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

AdvancedUse 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 property rules — 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 HTML Property rule form.


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.


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 HTML Property rule named Decimal 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" />

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" />

Parameters marked as required on the Parameters tab of the HTML Property form are validated as to name and type when you save a rule containing them.

Related topics How to reference properties indirectly within tags
Standard rules Atlas — Standard HTML Property rules with parameters

zzz JavaServer Page tags