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.
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)" />
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" />
Use the Param
keyword to identify an activity parameter value.
<pega:reference name="Param.myParameter" />
Each use of the reference tag updates the activity property — the value of the $this-value
keyword.
In the syntax presentations below:
[
and ]
define optional parts of the tag. Do not type the brackets.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 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 You can use the 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=" |
mode
|
Optional. The optional |
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.
The optional mode attribute can have one of six keyword values. If you omit the mode
attribute, the display
value is defaulted.
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 |
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. For a partial list, see Standard control rules accepting parameters.
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:
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 |
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 You can't use the ref attribute to set the value of a complex parameter. |
For example, the standard control 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" />
</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>