examples: localized values Example 1

The General tab of the standard property @baseclass.pyCaption indicates that values are defined by field value rules:

Hundreds of standard field value rule define text values for the property pyCaption. The field value rule

@baseclass.pyCaption.City in RuleSet Pega-ProCom contains an English text value "City"; the same value in a language-specific RuleSet ALPHA_FR (for French-speaking locales) can have a Localized Label of "Ville". The JSP tag is:

<pega:lookup property=".pyCaption" value="City" />

Example 2

An application contains a property Order.BoxColor in RuleSet ALPHA. In the English base application, values of this property are "red", "yellow", "magenta", and so on.

To support Italian-speaking application users, the developers add a localization RuleSet named ALPHA_it_IT. To support French-speaking users, another localization RuleSet named ALPHA_it_FR is created.

Two sets of field value rules are created, one for each color value in each RuleSet. For example, each RuleSet may contain rules with these key parts:

Order.BoxColor.red Order.BoxColor.yellow

and so on. The Localized Label of the first field value rule contains rosso for the ALPHA_it_IT RuleSet and rouge for the ALPHA_fr_FR RuleSet.

The JSP tag is:

<pega:lookup property=".BoxColor" formatOutput="false" />

For users working with a locale setting of it_IT, stream processing produces "rosso" when Order.BoxColor is red.

Users with a locale setting of fr_FR see "rouge."

onlyonce JavaServer Page tag

Purpose

Use the onlyonce JSP tag to indicate that text within the body of the tag is to be included in the stream processing output only the first time that an onlyonce tag of that name is found.

This tag is primarily useful in complex HTML streams to prevent multiple definitions of JavaScript functions.

When to use

When entering HTML source code directly into the HTML tab of a control rule (or similar form), you can minimize the size of the resulting HTML document with the <pega:onlyonce > and <pega:static > tags. See Including only one copy of JavaScript code in More about control rules.

Example

For example, this tag is named Alpha.

<pega:onlyonce name="Alpha" >

The work object id is <pega:reference name=".pyID">.

</pega:onlyonce >

During stream processing, if another onlyonce tag named Alpha appears, the body of the second (and later) tags are skipped over and not processed.

Complete syntax

In the syntax presentations below:

 JSP delimiters <pega: and </pega: mark the start and end of the tag.

 Replace any text in italics with your choice of value of that type.

<pega:onlyonce name="name" >

HTML, XML or JavaScript code to process only once

</pega:onlyonce >

The name attribute is required.

Attribute Description name

Set the name attribute to an arbitrary non-blank text value. Case is significant. During stream processing, second and later appearances of an onlyonce tag with this name cause the body of the tag to be treated as a comment, contributing nothing to the stream results.

properties-mapping JavaServer Page tag

Use the properties-mapping JSP tag to enclose a list of from-to property mappings defined by the

<property-map > JSP tags. This tag appears as an optional part of the listToList JSP tag.

For example:

<pega:properties-map >

<pega:property-map from=".A" to=".ALPHA" />

<pega:property-map from=".B" to=".BETA" />

</pega:properties-map>

In this example, a property named A on an embedded pages of a source Page List is mapped to a property named ALPHA on the embedded pages of a target Page List property. Similarly, property B is mapped to BETA.

Complete syntax

In the syntax presentation below:

 JSP delimiters <pega:...> and </pega:...> mark the start and end of the tag.

 Replace any text in italics with your choice of value of that type.

<pega:properties-mapping">

<pega:property-mapping from="propertyref" to="propertyref" />

</pega:properties-mapping>

At least one <pega:property-mapping ....> tag is required. For the <pega:property-mapping > JSP tag, both the from and to attributes are required.

p:r JavaServer Page tag

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

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.

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 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 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 italic or bold_

<p:r n="INFO" m="display"/> _Not italic or bold_

<p:r n="INFO" m="text"/> Not italic or bold

<p:r n="INFO" m="stream"/> Not italic or bold

<p:r n="INFO" m="literal"/> Not italic or bold

reference JavaServer Page tag

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

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.

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:

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

 Square bracket characters [ and ] define optional parts of the tag. Do not type the brackets.

 JSP delimiters <pega: and /> mark the start and end of the tag.

 Replace any text in italics with your choice of value of that type.

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

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.

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

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.

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

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 . If the string

appears, it is not altered.

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

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.

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.

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.

In all modes other than literal, the angle brackets are converted to HTML entities (<, >), invalidating the JavaScript code.

text

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

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.

The control rule identified in the property rule is ignored.

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

Mode examples

Property INFO has the value "Not italic or bold". 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 italic or bold_

<pega:reference name="INFO"

mode="display"/> _Not italic or bold_

<pega:reference

name="INFO" mode="text"/> Not italic or bold

<pega:reference name="INFO"

mode="stream"/> Not italic or bold

<pega:reference name="INFO"

mode="literal"/> Not italic or bold Parameters for non-auto-generated control rules

The 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

In document Pega JSP (Page 25-46)