Follow best practices when designing Screens.
The Advanced Screens package deprecated in March 2021.
See ProcessMaker University training to learn how to design Screens.
If you use the Advanced Screens package, please contact your Customer Success Manager.
Follow these best practices when designing Screens in Screen Builder.
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.
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.
Set the tab order for these controls as displayed from top to bottom as follows:
Set the tab order for all applicable controls for the best Screen usability experience and to avoid unexpected usability.
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.
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.
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.
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.
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.
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.
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.
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:
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.
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.
Avoid the following practices when designing Screens in Screen Builder.
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.
Watchers that use Scripts as their Source can adversely affect your Screen's performance. Therefore, when defining such Watchers, a warning message displays.
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.
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.
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.
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.
Follow best practices, and avoid worst practices, when designing Form-type Screens.
Follow basic form design best practices so your Form-type Screens are easy to navigate and read. Many of these best practices may apply to Display-type Screens.
Use Multicolumn / Table controls to organize the layout and width of other controls.
For each example, the Bad Practice tab displays by default. Click the adjacent Good Practice tab to view the best practice to follow. Design practices that are similar are grouped into the following sections:
Avoid using placeholders for Line Input controls. When users start typing in the controls, the placeholders disappear.
Use labels in controls to indicate their purpose, since they are always visible for users to see.
See the Label setting for the Line Input control for more information.
When a user navigates through a multi-column Screen, making the user follow a Z-pattern is more difficult for the user's eyes. Users might not even know where to start.
If the Line Input controls associate with one another, place them in one horizontal line.
If your form is large, do not use all Line Input controls in one section.
Use the Rich Text control to add headings that break the form into logically-related groups.
Avoid text redundancy as shown in the example below.
Be as concise as possible in control labels.
If there are fewer than four options, as a general guideline do not put them in a Select List control as drop-down options. This design requires the user to click twice to commit an action: once to display the Select List control options, another select an option.
If there are fewer than four options, show the options immediately using Submit Button controls. This design requires one click to commit an action.
By providing no user guidance for information to enter into the form, users become confused.
Use helper text to provide context how to interact with each control.
Unmasked Line Input controls allow users to introduce errors when entering commonly-used information.
Use masking patterns to pre-format commonly used information, thereby allowing users to enter information accurately. See the Custom Format String setting for the Line Input control for more information. Click the image below to enlarge.
Entering the following Script code for a Record List control without Row IDs does not work as expected such as allowing to edit, delete, or add records.
When initializing a variable for a Record List control in a Script code using a Calculated Property, it is essential to ensure that each row contains not only the record attributes but also a unique row_id
attribute. This row_id
should ideally be a hashed value or a unique string for each row. The presence of this row_id
is crucial for internal row tracking. For example, if we have a Record List control of first_name
and last_name
, the Calculated Property should return something like this:
Control Label | Tab Order Number |
---|---|
First Name
Middle Name
Last Name
Submit Your Name