p:r JavaServer Page tag

Use the p:r tag to display the values of properties, to allow users to enter values for properties, and to insert parameter values. (The p:r tag provides identical capabilities as the reference tag, but requires less typing.)

For a full explanation of the reference tag, see JavaServer Page tags — Reference.

Syntax

Use p:r rather than pega:reference as the tag. As attributes, substitute n for name, f for format, and m for mode. In the syntax presentations below:

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

The n attribute is required. The f and m options are optional.

<p:r n="[propertyref]" [f="option"] [m="mode"]/>

Property name or symbol — n attribute

Enter a property reference or a dynamic reference to a variable in the current stream, such as $this-value or $page-message. For a list of these keywords, see How to reference properties indirectly.

Format — f attribute

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

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

Presentation — m attribute

The optional m attribute controls additional facets of presentation and processing. If you omit the m attribute, the default value is display.

Option

Results

block

The same as normal, except that line breaks are replaced by the string  . If the string appears, it is not altered.

You can't use the format attribute with m="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.

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.

input

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

javascript

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

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 PRPC 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 tag received in an input textarea to be converted to a new line character.

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 with a space. It also performs the conversions listed for the normal keyword, so that the true 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 (< >, & and &ast; respectively) so that they appear correctly in the resulting display or output.

m attribute examples

Property INFO has the value "Not italic or bold". The table shows the display that results from various settings for the m attribute, using an underscore to show added space characters.

Tag	User display (read-only)
<p:r n="INFO" />	_Not <i>italic</i> or <b>bold</b>_
<p:r n="INFO" m="display"/>	_Not <i>italic</i> or <b>bold</b>_
<p:r n="INFO" m="text"/>	Not <i>italic</i> or <b>bold</b>
<p:r n="INFO" m="stream"/>	Not <i>italic</i> or <b>bold</b>
<p:r n="INFO" m="literal"/>	Not italic or bold

How to reference properties indirectly within tags

JavaServer Page tags

p:r JavaServer Page tag

Option

Results

Character

Output

m attribute examples

Tag

User display (read-only)