Post on 25-Nov-2014
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.
CONFIDENTIAL 61 Creating the Application
On both the Content and the Drill Down tabs, the labels are in Caption fields.
62 CONFIDENTIAL Creating the Application
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
CONFIDENTIAL 63 Creating the Application
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.
64 CONFIDENTIAL Creating the Application
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
66 CONFIDENTIAL Creating the Application
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.
CONFIDENTIAL 67 Creating the Application
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
74 CONFIDENTIAL Localization References in HTML Code
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.
76 CONFIDENTIAL Localization References in HTML Code
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.