ProcessMaker API Documentation
ProcessMaker Examples

Screen Builder Best Practices

Follow best practices when designing ProcessMaker Screens.

Screen Builder Best Practices

Follow these best practices when designing ProcessMaker Screens in your organization.

Naming Request Variables for ProcessMaker Screen Controls

Controls that have the Variable Name setting use this value as a variable name in the ProcessMaker Screen in which that control is used. Use unique Variable Name settings from any other control of the same type in all ProcessMaker Screens in your organization. Why? If a Process uses two different ProcessMaker Screens in which two controls of the same type have the same Variable Name setting, the value of the first ProcessMaker Screen's control overwrites the value of the second during Requests.

For example, suppose you have a Process that uses two different ProcessMaker 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 ProcessMaker 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 ProcessMaker Screens to have identical names.

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 ProcessMaker 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 ProcessMaker 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.

{
"selectList": [
{
"value": "Value 1",
"content": "Content 1"
},
{
"value": "Value 2",
"content": "Content 2"
},
{
"value": "Value 3",
"content": "Content 3"
},
{
"value": "Value 4",
"content": "Content 4"
}
]
}

Download and then import the following ProcessMaker Screen into your ProcessMaker instance. Preview the ProcessMaker 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.

Avoid Using Custom Scripts to Enhance ProcessMaker Screen Functionality

When designing a ProcessMaker Screen, it is possible to customize functionality by using custom scripts. However, such customization makes the ProcessMaker Screen prone to errors and difficult to support or debug later. Most design needs can be met without custom scripts by simply using the functionality available in ProcessMaker's Screen Builder.

Example of Disabling a Button Until a Toggle Key Is Selected

Consider the following ProcessMaker Screen design that uses the following controls with their respective default display states:

  • Check Box control: A Check Box control displays by default with the toggle key to acknowledge the terms of the form.

  • Rich Text control: A Rich Text control displays HTML containing the image of a disabled button until all required information in the form has been entered. The Rich Text control displays by default to appear as a disabled button.

  • Submit Button control: A Submit Button control remains hidden until the state of the Check Box control is True. Since the the Check Box control is FALSE by default, the Submit Button control is hidden by default.

For example, the Save Form button in the following screen appears disabled until the user agrees to the terms of the form.

After the terms are agreed to, the Save Form button enables.

Follow these guidelines to design a ProcessMaker Screen with a disabled button until a toggle key is selected. This example does not use a custom script as described as this best practice:

  1. Create a new ProcessMaker Screen. The new ProcessMaker Screen opens in Design mode.

  2. Add a Check Box control and configure the following settings:

    • From the Variable panel, enter in the Variable Name setting i_agree.

    • Enter in the Label setting I agree to the terms of this form.

    • From the Design panel, select the Toggle Style setting.

  3. Add a Rich Text control and configure the following settings:

    • From the Configuration panel, enter the following HTML in the Content setting:

      <span class="btn btn-primary disabled">Save Form</span>. This HTML uses the btn (button) class to display a disabled button using the same text SAVE FORM as the Submit Button control displays its Label setting value (described below).

    • From the Advanced panel, enter in the Visibility Rule setting i_agree == false. This visibility rule means that the Rich Text control remains hidden while the Check Box control's state remains FALSE (not selected).

  4. Insert a Submit Button control and configure the following settings:

    • From the Variable panel, enter in the Label setting Save Form.

    • From the Advanced panel, enter in the Visibility Rule setting i_agree == true. This visibility rule means that the Rich Text control hides while the Check Box control's state becomes TRUE (selected). The Submit Button control displays.

  5. The ProcessMaker Screen is now complete. Save your ProcessMaker Screen.

  6. Click the Preview icon to test the ProcessMaker Screen.

Related Topics