Localizing an Application

Localizing an Application

Introduction

Overview

For companies which need to incorporate multi-language support in their BPM/BRE

solutions, PegaRULES Process Commander’s architecture is designed to provide multi-

language capabilities in both the user and application environments (business solutions).

Application screens can dynamically integrate the language preferences of both the user

and the customer, which is useful in customer service settings. Thus, multi-lingual users

that handle calls from multi-lingual customers can optionally see structural information in

their preferred language, while seeing scripts, descriptions, and correspondence as the

customer would see them. The rules architecture seamlessly integrates elements based

on user preferences and the language of the current customer.

Although the core development environment is based in English, beginning in Version 4.2

Service Pack 5, PegaRULES has the ability to present users with forms and rule

translations in their preferred language. The default English presentation may be

overridden with the user’s choice of language in the following key areas:

• Application screens, fields, reports, and some error messages

• Customer correspondence templates

• User interface for workers and managers

Note that only the user interface functionality is being localized. The PegaRULES

localization technology is an aid to customers who wish to translate their application; it is

not meant to be an entire complete solution in all languages.

The localization process involves the following steps:

1. Set the users’ environment to their desired language

2. Enable localization in Process Commander

3. Create a localization-ready application, and then translate the labels that users would

see into all desired languages.

These steps will be reviewed in detail in this document.

Important: As developers create applications to be localized, they should

endeavor to comply with all the SmartBuild practices and guard rails; this will

make localization and maintenance of the application much easier and more

efficient.

Unicode Support Details

Version 4 of Process Commander supports the Unicode standard, which accommodates

handling, importing, and exporting character sets beyond the Roman character set

(ASCII).

“Unicode” is actually a general term encompassing many aspects of different character

sets. UTF-8 is a one- to four-byte encoding of Unicode, and is used by PegaRULES

when writing output or HTTP on the file system. UTF-16 is a two-byte form of Unicode.

Process Commander runs in the Java Virtual Machine (JVM); by default, the JVM strings

are UTF-16.

Process Commander uses standard JDBC interfaces to integrate with the PegaRULES

database. As long as the database supports Unicode, the JDBC drivers (which run as

part of the JVM) should take care of the data transformation from UTF-16 to whatever data

type the database expects. Thus, Process Commander supports whatever the customer

database and their chosen JDBC drivers support, including both UTF-8 and UTF-16.

Important: For most non-localized Release 4.2 installations using Microsoft SQL Server,

the following setting is included, either in the JDBC URL or the DataSource setting:

all the exposed columns. If

the existing database does not have Unicode on all the columns, the database

must be changed. For some databases, this may require reinstalling the

database software (and then reinstalling any other software - such as application

servers - that require being installed after the database software.

el and click on Regional and Language

Options.

NOTE: If Cancel is clicked when prompted for the CD, the installed fonts are not removed

and the web page may now display correctly. If Cancel is clicked, the language selected

is not completely installed, and the checkbox is removed from the Language Settings for

the System panel.

If the additional files are installed from the CD, other languages may now display correctly

also, since some fonts are shared across multiple scripts. (For example, after clicking

Cancel during the install for Traditional Chinese, a font suitable for it was available, but no

support for Japanese. After completing the full installation for Traditional Chinese, a font

that was suitable for Japanese was also present – and some, but not all, glyphs in

Simplified Chinese.)

3. Font support may be added for multiple languages by installing Microsoft Office

International Support (and in particular the so-called “Universal Font” Arial Unicode MS).

See Microsoft Knowledge Base article 287247 for more information.

Anyone who wishes to write an application in a language other than English, or localize an

existing English application into another language, would begin by obtaining the

appropriate Language Pack, and then developing/translating their own application rules

into that language.

Thus, for the standard PegaRULES RuleSets, the following is an example of the list of the

RuleSets and locale variants:

AcmeProducts_es:03-02

AcmeRulePro_es:04-01

to see if a

Rule-RuleSet-Name instance for a localized version of that RuleSet is defined in the

database. If it is, the existing localized variants of that RuleSet are inserted automatically

before the base RuleSet. When the user’s Organization, Division, or Access Group

RuleSets are added, the localization RuleSets are included automatically as well. When

the RuleSets are fully assembled, each requestor will have two RuleSet Lists associated

with it: the basic RuleSet List (which appears in the user’s Profile), and the localized

RuleSet List, which is associated with the requestor itself on the Clipboard.

Important Notes about Localized RuleSets

• When changing the Locale, it is not possible to switch out individual RuleSets –

the entire list of PegaRULES Process Commander rules will be swapped.

• The base RuleSets for PegaRULES Process Commander are in US English (by

design), as well as the developer environment. If a company is developing a

multilingual application for locales other than en_US, it is suggested that the base

application RuleSets also be in US English, even though that may not be the

preferred language for the customer. Since the customer will be building several

localized RuleSets, and as the PegaRULES RuleSets are all in US English,

having the application RuleSets in US English also will provide consistency

across the product. For example, if a French company (“La Paniere”) creates an

application, their base RuleSet would be in English (PaniereCo: 01-01), and their

Rules would be stored in their localized RuleSet (PaniereCo_fr_FR:01-01).

• The system tests each possible localization against the Rule-RuleSet-Name (for

the base RuleSet) only – not against any Rule-RuleSet-Versions. Once it has

determined the appropriate name for the RuleSet (by taking the existing base

RuleSet and adding the appropriate localization designation), it will search for the

RuleSet and Version which match the existing base RuleSet and Version. For

example, if a valid base RuleSet exists with a current version (“AcmeProducts:04-

02”), the system will look for the localized version of that RuleSet

(“AcmeProducts_fr:04-02”). If that RuleSet and Version don’t exist, standard Rule

Resolution rules will apply: other RuleSets and Versions within the major version

(“AcmeProducts_fr:04-01” or “AcmeProducts_fr:04-02-10”) can be used, but

RuleSets and Versions outside the major version (“AcmeProducts_fr:03-05”)

cannot.

Developers must therefore be careful when naming application RuleSets. If the

application base RuleSet is version 04-02, do not create a localized version of

that RuleSet and start the version numbering again at 01-01 (since it’s a new

version of the RuleSet). The localized RuleSet version (“AcmeProducts_fr:03-

02”) must match the base version (“AcmeProducts:03-02”).

CONFIDENTIAL 23 RuleSets and Localization

• If a user changes the locale (either by changing it in the browser or by using the

Set Locale tool), the system will automatically take the original base list of Rules

(that is displayed in the Profile), and re-localize this list based on the new locale

information.

French (in France) or French Canadian, they would get a list of 18 RuleSets. If

they were to switch to Spanish, they would only receive 14 RuleSets, as there are

fewer Spanish RuleSets available.

Displaying Localized RuleSets

CONFIDENTIAL 25 RuleSets and Localization

These localization RuleSets should be added into the developers’ Access Group, in the

order they appear on the clipboard. Thus, the most specific localization RuleSets should

be listed before the less specific localized RuleSets, which in turn should be listed before

the base PegaRULES RuleSets, to assure appropriate Rule Resolution processing.

26 CONFIDENTIAL

Building a Localized Application

Localizing the user experience for PegaRULES Process Commander can be divided into

two main parts:

• the application (Work Items)

• Process Commander (the Portal, standard reports)

The Portals for Work Users and Work Managers are localized in the Language Packs,

along with the standard manager’s reports. Note that the developer tools (such as “Where

Am I?” are not localized.)

The Work Item (or items) are the focus of applications written in Process Commander, and

as such, are custom to each application. These must be localized by the developer, using

the processes described in this section.

Work-

Confirmation Notes (flows only)

pyCountry

Data-Party

names of all countries

pyCountryCode

@baseclass

codes for all the countries

pyHistoryMemo

Work-

history messages, Audit Notes

(flows)

pyInstructions

@baseclass

Instructions (flows only)

pyMessageLabel

@baseclass

alerts, error messages, help

pyStatusWork

Work-

the status of the work item (flows

only)

pyStatusLabel

@baseclass

the status of the Assignments,

and also information from the

process the system is completing

(creating, saving, deleting)

IMPORTANT: For all rules which have autogenerated HTML, it is required to define new

field values in the correct “grouping.” These rules include:

• harnesses

• sections

• flow actions

The localization functionality for these rules will look for the appropriate Field Value for a

label in a specific “group;” if the Field Value has been defined in a different group, then the

system will not find it and will not localize that label.

In the sections below which give details about these rules, the label fields on the rule and

their associated “grouping” are listed.

Assignment to '{1 InstructionsLookup}' completed by

performing a '{2 CaptionLookup}'.

As stated earlier, the first parameter for this Field Value is a reference to the property

Primary.pyInstructions, which contains instructions. A run-time resolving of this Field

Value might result in a message such as:

Assignment to Review item and return to manager completed

by performing a Return to Manager.

would be set on the specified page.

Backward compatibility

Originally, the Message field of Page-Set-Messages and Property-Set-Messages referred

to a Rule-Message instance. To ensure backward compatibility with existing activities in

applications written before the release of Service Pack 5, this functionality will still be

supported.

• If the Category field is blank, then the data in the Message field is parsed as a

Rule-Message instance.

• If the Category field contains data, then the data in the Message field is parsed

as a Rule-Obj-FieldValue instance.

History/Audit Fields

The functionality of storing and displaying History or Audit data in general is different than

other localization features, and should be treated separately. This functionality includes:

• the History-Add method in Activities

• the Audit field in flows

For most labels, the localization lookup is immediate: the user completes the action of

Opening a New Item, for example, and the system does the localization lookup and

displays the new work item in the user’s chosen language. History messages, however,

have two distinct steps when a user completes an action:

• creating and storing/saving the data

• displaying the data

The History message may be created when a user completes an action – transferring a

work item, resolving it, etc. – but it will not be viewed until the user actually clicks on the

View History button.

pyConfirmationNote

Instructions

@baseclass

pyInstructions

StatusWork

Work-

pyStatusWork

StatusAssign

@baseclass

pyStatusLabel

Creating Flow Actions

The flow action rules are all displayed in the Take Action drop-down menu, where the

user chooses an action for the work item. Some of these may be custom-created by the

developer, or the developer may use the standard ones provided with Process

Commander.

HTML Tab

The developer must begin by ascertaining that localization is possible for a particular flow

action. When creating an application, one of the recommended procedures is to copy

existing flow actions; in order to enable localization, the developer should start with a flow

action rule from Service Pack 5.

CONFIDENTIAL 49 Creating the Application

There are a number of settings on the HTML tab which affect localization.

Setting Description Localization value

Auto Generated

HTML

Choice: enabled or disabled

This checkbox determines

whether there is custom HTML in

this window. If auto generate is

on, the system generates the

HTML from the information on the

Form tab. If auto generate is off,

the system assumes that custom

HTML has been entered into this

window and shouldn’t be

overwritten with generated HTML.

checked (enabled)

In order for localization to

be enabled, the HTML

must be auto-generated. If

this box is unchecked, the

Localize box will

automatically uncheck.

described above. The HTML tab should have the following settings:

• Auto-generated HTML: enabled (checked)

• Localize?: enabled (checked)

• Omit extra spaces: enabled (checked)

• Generate for: JSP

58 CONFIDENTIAL Creating the Application

As with flow actions, the Layout tab should be displayed in “smart frames,” and each

user-visible label should have a corresponding Field Value created in order to localize its

text.

For the fields on a section, Field Values should be defined on the following “grouping

properties.”

Label type

buttons, URLs

@baseclass

pyButtonLabel

Title

header, tabs

@baseclass

pyCaption

Tooltips

button, URL, icon

@baseclass

pyActionPrompt

Value

labels

@baseclass

pyCaption

Creating Reports

In Service Pack 5, many of the standard Summary View and List View rules have been

localized. Their shared localization functionality is described here; for functionality specific

to the rule type, please refer to the Summary View or List View sections below.

Like the work item Rules, localization begins for both View rules with a Localize?

checkbox on the HTML tab. This box must be checked for localization to be enabled for

the reports.

Unlike harnesses and sections, it is not possible to change the HTML in this tab – it is

generated HTML only. Thus, the Auto Generate HTML checkbox (and related

checkboxes, like Omit extra spaces) is not necessary and does not display.

tab.

abled, these

label fields will automatically search for Field Value references. If an appropriate Field

Value is not found, then the system will return the text which is in the label field.


On both the Content and the Drill Down tabs, the labels are in Caption fields.


The Organize tab, on the other hand, displays the captions for buttons or links on the

report:

Thus, Field Values which are defined for these labels should be in the following groups:

Label type

Usage

Field Value

Applies To class

Field Name (grouping

property)

Caption (Content or

Drill Down tab)

report labels

@baseclass

pyCaption

Caption (Organize

tab)

button or link

captions

@baseclass

pyButtonLabel

Full Description

field (History tab)

report title

@baseclass

pyMessageLabel


List Views

List View rules have different labels than the Summary Views. On the Display Fields tab,

the Field Labels contain the column headings for the list.


There are a number of Caption fields on the Content tab, but none of these are localized,

as the user doesn’t see them.

The Organize tab also contains Caption fields; as with the Summary View rule, these are

button labels or links.

Thus, Field Values which are defined for these labels should be in the following groups:

Label type

Usage

Field Value

Applies To class

Field Name (grouping

property)

Field Label (Display

Fields tab)

Column headings

@baseclass

pyCaption

Caption (Organize

tab)

button or link

captions

@baseclass

pyButtonLabel

Full Description

field (History tab)

report title

@baseclass

pyMessageLabel


Correspondence

Correspondence rules include:

• Rule-Obj-Corr

• Rule-Corr-Fragment

Localizing correspondence is a completely different process than localizing the work item

that a user sees. The work item is localized based on the user’s locale, and displays

according to the person who is working on the item. However, there are two people

involved in correspondence - the sender and the recipient. Therefore, using Field Values

to localize the item in the language of the user who is creating the item may not be correct,

as the correspondence really needs to be in the language of the person who is receiving it,

so they may read and act upon the information.

language correspondence rule is written, that rule should be copied, and a circumstanced

version of that rule should be created, based on the property which indicates in which

language a customer wishes to see their correspondence.

Below is an example of a base-language correspondence rule (in English), with no

circumstance.


This version of the rule has been circumstanced in French, and the text translated:

Using Custom Code in a Localized

Application

If a developer does choose to use custom code, there are special localization features

which should be employed, to make sure that this custom code is still localizable.

Pack 5. There are other

HTML rules where the code is not automatically generated, but the HTML is written

directly in the rule. These include:

• Rule-Obj-HTML

• Rule-HTML-Fragment

• Rule-HTML-Property

These rules may be generated either to use industry-standard JSP tags (recommended)

or to use the custom Pega directives (generate for HTML).

As with the other rule localization, where labels are needed, these references must not

contain hard-coded English, but must point to Field Values, where the Localized Label

field provides a translation into the required language. Different code is used depending

upon whether the HTML rule is generated to use JSP or custom Pega (HTML) tags.

Important: As with the generated HTML rules (described in the previous section), if there

are no existing Field Values for the reference, the system will return the text label (“Expand

all”).

JSP lookup tag

The ActionAddAttachment2 rule provides an example of hard-coded English in an

HTML rule.

In this rule, terms such as “Attach File” and “Upload in Progress . . .” are hard-coded into

the HTML display. In order to localize this rule, these labels must be changed to Field

Value references.

Using the pega:lookup localization feature

All localized values for the lookup tags are stored as Rule-Obj-FieldValue instances. As

stated previously, the Rule-Obj-FieldValue class contains three key properties:

• Class Name (pyClassName) – the class the Field Value is defined on

• Field Name (pyFieldName) – the name of the property the Field Value is defined

on (in localization, the name of the “grouping property”)

• Field Value (pyFieldValue) – the actual key name of the Field Value

There is also another field on the rule, .pyLocalizedValue, which is the value in the

Localized Label field which holds the translation of the Short Description.

In order for a lookup tag to find the appropriate instance in the database to retrieve, it will

require all of these tags to be identified.

There are two different ways that lookup can be enabled for localization. For each of

these, the syntax does not specify the class name of the item; this syntax signals the

system to use Rule-Obj-FieldValue as the class.

Syntax

<pega:lookup property=”.aProperty” />

Example:

<pega:lookup property=”.pyButtonLabel” />

Attributes

Attribute Name Description

property

required

the class name of the property in the database

Notes

When this syntax is used to look up Field Values, there are a number of assumptions

made to complete the information needed for the lookup:

• Class name: Rule-Obj-FieldValue

• Key – “Defined on” class name: the class of the primary page present at runtime

(or its ancestors, which would include @baseclass)

• Key – Field Name: the name of the specified property (the grouping property:

“.pyButtonLabel”)

• Key – Field Value: the value of the specified property at runtime

In this example, the system will use the grouping property name “.pyButtonLabel” to look

up a value. It will look up the Rule-Obj-FieldValue instance with the following information:

• Class Name (pyClassName) – the class of the primary page (in most instances,

the system will end up finding the Field Values defined on @baseclass)

• Field Name (pyFieldName) – .pyButtonLabel

• Field Value (pyFieldValue) – the current value of .pyButtonLabel

(“RemoveFromFolder”)

The system would look at the current value of .pyButtonLabel, and then return the rule-

resolved value stored in the .pyLocalizedValue. (This could be the German, French, or

other language version of the “Remove from folder” phrase.)

Important: For this reference to work correctly, the developer must be sure that there will

be a current value of the referenced Field Value on the clipboard at execution time.

72 CONFIDENTIAL Localization References in HTML Code

Localization Lookup: Second Variation

Syntax

<pega:lookup property=”somePage.aProperty” value=”fieldValue”/>

Example:

<pega:lookup property=”pxRequestor.pyCaption” value=”Engage Manager”/>

Attributes

Attribute Name Description

property

required

the Field Name – the name of the “grouping” property of the Field

Value rule. (May include the “pxRequestor” page.)

value

required

the Field Value (key name) of the Rule-Obj-FieldValue rule in the

system

formatOutput

optional

true/false value that determines whether or not the output will be

formatted using a Rule-HTML-Property Rule.

Notes

If the developer wishes to use a specific Field Value and look up its localized value, then

this alternate syntax may be used.

This syntax requires that a page be specified as part of the property reference, so the

system may determine the class name from that page. Since the “grouping property” is

generally just used to group the field values (as opposed to being an actual property), it

may not be on an actual page in the clipboard at the time it is referenced. A page needs

to be referenced which will always be on the clipboard, so the system may then search

the class hierarchy and find the Field Values in @baseclass. Since the requestor page is

always present for a work item, that page is frequently used as a “placeholder” page for

the “grouping” property.

Additional References

If the Field Values have parameter or property references defined, these references must

have corresponding data in the Field Value call. Thus, if the Field Value definition for

Processes for Application was:

Processes for Application {1}

then the lookup reference would have to include a parameter for that Field Value:

CONFIDENTIAL 73 Localization References in HTML Code

<pega:lookup property=”pxRequestor.pyCaption” value=”Processes for

Application\tparam.StartMortgage”/>

As with the Field Value references in activity methods, the syntax for the parameter or

property references is tab-delimited (“\t”).

getLocalizedTextForString

In addition to using JSP tags, there is a Java method which is also available for localizing

text in HTML rules: getLocalizedTextForString. This feature allows a “token” to be put

into the HTML rule, with a linked Rule-Obj-FieldValue instance which is localizable.

getLocalizedTextForString takes two parameters - Ref and String – and returns a

string.

string=tools.getLocalizedTextForString(“page.property”, “Value”)

As explained in the previous section, the Rule-Obj-FieldValue class contains three key

properties:

• Class Name

• Field Name

• Field Value

There is also another field on the rule, .pyLocalizedValue, which is the value in the

Localized Label field which holds the translation of the Short Description.

The first parameter, Ref, is the reference to the page and property name for the text string

to be localized. The system derives the Class Name from the specified page & property

reference, and then also uses this property reference as the Field Name. Thus, this

reference must be a named page on the clipboard. Frequently, pxRequestor is used, as

this is a named page which will always be present on the clipboard, but other pages

(pyViewPageLocale, for example) could be used.

The second parameter, String, is the actual Field Value (the key name for the Rule-Obj-

FieldValue instance):

• Add New Party

• Export To Excel

• Refresh List

etc.

Referencing getLocalizedTextForString in HTML Properties

Once the Field Values have been created, they may be referenced by

getLocalizedTextForString in HTML rules. These references may be set up in hundreds of

ways (as most references can be).

The first decision the developer must make when determining how to reference

getLocalizedTextForString is whether to cache the information or not. If the string text is

going to be referenced several times in the rule, then it is more efficient to cache that

information locally and retrieve it from the cache, rather than going out to the database to


retrieve the value each time. If there is only going to be one reference to the text in the

rule, then caching is probably not necessary.

Another decision for the developer is whether to use Java or HTML code to refer to the

text string. If the code in the rule is mostly Java, then that may be the most efficient way to

reference the string; on the other hand, if the code is mostly HTML, it is also possible to

set up the reference so that switching into Java code in the middle of the HTML is not

necessary.

NOTE: The examples below show how getLocalizedTextForString is used in Process

Commander rules. Developers would not be changing these particular rules, but should

look at these examples to determine how best to change rules in their own application, or

code them properly during the application design.

Example 1: only one reference to strings

This code does not include caching, as there is only one reference to the string. This

HTML rule is generated for JSP.

Code snippet from Rule-Obj-HTML instance Data-Gadget.myWorklistExpandContract

<%

ClipboardPage reqPage = tools.getRequestor().getRequestorPage();

String userId = reqPage.getString("pyUserIdentifier");

String userServer = reqPage.getString("pxReqURI");

String SMALLLIST = "small";

String FULLLIST = "full";

String EXPANDTEXT =

tools.getLocalizedTextForString("pxRequestor.pyCaption","Expand");

String CONTRACTTEXT =

tools.getLocalizedTextForString("pxRequestor.pyCaption","Contract");

// Get the list size, small or full, stored on the Work pyPortalPage

String strWorkListSize = SMALLLIST;

ClipboardPage pgDataPortal = tools.findPage("pyPortal");

if (pgDataPortal != null) {

ClipboardProperty cpPortalPages = pgDataPortal.getProperty("pyPortalPages");

for (int i = 1; i < cpPortalPages.size(); i++) {

ClipboardPage pgPortalPage = cpPortalPages.getPageValue(i);

if (pgPortalPage.getString("pyCaption").equalsIgnoreCase("Work")) {

strWorkListSize =

pgPortalPage.getString(".pyPageParams.pyWorkListSize");

break;

}

}

}

String strAnchor = (strWorkListSize.equals("full")) ? CONTRACTTEXT : EXPANDTEXT;

String srcUrl = userServer

+ "?pyActivity=Data-Gadget.ShowWorkView&ViewClass=Assign-

Worklist&ViewPurpose=&ViewOwner=ALL&pyAction=Refresh&showHeader=false&UserID="

+ userId + "&ViewHeader=false&glimpseMode=Scripts&workListSize=" +

strWorkListSize;

%>

In the above example, two strings were being localized: “Expand” and “Contract”. A local

string variable was defined for each of these (EXPANDTEXT, CONTRACTTEXT), and set

CONFIDENTIAL 75 Localization References in HTML Code

equal to the Rule-Obj-FieldValue instances for those values in the pyCaption grouping

(“Expand” “Contract”), using getLocalizedTextForString.

Note that at the top and bottom of this code, the symbols “<%” and “%>” are used. These

are the HTML references stating that the data enclosed between these symbols is Java

code; the “<” symbol means that this rule has been generated for JSP tags.

Example 2: Cached values using Java

This code includes caching. This HTML rule is also generated for JSP.

Code snippet from Rule-Obj-HTML: Code-Pega-List.SelectFolderItem

<%

tools.putSaveValue("CAPTION-expand",

tools.getLocalizedTextForString("pxRequestor.pyCaption","Expand"));

String footerQuery = listPage.getString(".pyExpandedQueryName");

if (footerQuery.length() > 0){

String footerCategory = listPage.getString(".pyExpandedQueryCategory");

String footerWindow = listPage.getString(".pyExpandedWindow");

// append a row containing link to a full blown query screen

tools.appendString("<tr><td align=center colspan=" + headerArray.length +">");

tools.appendString("<a href=\"javascript:executeList(");

tools.appendString("'" + footerQuery + "',");

tools.appendString("'" + footerCategory +"',");

// append parameters of the current list

String param = listPage.getString(".pyExpandedQueryParam");

tools.appendString("'&" +param + "',");

tools.appendString("10,10,80,80,");

tools.appendString("'" + footerWindow + "');");

String strExpand = tools.getSaveValue("CAPTION-expand");

tools.appendString("\">" + strExpand + "</a>");

tools.appendString("</td></tr>");

}

In this example, the getLocalizedTextForString reference is cached: the beginning of the

code uses putSaveValue. The local variable being used is “CAPTION-expand”; the

capital letters in the “grouping” allow the reference to be easily found in the code. Like the

first example, this code also points to the Expand Rule-Obj-FieldValue instance.


Example 3: Cached values using HTML

In addition to references in Java, references can be made directly in the HTML code.

This HTML rule is generated for HTML.

Code snippet from Rule-Obj-HTML: Code-Pega-List.Query_ProcessResForDisplay

<HTML>

<HEAD>

{JAVA}

// no assigments message

saveValueSet("MESSAGE-noAssignmentsFound",

tools.getLocalizedTextForString("pxRequestor.pyMessageLabel","NoAssignmentsFound"));

saveValueSet("CAPTION-of",

tools.getLocalizedTextForString("pxRequestor.pyCaption","Of"));

saveValueSet("CAPTION-expand",

tools.getLocalizedTextForString("pxRequestor.pyCaption","Expand"));

{/JAVA}

<table width="100%">

{when {%Integer.parseInt(saveValueGet("QueryResultsCount")) > 10 %}}

<tr>

<td style="width:100%;text-align:center">

<a href='javascript:showUserWorkList("{pxRequestor.pyUserIdentifier}")' >10

{$save(CAPTION-of)} {$save(QueryResultsCount)} - {$save(CAPTION-expand)}<a></td>

</tr>

{elsewhen {% Integer.parseInt(saveValueGet("QueryResultsCount")) > 0%}}

<tr>

<td style="width:100%;text-align:center">

<a href='javascript:showUserWorkList("{pxRequestor.pyUserIdentifier}")'

>{$save(QueryResultsCount)} {$save(CAPTION-of)} {$save(QueryResultsCount)} -

{$save(CAPTION-expand)}<a></td>

</tr>

{else}

<tr>

<td style="width:100%;text-align:center">{$save(MESSAGE-

noAssignmentsFound)}</td>

</tr>

In this example, the getLocalizedTextForString references are saved into a cache using

saveValueSet in a Java section at the top of the code. However, in the code itself, the

reference to the string uses $SAVE. This designation can be used when writing directly in

HTML, so the developer doesn’t have to drop into Java code (to use the

tools.getSaveValue method).

If the rule has been generated for JSP tags, the pega:save and pega:getSaved tags can

be used. (See the JSP Stream Support tech note for further details.)

For full details on using the getLocalizedTextForString Java method, please reference the

Process Commander Public Javadocs.

CONFIDENTIAL 77 Creating New Field Value Groups

Creating New Field Value Groups

As stated in the Field Values section of this document, there are a number of “grouping”

properties that are defined in Service Pack 5, including pyActionPrompt, pyButtonLabel,

pyCaption, etc. These are the values which must be used when creating new localization

Field Values for harnesses, sections, and other rules where the HTML code is

automatically generated.

However, if the customer wishes to create their own custom HTML rules, it is also possible

that they could create some additional “grouping” properties to reference in these rules.

Pegasystems recommends not creating too many, or the capability to find one particular

Field Value quickly will be lost. (Creating 100 groups for 100 Field Values will not aid a

customer to find a particular Field Value.)

There are three steps to creating and using a new Field Value group:

• create the new “grouping” property

• define Field Values on this property

• specify these Field Values in custom HTML

Create the Property

The first step in creating a new Field Value group is to create the grouping property. This

property should be defined on a class which is at the most general level possible in the

hierarchy, in order to allow the Field Values in this group to be used by the widest possible

number of classes (i.e., to promote reuse). Most of the grouping properties shipped with

Process Commander are defined on @baseclass; some are defined on Work-.

The property should be a Single Value property, of type Identifier.

78 CONFIDENTIAL Creating New Field Value Groups

Define Field Values

Once the new grouping property is created, define the appropriate Field Values on this

property. For example, the customer might create a new grouping property called

Products, and then define localization Field Values on that property.

In the above example, the Field Value Computer Monitor was defined on the new

grouping property Products.

Use in custom HTML

After the Field Values have been defined on the new grouping property, they can be

referenced in custom HTML rules. These references could be either a lookup reference,

or a getLocalizedTextForString reference.

lookup example

In an HTML rule which is generated for JSP, the pega:lookup syntax could be used:

<pega:lookup property=”pxRequestor.Products” value=”Computer Monitor”/>

getLocalizedTextForString example

This new Field Value reference could also be used with getLocalizedTextForString:

tools.putSaveValue("PRODUCTS-monitors",

tools.getLocalizedTextForString("pxRequestor.Products","Computer Monitor"));

CONFIDENTIAL 79 Localizing Properties

Localizing Properties

Properties can have different types in the PegaRULES system. Localizing requires

different processes based on the property type.

Number-Formatted Properties

The following property types use the default display mechanism:

• date

• time of day

• Date/Time

• integer

• number

• decimal

• double

Clicking the Demo button in the Set Locale tool displays all property types that will be

automatically changed by changing the Locale:

80 CONFIDENTIAL Localizing Properties

In the example above, although the current browser settings are set to en_US (Default

Locale), the Selected Locale has been changed to French (fr_FR).

Once the locale has been changed (either through the browser or by using the Set Locale

tool), all properties of the above types should automatically display data in the correct

format for the locale when either the default Rule-HTML-Property instance or no Rule-

HTML-Property instance is associated with the property (in the HTML Property field).

For example, a DateTime property with no HTML Property specified would display in the

default format, which maps to the MEDIUM format:

Jan 19, 2004 7:00:00 p.m.

If another format is desired, however, the following Rule-HTML-Property instances are

available:

DateTime-Full

DateTime-Full-i18n

DateTime-Long

DateTime-Long – i18n

DateTime-Medium

CONFIDENTIAL 81 Localizing Properties

DateTime-Medium – i18n

DateTime-Short

DateTime-Short – i18n

Examples of these Short, Medium, Long, and Full DateTime formats are displayed in the

demo screen (previous page).

for the default locale, but the Rule-HTML-Property instance will accept the specific locale

parameter and use that formatting for a different locale passed in as a parameter. If the

“base” (non-i18n) version of the Rule-HTML-Property instance is used, then both the

default locale values and the “specified” locale values would appear in the format of the

default locale.

Thus:

• When the system will only use locale information from the browser (the “default”

locale), the standard Rule-HTML-Property instance should be used.

• When there will be another locale specified in processing, but the default locale

should not be changed, the i18n version of the Rule-HTML-Property should be

used.

82 CONFIDENTIAL Localizing Properties

Text Properties

Properties may be defined so that a drop-down list of choices is displayed to the user for

setting a property value. When creating the property, the developer should choose a

Table Edit type on the Table Edit tab to populate this list:

NOTE: In Process Commander Version 4.1, an HTML Property called GetLocalizedValue

was created. This HTML Property is no longer used in Version 4.2.

the Short Description of the Field Value in the base RuleSet, the system will generate a

localized drop-down box by displaying the values from the Localized Label fields of the

localized Field Values.

Localizing an Application

Documents

Transcript of Localizing an Application