Skip to main content

         This documentation site is for previous versions. Visit our new documentation site for current releases.      

p:r JavaServer Page tag

Updated on August 16, 2022

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.


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.

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 m="block".


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 PRPC Version 5.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.

inputPresents the property in update mode so that a user can enter, or select, a value for the property.
javascript 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:

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

textCauses the <BR> tag received in an input textarea to be converted to a new line 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 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 * respectively) so that they appear correctly in the resulting display or output.

m attribute examples

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

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


Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best. is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us