Screen Design Best and Worst Practices
Follow best practices, and avoid worst practices, when designing Screens.
Screen Builder Best Practices
The Advanced Screens package deprecated in March 2021 for ProcessMaker 4.1 release.
See ProcessMaker University training to learn how to design ProcessMaker Screens.
If you use the Advanced Screens package, please contact your Customer Success agent.
Follow these best practices when designing Screens in Screen Builder.
Naming Request Variables for Screen Controls
Controls that have the Variable Name setting use this value as a variable name in the Screen in which that control is used. Use unique Variable Name settings from any other control of the same type in all Screens in your organization. Why? If a Process uses two different Screens in which two controls of the same type have the same Variable Name setting, the value of the first Screen's control overwrites the value of the second during Requests.
For example, suppose you have a Process that uses two different Screens that have a Line Input control with the setting FirstName
. During a Request, the first Line Input control receives a value. As the Request continues, that Line Input control's value automatically overwrites any value in the second Screen's Line Input control because they have the same Variable Name setting. This may be unintended. This is why it is helpful to experiment with JSON data models in Preview mode.
To avoid this issue, establish a naming convention with all Process Owners in your organization for Variable Name settings. For example, use a naming convention such as <ScreenName>_<FieldName>
. This naming convention minimizes two controls of the same type in different Screens to have identical names.
Use Variable Name setting values that provide context to that control's use so that when viewing the JSON data outside the context of that Screen, you and other designers understand information that control contains in the Request.
Tab Order for Keyboard Navigation
Use the Tab Order setting for applicable controls to coordinate the keyboard navigation order that a control takes focus amongst the structure of other controls in a Screen. Assistive technology users often use a keyboard for navigation. When the tab order for a Screen's controls is designed well, that Screen navigates via keyboard in the logical and intuitive structure of that Screen's content.
Follow these best practices to set the tab order for a Screen's keyboard navigation:
The tab order should follow the visual flow of the page: left to right (for Western readers), top to bottom.
Set the first control's tab order to
1
.Set the number for each subsequent control the sequential order that each control takes focus in the keyboard navigation order. Consider the following example.
![](https://docs.processmaker.com/~gitbook/image?url=https%3A%2F%2F1204157936-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FyEmSGNAM9WQCKnns9V9j%252Fuploads%252FnRoOXP3Su9GbVoOmnDPY%252FTab%2520order%2520best%2520practice%2520example%2520Screen%2520Builder.png%3Falt%3Dmedia%26token%3D364343a3-653a-4886-8041-548bfee71184&width=768&dpr=4&quality=100&sign=b03e6d5&sv=1)
Set the tab order for these controls as displayed from top to bottom as follows:
Control Label | Tab Order Number |
---|---|
First Name | 1 |
Middle Name | 2 |
Last Name | 3 |
Submit Your Name | 4 |
Set the tab order for all applicable controls for the best Screen usability experience and to avoid unexpected usability.
CSS Selector Naming Best Practice
Use the same CSS Selector Name value on different controls of the same type to apply the same custom CSS style to all those controls.
Visibility Rules Override Custom CSS Settings
If a Screen control affected by a visibility rule is hidden by default from custom CSS, the visibility rule overrides the custom CSS design. For example, if custom CSS is designed to hide a Screen control by default when that control's visibility rule dictates that it be visible, the visibility rule overrides the custom CSS to display that control. As a best practice, use visibility rules instead of custom CSS to hide a control by default.
Duplicate the JSON Array in a Select List Control Used in a Loop Control
When using a Select List control that gets its options as a JSON array from a data source, and that Select List control is used in a Loop control, follow this best practice:
Configure the Select List control to get the JSON object of the array, not only values.
Within the Loop control, duplicate the JSON object so that JSON object elements match those of the Select List control's.
Consider this example. The following is a JSON object that contains the JSON array from which a Select List control could use as its options when configured to reference the JSON object.
Download and then import the following Screen into Screen Builder. Preview the Screen to observe how the Select List control functions within the Loop control: select an option, and then enter values. Observe the JSON array that displays in the Preview panel.
Number of Controls in a Screen
For optimal Screen performance, as a best practice use fewer than 25 controls in one Screen. When adding more than this number, a warning displays.
![](https://docs.processmaker.com/~gitbook/image?url=https%3A%2F%2F1204157936-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FyEmSGNAM9WQCKnns9V9j%252Fuploads%252FwwGGrTUCruObaneUEjWq%252FMore%2520than%252025%2520elements%2520warning%2520-%2520Screen%2520Builder.png%3Falt%3Dmedia%26token%3D96f1daf8-41c4-4a3d-bca2-c3a7631ece06&width=768&dpr=4&quality=100&sign=ae0f998d&sv=1)
Use Nested Screens or divide your Task into multiple steps to avoid creating large Screens that adversely affect performance. Alternatively, use the Page Navigation control to create a multi-page Screen. See an example of using the Page Navigation Control to Design a Multi-Page Screen.
Use Date Picker Controls for Datetime Validation with a Vocabulary
As a best practice when a Vocabulary validates the JSON in a Screen for a datetime value, use a Date Picker control instead of a Line Input control.
Use Triple Mustache Brackets for Unescaped Characters
As a best practice when using HTML escaped characters like &
, <
, >
, /
, “
, '
, `
, or =
, use triple mustache brackets to avoid displaying incorrect values in Screen controls. Example: {{{name_with_character}}}
For more about mustache syntax, see mustache documentation.
Select List Controls: Using Single-Value Versus JSON Objects
Follow these best practice guidelines regarding the use of single-value JSON objects versus JSON arrays to reference Select List control options from Request data:
Use Single-Value Instead of Object if Select List Control Options May Change
As a best and general practice, use single-value JSON objects from which to reference Select List control options instead of a JSON array that contains all options within an array of objects.
If any value within the JSON object that contains all Select List control options change, such as via Request data, then none of the Select List control options display when a user clicks that Select List control.
Therefore, to use a JSON object that contains all Select List control options, ensure that none of the following would occur to the Request data from which the Select List control references its options:
Ensure that none of the values in any of the individual JSON objects would modify in any way.
Ensure that empty values are transformed to
null
. ProcessMaker Platform cannot accept empty values as options in Select List controls or Collection records.
Use Single-Value Instead of Object in a Select List Control When Editing a Collection Record
As a best practice, when editing a Collection record using a Select List control in a Loop control, configure the Select List control's Type of Value Returned setting with the Single Value option. This best practice applies only to this use case.
If you select the Object option, which reads the entirety of a JSON array or object instead of one value, ProcessMaker Platform expects the selected Select List control option to match that of the Collection record. However, when the Select List control is first selected by the user to view its options, the Select List control contains a different value, thereby causing an error.
When using a single value from which to select a Collection record, ProcessMaker Platform does not have this expectation. See Reference Request Data section in Select List control settings where this setting applies to this use case.
Screen Builder Worst Practices
Avoid these worst practices when designing Screens in Screen Builder.
Avoid JavaScript Custom Coding
Avoid adding custom JavaScript when designing Screens for the following reasons:
Custom JavaScript implementations are not under the ProcessMaker Platform Support scope: Because custom JavaScript implementations are not under the ProcessMaker Platform Support Scope, Support agents will not support custom JavaScript implementations.
Custom JavaScript implementations creates an unmaintainable business solution: By introducing custom JavaScript into Screen design that may affect workflow routing behavior outside of that Screen, you make that business solution much more difficult to maintain.
Avoid Using Watchers with Scripts
Watchers that use Scripts as their Source can adversely affect your Screen's performance. Therefore, when defining such Watchers, a warning message displays.
![](https://docs.processmaker.com/~gitbook/image?url=https%3A%2F%2F1204157936-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FyEmSGNAM9WQCKnns9V9j%252Fuploads%252FMILLJ45i6dEx9wYhHrhb%252FWatchers%2520with%2520Scripts%2520warning%2520Watcher%2520configuration%2520-%2520Screen%2520Builder%2520.png%3Falt%3Dmedia%26token%3D8f2d8f12-2e26-4e82-939e-153fb8f06fbc&width=768&dpr=4&quality=100&sign=e2ed4801&sv=1)
Use Scripts sparingly with your Watchers and consider other alternatives when possible. For example, instead of using a Script to call an API, use a Data Connector to connect to the API. Afterwards, use this Data Connector in your Watcher. See an example where a Data Connector is used in a Watcher to display Countries and Regions in Select List controls.
Select List Controls: Avoid Using Request Data for Options in Which JSON Objects May Dynamically Change
When configuring Select List controls to reference Request data for their options, avoid using JSON data in which a JSON object contains its own JSON objects that may change dynamically. The value of any JSON object may be changed dynamically in the following ways:
During a Request, a JSON object's value changes while routing.
The Request may reference Collection data that has changed since the Request started.
It is not good practice to store all data in one variable of type object
because any of the attributes can be modified at any time.
Instead, reference Request data that in which all JSON objects are peers of one another.
Note that this practice to avoid does not affect when you are providing your own Select List control options or using a Data Connector to get options.
Example of Request Data to Avoid for Select List Control Options
Consider the following JSON array in a control called Composers
that contains two JSON objects. The Request data at this moment in the Request is the content of that Record List control as a JSON object.
A Screen contains a Select List control with a Variable Name setting value of SelectedComposer
. This Select List control follows the bad practice to avoid described above by referencing the Composers
JSON array to return type Object.
See these sections in Select List control settings that document the settings described above:
Variable Name setting of
SelectedComposer
Options Variable setting of
Composers
During a Request, if the second option in the Select List control is selected, Dmitri Shostakovich, then the current Request data is as follows:
If a Task modifies the Record List values, the JSON objects in the JSON array have changed from the original values that Select List recognizes. For example, suppose the address in the second JSON object changes in the Record List control: Moscow
has been changed to Petersburg
.
When the Screen containing the Select List control accesses the Request data to get its values from the Composers
JSON array, the second JSON object is different. Therefore, the Select List control contains no options because the Composers JSON array is not identical to the object stored in the ComposerSelected
JSON object: ComposerSelected
contains the address with Moscow
, while the Composers
JSON array contains Petersburg
.
This example demonstrates why it is a bad practice to store JSON objects in which their values may change dynamically within other JSON objects.
Example of Request Data Permissible for Select List Control Options
Instead of following the example of the bad practice to avoid described above, configure the Select List control to store a single value for the type of value returned and reference the id
JSON key name in the Variable Name Property setting because its value is not likely to change.
Following this configuration, when the Select List control references the id
JSON key name, then the current Request data is as follows:
If any of the JSON objects in the Composers
JSON array change, the Select List control references a key name in the JSON object does not change. Therefore, the Select List control displays options derived from the Request data.
Related Topics
What is a Screen?What is Screen Builder?Screen TypesScreen Builder ModesValidate Your ScreenEdit Your ScreenAdd, Delete or Rename a PagePreview a Screen and Its JSON Data ModelManage Calculated PropertiesAdd Custom CSS to a ScreenManage WatchersUndo and Redo Changes in Your ScreenSave Your ScreenLast updated