|
|
lookup JavaServer Page tag — lookupUse the lookup tag to retrieve and display:
- Case 1: A property value of an instance that is stored in the database but is not present on the clipboard. (When the instance is already on the clipboard, use the reference tag.)
- Case 2: A localized version of a property value using field value rules.
The syntax allowed for these two options differs, so they are explained separately below.
Case 1: Displaying a property value not on the clipboard
The lookup tag does not require the object that contains the value to be present on the clipboard.
To display a property value for an object without opening the object, first determine the following:
- The name of the property for which you seek the value
- The class that contains the instance that contains the property
- The property or properties that identify the key parts for that class
- The key parts of the specific instance
Here is an example, explained in detail below. GAGNP 10/11/07 typo
<pega:lookup className="Rule-Obj-HTML" property="pxCreateOperator">
<pega:key name="pyClassName" value="Work-" />
<pega:key name="pyStreamName" value="Newbook" />
</pega:lookup>
The pega:key tags are embedded in the body of the pega:lookup tag. The pega:key tag specifies the name for each key part of the instance.
To learn which properties form the key of any concrete class, review the Basics tab of a Class form. If the KEYS array is empty, review the Basics tab of the parent class rule or the associated class group data instance.
Attributes of the lookup tag
The property and className attributes are required.
Attribute |
Value |
||||||||||||||||||||||||||
property
|
Name of the property (second key part) |
||||||||||||||||||||||||||
className
|
Class of the property (Applies To key part) |
||||||||||||||||||||||||||
formatOutput
|
Optional. Set Omit this attribute or set This attribute is not available when the lookup tag is used to retrieve a field value rule. GENTJ BUG-771 4/2/07 |
||||||||||||||||||||||||||
|
mode bug-6514 GENTJ V5.5 |
Optional. Values are mode=normal Use
mode=literal Use mode="literal" to prevent any HTML encoding. The special characters listed in the table above are passed through unchanged during stream processing. mode=javascript
|
||||||||||||||||||||||||||
| useCache V6.3 BUG-73484 PathBreakers |
Optional. For database lookups, the retrieved value is ordinarily retained in a temporary clipboard page, similar to the approach used for linked properties. (Such pages are deleted upon the next Commit operation in the Thread.) This caching improves performance, by eliminating a database fetch operation if the same value is needed a little later. However, it can result in the display of stale data, or the use of stale data in a calculation or decision. You can use either of two approaches to prevent this caching: |
Setting Attributes of the key tag
Include a key tag that identifies a value for each key part. The name attributes is required. Either the value or ref attribute is required. GENTJ 9/19/07
To learn which properties form the key of any concrete class, review the Basics tab of a Class form. If the KEYS array is empty, review the Basics tab of the parent class rule.
Attribute |
Value |
name
|
Property that forms part of the key. |
value
|
Value of that key part. |
| ref | Expression that computes the value of that key part. BUG-15320 |
Examples:
<pega:key name=”KeyProperty” ref=”.SomeValue” />
<pega:key name=”KeyProperty” ref=”Param.SomeParameter” />
<pega:key name=”KeyProperty” ref=”$save(Something)” />
Case 1 example: database lookup
To display the Add Operator field for an HTML rule instance named Work-.Newbook without opening the instance to the clipboard:
1. Determine the property that corresponds to the Add Operator field.
The property that holds the Add Operator field is pxCreateOperator. To discover this, review any HTML rule, and then click the Rule Data toolbar button (
) on the toolbar. Scan the XML display to locate the property.
2. Determine the rule type of the HTML rule.
The rule type is Rule-Obj-HTML.
3. Determine the properties that hold the key parts for any HTML rule. You can find the key parts of any class by reviewing the Rule-Obj-Class rule instance that defines that class.
The key parts are pyClassName and pyStreamName.
4. Determine the values for the key parts for this specific instance.
The value of the first key part is Work-; the value for the second key part is Newbook.
The result:
<pega:lookup className="Rule-Obj-HTML" property="pxCreateOperator" >
<pega:key name="pyClassName" value="Work-" />
<pega:key name="pyStreamName" value="Newbook" />
</pega:lookup>
The lookup tag can be used within other tags, to supply values used as HTML attribute values and in XML tags.
If the property Table Type is not None and the Use for display (not validation)? box is checked, the output is translated according to the table contents. This can provide one approach to localization of the value.
Case 2: Displaying a localized property value
Using information in the General tab and field value rules for a property, you can use the lookup tag to convert a Single Value property text value from English (or another base language) to a locale-specific value.
To construct the localized values:
1. Select Field Value as the Table Type on the General tab of the property.
2. Enter the Applies To key part of the property as the Class value.
3. Enter the Property Name key part of the property as the Field Name value.
4. Create localization RuleSets for each supported language and a version for each. For example, if the application RuleSet is named ALPHA, create a RuleSet named ALPHA_fr_FR to hold the French version of selected rules. Create a version 01-01-01 for ALPHA_fr_FR and add it to your access group or application rule.
5. Sign on after you have acquired the ability to add rules to the localization RuleSets.
6. Create a single field value rule in each localization RuleSet. Enter the language-specific value in the Localized Label field.
7. Check the Use only for display (not validation)? box. Save the Property form.
8. In stream rules that display the property value, use the second form of the lookup JSP tag:
Attribute |
Value |
||||||||||||||||||||||||||
property
|
Reference to a property, in the context of the current stream rule. |
||||||||||||||||||||||||||
value
|
Optional. English value of the field, if a known constant value. |
||||||||||||||||||||||||||
formatOutput
|
Optional. Set Omit this attribute or set |
||||||||||||||||||||||||||
| mode |
Optional. Values are mode=normal Use
mode=literal Use mode="literal" to prevent any HTML encoding. The special characters listed in the table above are passed through unchanged during stream processing. mode=javascript
|
During stream processing, the system uses the user's locale to access the localization RuleSet. The output is the contents of the Localized Label field.
Errors
The text "No data available" appears when:
- The value of the value attribute is not valid.
- The value attribute is omitted but the property value is null.
- The value attribute is omitted but Table Type area of the General tab of the property does not support field value configuration.
Case 2 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."
Dynamic System Setting for V6.3 performance and behavior
The optional Dynamic System Setting prconfig/useUdfToRetrievePropertyValue/database can improve performance of the lookup JSP tag when the target property is not an exposed database column in the PegaRULES database. As a best practice, define this setting and set it to "true", unless your system does not include the database User Defined Function feature (which was introduced with V6.2SP2).
- If true, PRPC calls database User Defined Functions to extract the property value from the BLOB or Storage Stream column. Only the property value is returned from the database.
- If false, the BLOB column is returned from the database and analyzed by PRPC server software to extract the needed property value, a more expensive approach.
By default, the value of this Dynamic System Setting is false.
When this setting is true, property values retrieved by the lookup JSP tag are saved temporarily on a special clipboard page, visible in the Linked Properties page grouping of the Clipboard tool. Such pages are deleted upon the next Commit operation by the requestor Thread; this reduces the likelihood of stale values. See How to create or update a prconfig setting.