Advanced UI Advanced UI Techniques Techniques
e‐Learning Course Transcript
Copyright 2008 Pegasystems Inc., Cambridge, MA All rights reserved. This document describes products and services of Pegasystems Inc. It may contain trade secrets and proprietary information. The document and product are protected by copyright and distributed under licenses restricting their use, copying distribution, or transmittal in any form without prior written authorization of Pegasystems Inc. This document is current as of the date of publication only. Changes in the document may be made from time to time at the discretion of Pegasystems. This document remains the property of Pegasystems and must be returned to it upon request. This document does not imply any commitment to offer or deliver the products or services described. This document may include references to Pegasystems product features that have not been licensed by your company. If you have questions about whether a particular capability is included in your installation, please consult your Pegasystems service consultant. For Pegasystems trademarks and registered trademarks, all rights reserved. Other brand or product names are trademarks of their respective holders. Although Pegasystems Inc. strives for accuracy in its publications, any publication may contain inaccuracies or typographical errors. This document or Help System could contain technical inaccuracies or typographical errors. Changes are periodically added to the information herein. Pegasystems Inc. may make improvements and/or changes in the information described herein at any time.
This document is the property of: Pegasystems Inc. 101 Main Street Cambridge, MA 02142‐1590 Phone: (617) 374‐9600 Fax: (617) 374‐9620 www.pega.com
Updated: April 9, 2008
Contents Maximizing Reuse of Harnesses and Sections .................................................................................... 1 Maintaini ng Guardr ail Compl iance wit h Harn esses and Section s ..................................................... 1 Utili zing the Acti on Form for Harnesses and Section s ....................................................................... 2 Utili zing Field Values with Harnesses and Section s ............................................................................ 2 Read/Write Access for Harnesses and Sections .................................................................................. 3 Referencin g HTML Pro perty Rules in Harnesses and Section s ......................................................... 4 Parameterizing Rule-HTML-Properties .................................................................................................. 5 Defining Custom Buttons ....................................................................................................................... 5 Repeating Elements for List Views ........................................................................................................ 6
Maximizing Reuse of Harnesses and Sections As with many rules in PRPC, there are multiple ways of maximizing reuse in harnesses, sections, and flow actions. The most obvious way of achieving optimum reuse is by placing the rule in the appropriate location within your class structure. By building HTML form rules to display common embedded content in the Work‐ part of the class structure, it can be re‐used across all work object types. However, the limitation is that you must fully qualify the path of the embedded property. By building the HTML form rule in the same class as the property, you inherently achieve reuse. You can use this rule to display any property of any type of this class. The benefits of doing this are that you… ■
Do not have to fully qualify the references to the properties
■
Can display data elements without the need for detailed work object property structures
■
Are allowing for quick development at the start of a project
■
Achieve a consistent display of data across the application
For instance, if a section rule has been defined in the Work‐ part of our class structure and displays address details, you must fully qualify the path to each individual property relative to the work object. Although this functionality will work, it can only be used to display an address when the address is part of a page property named Address, and the section rule that this property is defined on has limited reusability. Looking at the same section rule defined within the Data‐Address‐Postal class, you only need to put references relative to the class you are currently in, which allows for the use of this form wherever an address is to be displayed. Therefore, a work object can display two addresses, which relate to two different address properties on our work object, but can use the same section rule to display both.
Maintaining Guardrail Compliance with Harnesses and Sections To showcase a smooth, feature rich UI coupled with a pre‐flight report that shows everything has been auto‐generated, use JSP tags defined directly into
2
Advanced UI Techniques
Rule‐HTML‐Section cells to include Rule‐Obj‐HTML, Rule‐HTML‐Fragment, and Rule‐Obj‐ListView rules. Here we are using a section to display an individual element within a page group property. A Rule‐HTML‐Fragment has been defined that takes the index to display from a property on the work object called Address Interest. This sets the subscript of the desired page. Historically, this would have been defined directly in a custom built Rule‐HTML‐ Section. However, to maintain guardrail compliance, the JSP is within the HTML fragment, and the fragment is within a section layout
Utilizing the Action Form for Harnesses and Sections Traditionally, a button or icon with a custom activity was used to invoke and follow a new process from the middle of an existing process. This is fine for some situations but does not work well when the activity in question creates a new work object and displays an assignment on that new work object. The CPM Framework takes advantage of a minimal change to the Action form on the Perform Harness to solve this requirement while still being guardrail compliant. For example, we are interacting with a customer and attempting to search for the customer record. When the customer record is not found, we are required to register the customer. Interacting with the customer and creating a new customer are two separate processes. By changing the target of the Action form, you can direct the submission of the form to submit the entire form rather than just the Action form. This can be achieved by embedding a fragment with a small piece of JavaScript that modifies the target attribute of the form.
Utilizing Field Values with Harnesses and Sections Field values within harnesses and sections allow for complete reuse of process flows and their components. The out of the box Rule‐Obj‐HTML rule ActionDropDown is used to define the contents of the dropdown on the Perform harnesses within the action form.
Advanced UI Techniques
3
Minor modifications will allow for the use of dynamic field values to work and to maximize the full reuse capability of flow actions. The Work‐.ActionDropDown rule uses a Public API method getLocalizedTextForString to return the localized value of field value instances. To allow this rule to use dynamic field values, the ActionDropDown HTML must be modified to use the Lookup JSP tag as opposed to a Public API method call. The out of the box ActionDropDown rule is a final rule. However, this does not mean that it cannot be customized within your application without breaking any guardrails. Saving the rule with an Applies To class other than a class that inherits from Work‐ allows you to create your own version of this rule. This means that the rule is found by pattern inheritance first before any directed inheritance finds the Work‐ rule.
Read/Write Access for Harnesses and Sections It is sometimes required within a process to display previously captured data in a read‐only format in a confirmation step. The same section could, and probably should, be used for both the capture and the confirmation. To achieve this… ■
■
Define a privilege such as Read‐Only that you never assign to a user role Add this privilege as the “Update Privilege” attribute when you embed the section
This ensures that whenever the parent section is displayed the embedded section is always shown as Read‐Only. PRPC 5.3 has some very interesting implementation of the Perform Harness, taking screen flows in particular to a new level. See Work‐.TabbedScreenFlow and Work‐.TreeNavigation for more information regarding advanced harness uses within screen flows.
4
Advanced UI Techniques
Referencing HTML Property Rules in Harnesses and Sections The use of Rule‐HTML‐Property rules allows for the consistent display of properties wherever they are referenced, for example in HTML forms or Correspondence templates. The following rule types have forms that allow Rule‐HTML‐Property rules to be referenced directly: ■
Rule‐Obj‐Property, with the HTML input in the presentation part of the form
■
Rule‐HTML‐Section, where you can override the default presentation for a particular property
■
Rule‐Obj‐FlowAction, where again you are allowed to override the default presentation for a particular property
■
Rule‐Obj‐ListView
■
Rule‐Obj‐SummaryView
All other HTML rules allow for the manual inclusion of Rule‐HTML‐Property references via the Reference JSP tags or HTML directives (which is deprecated). When defining custom Rule‐HTML‐Property rules, it is important to include two out of the box rules: ■
Validation Messages: to ensure the full functionality of validation display
■
Client Side Validation: to ensure client side events handling is maintained
If the Validation Messages is not used, when that property is validated, for example in a flow action post activity, the error message regarding that validation is seen in an errors element at the top of the HTML. While this serves a purpose and displays messages back to the user, it is not the most user‐ friendly way of alerting the user. By including the messages Rule‐HTML‐Property rule, when validating property values for flow action validate rules or post activities, the user sees the out of the box red cross and the desired validation message upon hover over. The more complex the Rule‐HTML‐Property becomes, the longer the forms that references the related property will take to load. This becomes even more important when considering reporting type rules such as list view and summary view rules.
Advanced UI Techniques
5
Parameterizing Rule‐HTML‐Properties Parameterization of Rule‐HTML‐Property rules allows you to build one rule to fulfill a requirement in multiple areas, which results in lower development and maintenance costs. An ideal use of parameterization is with dynamic selects. An out of the box example exists that allows you to quickly define dynamic select presentations. This has a large number of parameters enabling you to rapidly deploy dynamic select functionality throughout the application. Parameters can only be passed directly using the out of the box form with the following rule types: ■
Rule‐Obj‐Property (from v5.3)
■
Rule‐HTML‐Section
■
Rule‐Obj‐FlowAction
Parameters can be passed to Rule‐HTML ‐Property rules within non‐auto generated Stream rules using the Pega Param JSP tags. Early versions of PRPC (pre 5.3) did not allow parameters to be passed to a Rule‐ HTML‐Property directly from the Property definition. This limitation still exists in version 5.3 when referenced from List View and Summary View rules.
Defining Custom Buttons Custom Radio Buttons List Views can be used to format results sets. Inherently, List View rules allow for the single and multiple selections of results for further processing. However, there are situations where this functionality cannot be used, such as displaying Page‐List elements embedded within another object. In PRPC 5.3 there is a comprehensive set of radio button definitions that allow you to select results from a list view. If you have version 5.3 or later, investigate the out of the box offering before using the solution detailed above.
Custom Buttons Using standard Rule‐HTML‐Section functionality, it is possible to include a button on a screen that calls an activity to perform an action and ultimately repaint the screen. However, there are situations where it is more practical to include the button within a Rule‐HTML‐Property definition so that each time the property is displayed a defined activity can also be invoked.
6
Advanced UI Techniques
For example, for each display where you intend to capture an address, a button has been included to call an activity to perform an address lookup. This button has been defined within the Rule‐HTML ‐Property. Within the Address Lookup Rule‐HTML‐Property rule, there is the defined logic and a display of the entered value, as well as the simple script to invoke an activity. Our activity has set simple values on the page and repaints the screen. When the Address Lookup button is clicked, the activity is invoked, properties are populated, and the screen is redisplayed.
Repeating Elements for List Views List view rules are a very powerful tool for formatting repeating elements of data. Traditionally, they are used to define the criteria to retrieve, sort, and display data, such as worklists, that display on our default portal. List views provide the ability to sort repeating elements without the need to build complex custom JavaScript. This functionality can also be used to format repeating rows of data. Within the CPM framework, list views are often used to format repeating elements of data returned from external service calls. For example, when searching for a contact, an activity is processed that looks for customers on an external database and retrieves the results set prior to the screen being rendered. You can define an activity within the Report Source section of the form. Essentially, your activity could ensure the content you wish to display is present on the clipboard. If not, it creates a blank page with zero results enabling the list view to display without error. This list view is then embedded within a normal section using a Pega ListView JSP tag that allows you to stay guardrail compliant.
Note: When defining list views to purely format data, you must always define one element in the Get These Fields section of the form. This need not relate to anything you wish to display. Leaving this element blank will not allow the rule to save, and adding in a property that is not exposed will cause guardrail compliance alerts to be generated. A simple way around this is to define pyLabel as the field in the Get These Fields section within each of your custom list view rules.
Advanced UI Techniques
7
Within the list view definition, you can then define what rows are selectable. ■
Single – each result is displayed with a radio button.
■
Multiple – each result is displayed with a checkbox.
Depending on the “Copy To” method chosen, the selected rows are mapped to the clipboard in a number of different ways. This is particularly useful in Search and Select functionality.