reference JavaServer Page tag

Attribute

Value

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

You 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 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 checkbox, 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.

Value

Results

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

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

In 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

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

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

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: GRP-242 SOLOM 5.5

>>Warning>> Using mode=literal can expose the system to cross-site scripting attacks - use with 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 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 appears, even if it includes characters that are usually interpreted as HTML elements. VANDJ 9/6/02

On output, converts the <, >, & and * characters to the corresponding HTML entities (< >, & and * respectively) so that they appear correctly in the resulting display or output. The HTML Property 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

Tag

User display (read-only)

_Not <i>italic</i> or <b>bold</b>_

_Not <i>italic</i> or <b>bold</b>_

Not <i>italic</i> or <b>bold</b>

Not <i>italic</i> or <b>bold</b>

Not italic or bold

Attribute

   Description

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.

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