Atlas — Supported user interface features for mobile applications

Build applications for use on mobile devices, including tablets, phones, and portable media players, using the Pega-Mobile RuleSet. Many of the user interface features available in an application built to run through a web browser are also supported in applications built for use on mobile devices. For features not yet optimized for use on mobile devices, create specialized mobile versions of rules, and save them into a RuleSet with the same name and version, but with a _mobile suffix. For more information, see PDN article How to create a specialized RuleSet for mobile devices.

Additional features supported in a mobile application are detailed in the sections below.

Configuring Mobile Features

The Pega-MobileGallery RuleSet is similar to other PRPC galleries that showcase application features and configurations. This gallery displays working examples of Pega Mobile's runtime and design time capabilities. See PDN article View Pega Mobile features and configuration in the Mobile Gallery.

A clipboard view is also available, which is similar to the Designer Studio clipboard tool. The mobile clipboard lets you view property values, rules, and more in your application. Access the clipboard while using the Apple Safari or Google Chrome emulator on your desktop. See PDN article Inspect your Pega Mobile application with the Mobile Clipboard tool.

Pega Mobile 3.3 introduced the Mobile Mashup and Mobile SnapStart features, which allow for the creation of URLs that can embed Pega Mobile functionality inside third-party mobile applications. See PDN article Pega Mobile Mashup and Pega Mobile SnapStart.

Additionally, you can customize the appearance of Pega Mobile using CSS. See PDN article Configuring the color scheme of your Pega Mobile application.

Harnesses and Sections

If your application runs on mobile devices and on desktop browsers, you can create sections and harnesses that contain the features supported by the Pega-Mobile RuleSet without affecting the browser copy of the rules. To learn about creating and referencing harnesses and sections for mobile devices, consult the PDN.

You can use circumstancing on a section rule to create a mobile-compliant version of the section. Use Save As to save the section rule, and enter the property pyPortal.pyDesktopSubType and value Mobile. On the Pages & Classes tab, add the pyPortal page and class Data-Portal. You can ignore the performance warning message.

You can also circumstance your entire UI experience based on the device type. For the circumstance, enter property pxRequestor.pxDeviceType and value phone or tablet. When you log in using this portal, the application determines the User Agent, and displays the portal, sections, harnesses, and flow actions with a user interface for the specified device type. You can circumstance individual harness and section rules in the same manner.

Specifically, the RequestorInitialize activity opens the portal as specified and initializes the pyPortal page. The activity populates pxDeviceType with the result of the pyGetDeviceType decision tree. You can save pyGetDeviceTypeinto your application RuleSet and override the conditions that determine the device type. However, do not remove existing entries in the pyGetDeviceType rule. Instead, create your entries on top of entries in the table. As delivered to Pega-Desktop, pyGetDeviceType uses the pyGetUserAgent function rule to determine the device type.

Dynamic UI

Refresh this Section actions are supported.
Visible When is supported for sections and layouts within a section.
Visible When is supported on cells with Always and Other Conditions. However, note that unlike desktop applications, Smart Layouts in mobile applications show or hide the label based on the Visible When setting of the field; the Visible When on the label is ignored.
Run on Client is not supported.
Refresh When conditions are not supported.
Privileges for viewing and updating sections are honored on sections included in flow actions, harnesses, and other sections. The View Privilege and Update Privilege fields on Section Includes allow you to restrict user’s ability to see and edit the section. As Visible When can also be set, the most restrictive condition is implemented, and a child can only be more restrictive than a parent. For example, if you have a View Privilege for a section, and the section has a Visible When that is false, you cannot see the section. Further, if you do not have an Update Privilege, and a cell property Edit Options is set to Editable, you cannot edit the property.

Display Options

When the Pega-Mobile RuleSet is present for your application, harnesses have an additional section, Mobile, on the Display Options tab. The Supplemental Toolbar Navigation Rule field lets you specify a navigation rule that supplements the contents of the toolbar display. See Harness Form — Completing the Display Options tab.

Confirm Harness Name

If you save your Confirm harness to a different name as you create your mobile application, be sure to update the Harness field under the Action tab on flow actions to reflect the new harness name.

Harness Titles

Add titles to the harness using the header cells in a container. In the Cell Property Value field, you can specify a property reference or enter a text string for the title. Titles entered in the Container property panel are unsupported in mobile applications.

Layouts

The following layouts are supported in mobile applications.

Single and Double Smart Layouts are no longer available for use starting in Pega 7.1.

Free Form Layouts

Multi-column, multi-row Free Form layouts are supported with all mobile controls.

Dynamic Layouts

Dynamic layouts can be created using the form in the Mobile UI "Layouts" gallery. Using a dynamic layout will automatically adjust items on a mobile screen to best fit its specific size.

Repeating Grids

Repeating grids are supported with some considerations.

Edit Mode	Can Add *	Can Edit	Select on single tap	Can delete using long tap menu **	Edit method	Supported in main content panel	Supported in overlay	ShowDetails Checkbox
Read Only					N/A	X	X	Supply a flow action
Read/Write			X	X	N/A	X
Modal Dialog	X	X	X	X	Modal	X
Expand Pane	X	X	X	X	Main content panel via slide gesture	X
Embedded Pane	X	X	X	X	Main content panel via slide gesture	X
Inline			X	X		X

* if Add button is present in design time.

** if Delete button is present in design time.

Note that when an end user selects an item on a Repeating Grid, pySelected is set to "true' so that the selected item can be used as part of additional processing.

On the General tab, in the Edit Mode field, Read Only, Modal Dialog, Embedded Pane, and Expand Pane are fully supported. On a mobile device:
- Modal Dialoglaunches in the main content panel.
- Embedded Pane and Expand Pane slide over to fill the content panel.
For row selection, the long tap is required if the grid has one of the supported modes. If the mode is Read/Write, use a single tap for selection.
The user does a long tap to select the row when the grid has an edit mode that allows edits.
Only page list and page group properties are supported.
In the Grid Repeat Layout form, only the Title field is supported.
On a cell property within a repeating grid, only the Width field is supported.
The Delete and Add buttons only appear in the UI if they were configured at design time.

Tabbed layouts

Tabbed layouts are supported using a carousel effect, identified by the 3 dots at the bottom of the screen. Switch between tabs using a swiping motion.The tabbed layout must be the only layout in the section. Do not add other layouts.

Controls

Configure controls for your mobile application carefully. Remember that features of controls may be configured directly on the control rule, on the cell property panel in the section, or on a property. If you configure the control rule directly, you affect all instances of the control. If you configure the control on the cell property, you affect only this instance of the control.

As a best practice, ensure that all cells have a control in the cell property panel. If you configure the property to have a control, check to make certain the control is present when you use the property in a cell. If the Control field of the cell property is blank at run-time, the application looks to the property to determine the control configuration.

The decision table pzMobileControlMapping maps commonly used controls to mobile versions of those controls in order to facilitate the operation of an existing PRPC desktop version of your application. Map your custom controls in pyCustomMobileControlMapping.

In the Basics section of rules for controls in a mobile application, the Value field Value of associated property is supported, if present. Tooltips are not supported for any controls in a mobile application.

Following are some of the more commonly used controls.

pxCheckbox	Both Editable and Read-Only are supported. Format: Type — `True/False` is supported.
pxCurrency	Formats a number as a currency using the default locale. Options: Placeholder is supported. Format: Decimal Places is supported. Scale Negative Format is supported. Symbol — `Constant` and `None` are supported. Use Constant with value $ to display the dollar symbol.
pxDateTime	The TimeOfDay property type is not currently supported in a mobile application. See Adding a Calendar control. When adding a Date time text input control to a layout, the native browser date and time pickers are enabled by checking the Browser native support on mobile check box. All other configuration parameters on the control are currently unsupported.
DynamicSelect	Supports the Dynamic Select control. On Blur and OnChange events are supported.
PromptSelect	Presents a drop-down list of values determined by the Table Type areas of the General tab of a property rule. On Blur and OnChange events are supported.
pxButton	Format - `Standard`, `Simple`, and `Strong` styles are supported. If you select `Other`, you can also enter a custom CSS style or one of the following out-of-the-box styles: `normal`, `round`, `action`, `decline,confirm`, `back`, `forward`. See PDN article Customize buttons and links in a Pega Mobile application. Label - Enter text or a field value with brief text to appear on the button. The supported subset of Behaviors and Actions are described in the table below. Note that the Display action Refresh Section is supported only with Target`This Section`.
pxLink	Format - `Standard`, `Simple`, and `Strong` styles are supported. If you select `Other`, you can enter a custom CSS style. See PDN articleCustomize buttons and links in a Pega Mobile application. Label - Enter text or a field value with brief text to appear on the link. The supported subset of Behaviors and Actions are described in the table below. Note that the Display action Refresh Section is supported only with Target`This Section`.
pxTextArea	Presents the property as an HTML text area, which provides multi-line input or display. The Text Area control uses this rule. To place the control in a section or harness, drag and drop the text area icon () from the Basics control group onto a layout cell. See Adding a Text Area control.
pxTextInput	Presents the property as an HTML text box in edit mode. Spell checking is enabled by default. The Text Input control uses this rule. To place the control in a section or harness, drag and drop the text input icon () from the Basics control group onto a layout cell. See Adding a Text Input control.
pxAutoComplete	Can be set on a cell or property. Supported fields include Display Fields, Maximum Results, Minimum Search Characters, and Only match the start of string. Can be read only or editable.
pxSignatureCapture	Used to capture a user signature on either a desktop or a mobile application. This function is typically performed on a mobile device though a touch interaction, but this can also be done on a desktop app using a mouse. Once captured, the signature is added to the work item as an image attachment. To place the control in a section or harness, drag and drop the Signature Capture icon () from the Advanced control group onto a layout cell. See Adding a Signature Capture control.
pxAddressMap	Used to map addresses in Google Maps from within either a desktop or a mobile application. To place the control in a section or harness, drag and drop the Address Map icon () from the Advanced control group onto a layout cell. See Adding an Address Map control.

The mobile versions of each control are HTML-sourced to support their use on mobile devices. Do not edit these versions.

As you create your application, do not use the mobile version of a control. The decision table pzMobileControlMapping handles the mapping of standard PRPC controls to mobile versions. The following table lists the mobile versions of supported controls. Map your custom controls in pyCustomMobileControlMapping.

Mobile control	Description
pxDateTimeMobile	Values mapped to pxDatetimeMobile appear as a calendar picker in the mobile portal. The supported DateTime format is dd/mmm/yyyy.
pxTextAreaMobile	Values mapped to pxTextAreaMobile appear as a text area in the mobile portal. Dynamically adjust cell size according to the cell contents by clicking Size to Content in the Specifiy Height section of the Parameters window for the control. Click Auto to display the contents of the cell in a fixed-height scrollable field.
pxCheckboxMobile	Values mapped to pxCheckboxMobile appear as a check box in the mobile portal.
pxButtonMobile	The controls pxButton and pxLink are mapped to pxButtonMobile.
pxCurrencyMobile	pxCurrency is mapped to a mobile version of the control.
pxRadioButtonMobile	The RadioButtons control is mapped to pxRadioButtonMobile. On Click and On Change events are supported. Read Only displays the button value, not the label. Radio buttons appear horizontally on your mobile device. Due to the narrow display width available on phones, configure only up to two radio buttons.
pxNumberFieldMobile	Number controls other than currency should be mapped to this control. Any control containing the word "integer" automatically has a decimal precision of 0.
pxMenuBarMobile	The MenuBar control is mapped to this control. Use this control to display a read-only navigation rule in a section.
pxParagraphMobile	Allows you to include RTF (including styling), HTML, and plain text. Click the magnifying glass to provide the class name and the Paragraph rule name.
pxHTMLFragmentMobile	Allows you to include Pega references (page and property references), RTF (including styling), HTML, and plain text. Click the magnifying glass to provide the HTML Fragment rule name as a parameter.
pxSelectListMobile	Values mapped to pxSelectListMobile appear as a select box in the mobile portal. PromptSelect uses a local list and a prompt list. PromptFieldValue uses Table Type of Field Value on the Property rule. Mobile and desktop applications support this control. If the Control field on a property is blank or set to Default, you must configure the control on the cell property panel. DynamicSelect uses a report definition, activity, or clipboard page. The Default Caption field on the parameter page is also supported.
pxTextInputMobile	Values mapped to pxTextInputMobile appear as a text box in the mobile portal. The controls Text, pxTextInput, pxPassword and pxObfuscated, and Password, are all mapped to this control.
pxAutoCompleteMobile	Autocomplete control is mapped to a mobile version of the control.
pxSignatureMobile	Do not map anything to this control. See PDN article Signature Capture with Pega Mobile.
pxGMapDirectionsMobile	Do not map anything to this control. See PDN article How to use mobile geographic map controls.
pxGMapLocationMobile	Do not map anything to this control. See PDN article How to use mobile geographic map controls.

Supported actions in button and link controls

The following table describes the action categories and action names that are supported for use in a mobile application. You may configure multiple actions on a button or link control.

Action Category	Mobile Action Name
Process Work	Show Flow Location Add New Work (from New or Create harness) Finish Assignment (from Perform harness) Cancel Save
Get Work	Create Work Open Assignment Open Work by Handle
Display	Refresh Section
Launch	Harness - Target value of `Pop-up Window` or `New Document` is supported. Local Action - Target value of Modal Dialog or Overlay are supported. Using Page is supported. Scan Barcode/QR Code - See PDN article How to use the mobile barcode and QR code scanner.
Advanced	Run Activity Run Script Run Data Transform

Atlas — Standard controls without parameters
Atlas — Standard controls with parameters

About controls
Atlas home