Section, Harness, and Flow Action forms -
Adding an Icon/Image control

About Harnesses

You can add an Icon/Image control (pxIcon) to a cell in a layout or a harness.

Icon/Image controls display an icon or image and can invoke an action when the user clicks or hovers the mouse pointer over the icon or image. You can configure the pxIconcontrol as desired, specifying an icon, image, external URL, property, or icon class as the source of the icon/image. You can also configure actions that execute when the user clicks or hovers the mouse pointer over the icon/image, as well as conditions that disable the icon/image.

PRPC ships with a number of pre-configured variations of the pxIcon control, such as pxIconAddItem. Each of these controls is pre-configured with an icon, tooltip, and action. See Standard icon controls below for a complete list. These rules eliminate the need to manually configure the values in the pxIcon Parameters dialog.

Beginning with 7.1, add an image using the Icon/Image control (pxIcon).

TipThe UI Gallery contains a working sample. To view and interact with the sample, select > User Interface > UI Gallery. In the Components area, select Icon.

Adding an Icon/image control

  1. Click the down-arrow Arrow at the right end of the Basic control group Basics and select Icon/Image.
  2. Drag the control into the layout and release the mouse button to drop the control.

    If you are using a cell-based layout and you drag the control into a cell that is not empty, then the dropped control replaces the current contents of the cell.
  3. Click the magnifying glass Magnifying glass to display the Properties panel and complete the following tabs:

General tab

Field

Description

Icon Source Select one of the following as the source for the icon/image:
  • Standard Icon: select from a list of icons pre-configured with a default icon, tooltip, and action.
  • Image
  • External URL
  • Property
  • Icon Class
Standard icon

Appears if you selected Standard Icon as the Icon Source.

Press the down arrow and select the standard icon that you want to display. Standard icons are pre-configured with an icon and a tooltip. Variants of the pxIcon control are also configured with actions; see Standard icon controls below for details.

External URL

Appears if you selected External URL as the Icon Source.

Type the URL that you want to display as the icon/image source.

Image

Appears if you selected Image as the Icon Source.

To search through binary file rules containing images, click the magnifying glass icon to start the Image Catalog tool (a pop-up version of the Image Library landing page).

If the image is not already loaded to a binary file rule, create a binary file rule and upload the image to the binary file rule.

Image size

Appears if you selected Image, External URL, or Property as the Icon Source. For images, this field displays only if the selected image is not a sprite (Treat Image As A Sprite is not selected on the Main tab of the image binary file.)

Select the image size:

  • Auto: automatically sizes the image by allowing the layout to determine the width of the control area. Default.
  • Custom: select to specify the width and height of the image in pixels in the Image dimension field.
Position

Appears if you selected Image as the Icon Source and the selected image is a sprite. (Treat Image As A Sprite is selected on the Main tab of the image binary file.)

Sprites typically contain columns of images, representing each icon in normal, hover, and disabled states. Press the down arrow to select the column number of the image that you want to display.

Class

Appears if you selected Icon Class as the Icon Source.

Specify the class of the icon.

NoteTo learn how to upload your own icon fonts into a Pega application, see the PDN video tutorial Implementing icons fonts in Pega applications.

Property

Appears if you selected Property as the Icon Source.

Press the down arrow to select the property that you want to use as the source of the image/icon. The property can be an internal binary file (Rule-File-Binary) or an external URL.

Tooltip

Specify a tooltip to display when the user hovers the mouse pointer over the image or icon. You can press the down arrow to select a property value or type the text that you want to display as the tooltip.

TipAs a best practice, start the sentence with verb either in the imperative ("Enter price of item here") or as an infinitive ("To cancel the order, click here").

Privilege

Press the down arrow to select a privilege rule that controls the availability of this control at runtime.

If there is a privilege and a when rule (see Disabled field), both rules must evaluate to true for the icon/image to be available to the user.

Disabled

Select to disable the text input:

  • Never: never disabled
  • Always: always disabled
  • Condition (expression): the text input is disabled under the specified condition. In the field that displays, select a condition or click to open the Condition Builder. You can define a simple expression based on the comparison of a pair of constants, properties, or both, combined by Boolean operators, such as .Color="Red". You can combine the expression with a when condition rule or another expression using the && and || operators.
  • Condition (when): the text input is disabled under the specified condition. In the field that displays, select a when rule. Click to create a new when condition or review an existing when condition.

Standard icons

Each of the following is configured with a default icon, tooltip, and action, eliminating the need to configure these values.

  • pxIconAddItem
  • pxIconAddNewWork
  • pxIconAttachments
  • pxIconCancel
  • pxIconContents
  • pxIconDeleteItem
  • pxIconEnableActionSection
  • pxIconExpandCollapse
  • pxpxIconExplore
  • pxIconFinishAssignment
  • pxIconGetNextWork
  • pxIconHistory
  • pxIconLocalAction
  • pxIconPrint
  • pxIconReopenWorkItem
  • pxIconReview
  • pxIconSave
  • pxIconShowFlowLocation
  • pxIconShowHarness
  • pxIconIconShowReopenScreen
  • pxIconSpellChecker
  • pxIconUpdate

Configure the control

  1. Click beside the Control field on the Cell Properties panel to open the Parameters dialog.
  2. In the Options area, configure the icon/image as desired: 
  3. Field

    Description

    Icon Source Select one of the following as the source for the icon/image:
    • Standard Icon: select from a list of icons pre-configured with an icon and a tooltip. Add events and actions as desired in the Behaviors area.
    • Image
    • External URL
    • Property
    • Icon Class
    Type

    Appears if you selected Standard Icon as the Icon Source.

    Press the down arrow and select the standard icon that you want to display. Standard icons are pre-configured with an icon and a tooltip. Variants of the pxIcon control are also configured with actions; see Standard icon controls below for details.

    External URL

    Appears if you selected External URL as the Icon Source.

    Type the URL that you want to display as the icon/image source.

    Image

    Appears if you selected Image as the Icon Source.

    To search through binary file rules containing images, click the magnifying glass icon to start the Image Catalog tool (a pop-up version of the Image Library landing page).

    If the image is not already loaded to a binary file rule, create a binary file rule and upload the image to the binary file rule.

    Image size

    Appears if you selected Image, External URL, or Property as the Icon Source. For images, this field displays only if the selected image is not a sprite (Treat Image As A Sprite is not selected on the Main tab of the image binary file.)

    Select the image size:

    • Auto: automatically sizes the image by allowing the layout to determine the width of the control area. Default.
    • Custom: select to specify the width and height of the image in pixels in the Image dimension field.
    Position

    Appears if you selected Image as the Icon Source and the selected image is a sprite. (Treat Image As A Sprite is selected on the Main tab of the image binary file.)

    Sprites typically contain columns of images, representing each icon in normal, hover, and disabled states. Press the down arrow to select the column number of the image that you want to display.

    Class

    Appears if you selected Icon Class as the Icon Source.

    Specify the class of the icon.

    Property

    Appears if you selected Property as the Icon Source.

    Press the down arrow to select the property that you want to use as the source of the image/icon. The property can be an internal binary file (Rule-File-Binary) or an external URL.

    Tooltip

    Specify a tooltip to display when the user hovers the mouse pointer over the image or icon. You can press the down arrow to select a property value or type the text that you want to display as the tooltip.

    TipAs a best practice, start the sentence with a verb, either in the imperative ("Enter price of item here") or as an infinitive ("To cancel the order, click here").

    Disabled

    Select Yes if you want to apply a when condition that tests whether the user can use the control. If selected, the following options appear:

    Disabled Condition SmartPrompt Select one of the following:
    • The When Name key part of a when condition rule. Click(magnifying glass) to review or create the rule.
    • Expression based on the comparison of a pair of constants, properties, or both, combined by Boolean operators, such as .Color="Red". You can combine the expression with a when condition rule or another expression using the && and || operators.

    As a best practice, use the Condition Builder to edit this field. Click ( ) to open the tool. See Using the Condition Builder to configure dynamic UI actions.

    Run On Client

    Appears only if the Disabled Condition field contains an expression that can be evaluated on the client. Complex expressions and When rules are not eligible.

    Select to cause evaluation and execution of the condition each time the value of a property stated in the condition changes. 

    If unselected, the expression is evaluated and the condition executed when the form is initially presented and whenever the form is refreshed.

    Privilege

    Press the down arrow to select a privilege rule that controls the availability of this control at runtime.

    If there is a privilege and a when rule (see Disabled field), both rules must evaluate to true for the icon/image to be available to the user.

  4. In the Behaviors area, configure events and actions as desired. See Control Form — Completing the Control tab for descriptions of the available parameters and how to define behaviors.
  5. Click OK.

Complete the Cell Properties panel — General tab

Complete the General tab.

If the panel is pinned (Pinned), the wireframe presentation on the rule form changes immediately to reflect of your inputs. If the panel is not pinned (not pinned), click Apply to apply your inputs.

Field

Description

Visible Select to determine when the icon appears. (If this setting is not applicable, the cell contents are blank.)
  • Choose Always to have the icon appear or be hidden based on the visibility of the enclosing section or flow action when the form is first presented or is refreshed. This condition is checked only once.
  • Choose Other Condition to make the visibility depend on a when condition rule, a Boolean expression evaluated only once, or a test evaluated repeatedly upon JavaScript events.
Condition SmartPrompt If you selected Other Condition for the Visible field, complete this field.
  • The When Name key part of a when condition rule. Click(magnifying glass) to review or create the rule.
  • Simple expression based on the comparison of a pair of constants, properties, or both, combined by Boolean operators, such as .Color="Red". You can combine the expression with a when condition rule or another expression using the && and || operators.

As a best practice, use the Condition Builder to edit this field. Click ( ) to open the tool. See Using the Condition Builder to configure dynamic UI actions.

 

  • When condition rule evaluated once — Enter the When Name key part of a when condition rule that determines the visibility of this image at runtime. The system uses the Applies To key part of the current rule in rule resolution to locate the when condition rule. Click(magnifying glass) to review or create the when condition rule.
  • Expression evaluated once — Enter an expression that returns true or false. This expression can involve multiple properties, function calls, and other syntax as supported by the <pega:when > JSP tag.
  • Simple expression evaluated upon JavaScript events — To dynamically control the visibility of this image with a JavaScript event, enter a simple comparison involving a target property and select the Run on Client? check box. The result at runtime determines whether the content of this cell appears in read-only mode or in the mode of the enclosing layout.
    For example, enter .Color =="Blue" in this field to make this image visible when the property Color has the value Blue, and invisible otherwise. Depending on the state of the Run on Client? check box, the comparison executes only once as the form is initially displayed, or dynamically. See Implementing dynamic form actions and the Client Event Editor.
Run on Client?

Appears if the Condition field contains a simple comparison.

Select to cause evaluation and execution of the condition each time the value of a property stated in the condition changes. If unselected, the expression is evaluated and the condition executed when the form is initially presented and whenever the form is refreshed.

Complete the Cell properties panel — Advanced tab

Complete the Advanced tab to control the presentation and visibility of the field.

Field

Description

Include a label

Select if you want to add a label to the control. Enter text in the input field.

Alternatively, use SmartPrompt SmartPrompt to select a field value rule if you plan to localize the text. Enter no more than 64 characters. A field value rule with pyButtonLabel as the second key part and this text as the final key part is needed for each locale. When practical, choose a caption already included in a language pack, to simplify later localization. See About the Localization wizard.

Label format Select a format for the label.
Cell read-write classes SmartPromptOptional. By default, when the user form or flow action form appears in read-only mode, the CSS style named DataValueRead or DataValueRead RV2 applies. If this cell is not controlled by Smart Layout restrictions, you can enter another style name or select from those listed.

The SmartPrompt list shows all styles that start with the word Data. You are not limited to these styles.

Click(magnifying glass) to review the text file rule that defines the style sheet. Your application can override and extend this style sheet in an application text file rule.

Cell read-only classes

SmartPromptOptional. By default, when the user form or flow action form appears in read-only mode, the CSS style named DataValueRead or DataValueRead RV2 applies. If this cell is not controlled by Smart Layout restrictions, you can enter another style name or select from those listed.

The SmartPrompt list shows all styles that start with the word Data. You are not limited to these styles.

Click(magnifying glass) to review the text file rule that defines the style sheet. Your application can override and extend this style sheet in an application text file rule.

Cell inline style Enter CSS code for an inline style for a cells in the column. For guided assistance in composing a style definition, click the magnifying glass icon (Magnifying glass) to open the Style Editor. You can select from predefined lists or type a style definition directly, and preview the results.
Show When Active This check box appears when control is placed in the repeating area of a Grid, Tree Grid, or Tree layout. If checked, the icon displays in the row only when the user selects it.

Standard icon controls

PRPC provides standard variations of pxIcon. Each is preconfigured with an icon, tooltip, and action. As a best practice, use these standard rules to ensure correct appearance and behavior. In the Cell Properties panel, use AutoComplete () in the Control field to select a rule.

If the action is not included in the list, keep pxIcon and use the Parameters dialog to configure the control.

This table below describes the icon name, the icon, the action invoked when clicked, and the standard icon control, which contains the control's parameters.

Icon Name

Icon and Action

Control Rule

Add Item

— Adds (above or below) a row to a grid, tree, or tree grid layout

pxIconAddItem
Add New Work

help icon— Adds a new work item using the primary page data. Saves the new work item on the deferred list.

pxIconAddNewWork
Attachments

— Presents a list of work item attachments, so users can view or add attachments. This icon appears only for users who hold the Work-.AccessAuditTrail privilege.

pxIconAttachments
Blank

help icon — No action is associated with it.

pxIcon
Cancel

— Closes the current form without applying any changes.

pxIconCancel
Contents

— For a cover work item, changes the form to allow users to view and navigate among the covered work items. You can override a standard list view rule to control details of this display.

pxIconContents
Delete Item

— Removes a row in a grid, tree, or tree grid layout.

pxIconDeleteItem
Enable Action Section

help icon — Presents the user form in review-only mode; inputs allowed in the action section only.

pxEnableActionSection
Expand/Collapse

— Redraw the form with all areas fully expanded.

pxIconExpandCollapse
Explore

— For a folder work item, changes the form to allow users to view and navigate among the associated work items.

pxIconExplore
Finish Assignment

help icon — Submits changes and marks this assignment as complete.

pxIconFinishAssigment
Get Next Work

help icon — Cancels any unsubmitted changes and finds the most important assignment to work on next.

pxIconGetNextWork
History

— Displays the work item history, for users who hold the Work-.AccessAuditTrail privilege.

pxIconHistory
Print

— Starts browser-based printing, which prints the current user form as displayed. This printout may not include desired fields and may use colors, fonts, and labels that are not desired in hard copy prints.

pxIconPrint
Reopen Work Item

— Reopens a resolved work item, for users who hold the Work-.Reopen privilege. Runs the standard activity Work-.Reopen or your application override.

pxIconReopenWorkItem
Review

help icon — Presents the user form in review-only mode, allowing no updates.

pxIconReview
Save

— Saves the work item with Submit.

pxIconSave
Show Flow Location

— Known as the Where-am-I? icon marks the location of the current assignment with an arrow. This icon appears only to users who hold the Perform privilege.

TipIf the harness is a New harness — one supporting the entry of new work items — do not include the Show Flow Location icon in most cases. A flow execution doesn't start until users submit a user form. If you do include this icon in a New harness, use a when condition rule to disable the icon at runtime unless a non-blank work item ID exists.

pxIconShowFlowLocation
Show Reopen Screen

— Shows the form in review mode but allows users to reopen a resolved work item. Available to users who hold the Work-.Reopen privilege. Runs the standard activity Work-.Reopen or your application override.

pxIconShowReopenScreen
Spell Checker

Spellcheck — Enables spell-checking. See How to enable spellchecking in user forms.

pxIconSpellChecker
Update

— Redraws the form in update mode. Appears only for users who hold the Work-.Update privilege. Update mode allows changes to values that appear in sections other than the TAKE ACTION section.

NoteThis capability is not desirable in all applications, as it allows users to overwrite values entered previously, perhaps by other users.

NoteThe  Apply   button sends changed user inputs to the server, but does not commit these changes. The user must select and complete a flow action to save the changes. See Understanding transactions in flow executions.

pxIconUpdate

Copying, deleting, duplicating, or moving an icon

TipUse these Windows operations to speed development:

As of V6.2, the Icon control uses the auto-generated control pxIcon. The icon and its behavior are governed by the settings in the rule form's Control tab. The Parameters tab is not available and the HTML cannot be edited. As a best practice, do not modify a copy of the rule while designing a section, flow action, or harness. Instead, use the Parameters dialog available in the control's Cell Properties panel. See Control rule — Completing the Control tab.

Use the pxIcon control in new development. The V5 Icon control remains supported in V6.X. See About the V5 Icon control.

Tips

TipUse these Windows operations to speed development:

Up About Flow Actions

Up About Harnesses

Up About Sections