Back Forward reference JavaServer Page tag

JavaServer Pages tags

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

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.

  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: GENTJ 3/27/07

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

  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 >

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 runtime context of a control rule, you can reference a parameter using the notation GENTJ 4/7/08 not section

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.

NoteYou can use the format attribute only when the mode attribute is omitted or is set to display. CLINB 12/6/06 Additionally, the name attribute must explicitly identify a property, not a parameter or symbolic reference. GENTJ 3/10/09

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 checkbox, because the control 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.

mode

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. SR-4597 B-22011

  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". GENTJ 3/10/09

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. CLINB 12/03

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. Bug-8993 Bug-11595 ERNSG 2/14/08

input

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

javascript

Advanced featureUseful 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.GENTJ CODE-630 12/23/08

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.

CautionWhen you save a stream rule that includes a reference tag with this mode, you may receive a security warning message: GRP-242 SOLOM 5.5

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

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. VANDJ 9/6/02

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 rule is ignored. ZELEK VANDJ 11/15/02

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

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. CLINB 12/6/06 needs work

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

Advanced featureC-2282The 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 a non-auto-generated control rule that accepts parameters. GENTJ 4/7/08 not section

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. PRKB-20657

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.

Advanced featureUse the following syntax to identify complex parameters: Proj-1128

  • .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 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 Decimal accepts three parameters named ThousandsSeparator, Precision, and Locale. A reference JSP tag can supply constant parameters using this syntax: STEWS DOC 3/23/06

<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: PROJ-1128

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

REMOVED: 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. GENTJ 4/7/08 not section rulesBUG-23314 3-12-2010
Related topics How to reference properties indirectly within tags
Standard rules Atlas — Standard control rules with parameters

Up JavaServer Page tags