Learn how to add, delete, or rename a Screen page.
By default, a Screen contains one page with the same name as the Screen itself. However, Process Designers have the ability to add additional pages as needed. Each page within the Screen is assigned a unique name and users can navigate to that page through the Page Navigation control.
Pages can only be added to Form-Type Screens.
Add a Page Navigation control to allow request participants to navigate to additional pages within a Screen.
Follow these steps to add a new page to a Screen:
Click + Create Page option to create a new page. The Create New Page screen is displayed.
In the Page Name setting, enter the name of the new page.
Click Save. The new page displays as a separate tab next to the current page at the top of the screen.
Click on the tab associated with a page to view that page.
The newly added page is also accessible from the Pages menu.
Pages can only be edited to Form-Type Screens.
Follow these steps to reorder pages in a screen:
Open a screen with multiple pages.
The Edit Pages screen is displayed.
Deleting a page from a Screen cannot be undone.
Add a control that uses ProcessMaker's Artificial Intelligence (AI) to generate Screen components that use natural language to describe how they work.
Use ProcessMaker's AI Assistant to generate a Screen without knowing how to use Screen Builder controls. From within Screen Builder, use the AI Generated control to use ProcessMaker Artificial Intelligence (AI) to generate functional Screen controls by describing in natural language how those controls function.
AI Generated controls are a no-code way to design a Screen quickly:
Add an AI Generated control to your Screen.
Enter text into the AI Generated control using almost any natural language that describes the functional needs of a section or the entirety of your Screen. You may enter your natural language Screen description in one language, but specify that the Screen user interface labels be in a different language. Multiple AI Controls may be used in a Screen, one to describe and generate different sections of that Screen without even understanding what each Screen Builder control does.
The AI Generated control previews the layout of the Screen based on its interpretation of your natural language.
Optionally regenerate a new preview based on the same or different description, or accept the layout.
After accepting the layout preview, the AI Generated control renders the preview into functional controls that are ready to use. You may further configure those controls if necessary: these are now standard controls like any other.
The following Screen Builder controls are supported. These are listed in alphabetical order.
This control is only available for Form-type Screens. See Screen Types.
Follow these steps to add this control to the Screen:
Drag the AI Generated icon into the Screen Builder canvas. Existing controls on the Screen Builder canvas adjust positioning based on where you drag the control.
After the AI Control renders the control(s) for your Screen, review configuration settings and then validate your Screen.
The AI Control does not render in Preview mode until the AI-generated components are applied to the Screen. In Preview mode the following message displays: AI Assistant is unavailable until you apply changes.
After adding an AI Generated control to a Screen page, enter a functional natural language description for the Screen components that the AI Generated control will generate.
Follow these steps to describe how the Screen components are to function:
Select the AI Generated control into which to enter your natural language description of its functionality.
In the Description setting, enter a functional natural language description for the components that the AI Generated control will generate. One AI Generated control description may use no more than 1000 tokens. A token is a common sequence of characters found in text for a particular language. Generally, one token corresponds to approximately four (4) characters of common English-language text. This corresponds to approximately 100 tokens to about 75 words in English. To the right of the Description label displays how many tokens your description currently uses. If your description exceeds 1000 tokens, shorten the length of your description.
Click the Generate button. The AI Generated control displays a progress bar for the percentage completion of a Screen preview based on your description. When complete, a preview of your Screen control(s) displays within the AI Generated control. Use this preview to evaluate if the AI Generated control provides the control(s) you intended.
Do one of the following:
Regenerate the preview: Revise and/or regenerate the AI Generated control's preview of the Screen layout based on the same or a different description.
Accept the preview: Click the Apply Changes button above the preview. The AI Generated control immediately renders the preview as functional controls which can be configured from the default settings the AI Generated control provides. The Variable Name setting for each rendered control uses a placeholder value since this setting is required for all controls.
The AI Generated control has the following panels that contain settings:
Enter a functional natural language description for the components that the AI Generated control will generate. As you enter a description, the number of tokens that the AI Generated control will use to generate those components displays. A maximum of 1000 tokens may be used per AI Generated control. See Describe the Functional Components for Your Screen Using Natural Language.
Below are settings for the AI Generated control in the Advanced panel:
Note the following regarding how to use visibility rules:
To make this control hidden until another control contains a value, enter the Variable Name setting value of that control to this control's Visibility Rule setting.
Select on which device types this control displays:
Desktop: The control displays only on desktop devices. Enable the Show for Desktop toggle key.
Mobile: The control displays only on mobile devices. Enable the Show for Mobile toggle key.
The AI Generated control does not render in Preview mode until the AI-generated components are applied to the Screen. In Preview mode the following message displays: AI Assistant is unavailable until you apply changes.
See the following best practices regarding custom CSS in Screens:
Click the Pages icon at the top of the screen to see the Pages menu.
Click the pages icon to see the Pages menu and then select See all Pages.
Click the Edit icon to change the name of the screen.
Click the Delete icon to delete the screen.
Use the Move icon to reorder the pages in this screen.
Expand the AI Assistant category to the left of the Screen Builder canvas, and then locate the AI Generated icon .
Place into the Screen Builder canvas where you want the control to display on the Screen.
Expand the Configuration panel to the right of the right-side of the Screen Builder canvas if it is not already. The Description setting displays.
Specify an expression that indicates the condition(s) under which this control displays. See Expression Syntax Components. If this setting does not have an expression, then this control displays by default.
Both: The control displays on both desktop and mobile devices. Both toggle keys are enabled by default.
Enter the value to represent this control in custom CSS syntax when in Custom CSS mode. As a 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.
Validate That Your Screen is Ready for Use in Processes.
Before you deploy your Screen to production, validate that it is ready for use in Processes for the following reasons:
Minimize problems when previewing your Screen.
ProcessMaker Platform represents Screens as JSON data models. You can view any JSON data model in Preview mode to test how a Process's JSON data model or another Screen's data model interacts with your Screen. When testing a JSON data model, the Screen Validation feature indicates when that data model is not valid.
Minimize problems when Process designers test your Screen in their Processes. Since your Screen may be used in multiple Processes in your organization, ensure that your Screen won't cause production problems later.
Follow these steps to validate a Screen:
Screen Validation is enabled by default. If the Screen Validation toggle key is disabled, enable the Screen Validation toggle key so that Screens Builder automatically validates your Screen as you work.
Work on your Screen. Screens Builder indicates any validation issues as you work. The following indicators may occur:
No errors found: If no errors are found, the following text displays to the right of the Open Console button: 0. The green check mark displays. Your Screen is valid.
Furthermore, controls that are associated with errors display a red-colored highlight.
If errors are found, click the Open Console button again to hide the error summary. Make changes to your Screen or JSON data model and then repeat steps 3 and 4 again until Screens Builder finds no validation errors.
A Screen can be saved in Design mode.
A Screen can be published in two ways. See the following sections regarding how a Screen may be published:
Publish a single version of your Screen.
Publish distinct versions of your Screen.
Click the Publish button from Screen Builder's top menu to save the Screen.‌ This action overwrites the previous publication of this Screen without maintaining a record of its previous publication(s).
Distinct versions of a Screen can be published. A version is a set of changes published for a Screen since the last publication. Versioning maintains a record of all named and unnamed publications to that Screen. Any of these versions may be viewed or retrieved, if needed.
Follow these guidelines to publish a new distinct version of your Screen:‌
Click the Publish button from Screen Builder's top menu.‌
Do one of the following:
Publish an unnamed version:
Follow these steps to publish an unnamed version:
Click Save to publish an unnamed version. Otherwise, click Cancel to return to Screen Builder without publishing. As a best practice, name each published version to provide auditing and documentation to what has changed in each publication. Otherwise, Process Designers that manage versions of this Screen do not view unnamed versions when the Only show named versions toggle key is enabled while viewing that Screen's version history.
Save a named version:
Follow these steps to publish a named version:
In the Version Name setting, enter a name for this version. The version name displays when viewing the version history of that Screen and helps identify this version. Although this setting is not required, as a best practice name each version for easier maintenance, documentation, and auditing purposes. Name the version that describes changes in this Screen.
In the Additional Details (optional) setting, optionally enter details of the changes made in this version. The additional details display when viewing the version history of that Screen and helps other Process Designers or Administrators understand the changes made in that version. Enter details which concisely summarize the changes made in this version.
Click Save to save this version. Otherwise, click Cancel to return to the Screen Builder without publishing.
Preview your Screen to evaluate how users would interact with your Screen: test for desktop and mobile devices, and enter data into the JSON data model to mock Request data.
Screens can be re-used in multiple Processes. Behind the controls that compose these digital forms, Screens are JSON files. Processes are also represented as JSON data models that pass Request data to Tasks defined in the Process model. As such, preview, evaluate, and test how data in your Screen is passed to JSON data models before using that Screen in production Processes.
Furthermore, test how your Screen displays on Desktop and Mobile devices. In doing so, evaluate which control(s) to display on Desktop and/or Mobile devices and how well they render on each. A control may be configured to display on one or both device types.
The AI Control does not render in Preview mode until the AI-generated components are applied to the Screen.
Preview your Screen in the following ways:
Preview how your Screen displays on desktop and mobile devices.
Prior to previewing your Screen, ensure to configure each control on which device type it displays:
Desktop: The control displays only on desktop devices. Use for controls that require a wide width to display properly. Ensure that the Show for Desktop toggle key is enabled in the Device Visibility setting within the Advanced panel for that control.
Mobile: The control displays only on mobile devices. Use for controls that are meant to be interacted with on mobile devices. Ensure that the Show for Mobile toggle key is enabled in the Device Visibility setting within the Advanced panel for that control.
Both: The control displays on both desktop and mobile devices. Ensure that both toggle keys are enabled.
Follow these steps to preview your Screen for each device type:
Open the Screen. The Screen is in Design mode.
Below is an example of the same Screen previewed for each device type.
Optionally, use a Vocabulary from which to preview your Screen to ensure that it complies with any regulatory compliance that Tasks using this Screen must comply. A Vocabulary is a JSON schema. The JSON schema describes the data objects, types, and structure that you want in both a machine- and human-readable format. The Vocabulary from which to preview your Screen must already exist.
Follow these steps to use a Vocabulary during your Screen preview and testing:
Open the Screen. The Screen is in Design mode.
Click the Preview button.
From the Select a vocabulary drop-down menu, select the Vocabulary from which to verify that your Screen complies with its JSON schema. Screen Builder loads the Vocabulary, and then evaluates if it is a valid JSON schema. One of the following messages display below the Select a vocabulary drop-down menu:
Valid JSON schema: If the JSON schema is valid, the following message displays: Data Valid for JSON Schema.
Invalid JSON schema: If the JSON schema is not valid, then the Vocabulary panel displays the errors that render the JSON schema invalid.
Enter or review data in the Screen controls as you would for a Task during a Request. Evaluate if your Screen processes the Vocabulary's JSON schema appropriately.
During your Screen evaluation, optionally do the following:
Optionally, enter mock Request data into your Screen to evaluate if your Screen processes expected Request data appropriately.
In the Data Input section, enter a JSON data model as your Screen's data input to evaluate how JSON data models for different Processes interact with the JSON data model for your Screen.
Follow these guidelines to enter mock Request data into your Screen to evaluate how your Screen processes expected Request data:
Open the Screen. The Screen is in Design mode.
Click the Preview button.
Enter a JSON data model into the Data Input panel. This JSON data model may come from a Process's Request data or another Screen. As you enter a JSON data model, the Screen Validation indicator displays if your JSON schema has any errors that prevents validation.
Enter or review data in the Screen controls as you would for a Task during a Request. Evaluate if your Screen processes the mock Request data appropriately.
During your Screen evaluation, optionally do the following:
Follow these guidelines to preview the JSON data model your Screen generates:
Open the Screen. The Screen is in Design mode.
Click the Preview button.
Enter or review data in the Screen controls as you would for a Task during a Request. When data is entered into each control, the Data Preview panel adds that control value into a JSON data model using the Variable Name setting value of that control. During an in-progress Request, this JSON data model would incorporate into that Request's data model.
Evaluate if your Screen generates data appropriately. To denote that the content of a Line Input control is of String
data type, those Request variable values display with one backslash (\
) preceding and following single- and double-quotation marks (`
and "
, respectively) that may be within the string of that Request variable value so as to indicate that these punctuation marks are interpreted as part of the literal string instead of functioning as punctuation. For example, a Line Input control with a text value of ""Louis Canera" has been employed at "Company" from '2015' until '2023'"
displays in the preview as "\"Louis Canera\" has been employed at \"Company\" from \'2015\' until \'2023\'"
.
Calculated properties also display in the Data Preview panel as part of the JSON data model if you submit the Screen by clicking the Submit Button control in Form-type Screens. See Manage Calculated Properties.
During your Screen evaluation, optionally do the following:
Create a new Screen or click the Edit iconto edit the selected Screen. The Screen is in Design mode. Though you can enable Screen Validation in Preview mode, you may only fix validation errors in Design mode.
Errors are found: If errors are found, Screens Builder displays how any errors are found to the right of the Open Console button. The error icon displays with the number of current errors. Click the Open Console button to display a summary of the errors. Below is an example.
The Commit Changes screen displays to name that published version of this Screen.
Click the Preview button. The Screen previews for the desktop by default: the Preview Desktop button is enabled.
Click the Preview Mobile button to view your Screen as if on a mobile device.
Expand the Vocabulary panel that is on the right-side of the Screen Builder canvas if it is not already.
Expand the Data Input panel that is on the right-side of the Screen Builder canvas if it is not already.
Expand the Data Preview panel that is on the right-side of the Screen Builder canvas if it is not already.
Click the icon to open a preview of the data. The Output Preview Panel displays the JSON structure and the Data Browser canvas. To navigate JSON data in the Data Browser, see Data Browser.
Design your Screen for Request participants to interact with Request data.
Use Screen Builder to design Screens for your Processes. Screens are designed independent of Processes: any Screen can be used in any Process, even those that you did not design. Screens can be exported and then shared with other Process designers so they may import them for their Processes.
While Screen Builder has an easy-to-use drag-and-place design interface to edit and preview Screens, ProcessMaker Platform represents them as JSON data models. You can view the JSON data model while in Preview mode.
You can use four types of Screens: Form, Display, Email, and Conversational. For details on these types, see Screen Types.
Screens are composed of controls. Use controls to provide your Screen with specific functionality. See Control Descriptions and Inspector Settings.
Below are a few examples of these controls:
Display text.
Provide a group of radio buttons to allow the Request participant to select an option.
Provide a drop-down menu to allow the Request participant to approve or reject a Request.
Provide a text area where the Request participant can enter text.
Provide a date control where the Request participant can select a date.
The Screen Builder can be used in one of the following modes:
Use Design mode to design your Screen. Design mode is the default mode when a Screen is created or edited. While in Design mode, use the Design setting section to configure controls that you place into your Screen Builder canvas.
See Control Descriptions and Inspector Settings.
Use Preview mode to view and test your Screen. Test how your controls function as a form user would experience your Screen during a Request.
Furthermore, test how the Screen's controls you configured in Design mode interact with JSON data models. ProcessMaker Platform represents Screens as JSON data models. You can view any JSON data model in Preview mode to test how a Process's JSON data model or another Screen's data model interacts with your Screen. Viewing the JSON data model can be helpful to see how values are entered into the Screen as well as to use that JSON data model in your Scripts.
Use Calculated Properties mode to add Calculated Properties to that Screen. A Calculated Property is any value, mathematical calculation, or formula. A Calculated Property's determines its value either through a mathematical formula or valid JavaScript, and may include values from Screen control values and Magic Variables during that Request. Likewise, a Calculated Property's value can display in a Screen control during that Request. Calculated Properties can only be used within and only affect the Screen to which the Calculated Property is defined.
Use the Custom CSS mode to add custom CSS styles to a Screen.
Use Watchers mode to add Watchers to that Screen. During a Request or while previewing the Screen, a Watcher monitors when the value of a control in that Screen changes or receives a value, acts upon a Data Connector or runs a Script using that control's value, and then outputs its result to another Screen control.
See Manage Watchers.
Create a Screen or edit a Screen in which to add the control.
Expand a category in the Controls Menu on the left and locate a control to add.
Click-and-drag the control into the Screen Builder canvas. Existing controls on the Screen Builder canvas adjust positioning based on where you drag the control.
Drop the control into the Screen Builder canvas where you want the control to display.
View the Screen Controls section for detailed information on all available screen controls.
After adding a control to a Screen page, you may move it to another location on that page such that it is above or below other controls placed on that page. A control cannot be moved to another Screen page.
Follow these steps to move a control to another location on that Screen page:
Place the control at the location on the page you want it. The other control(s) on the page automatically adjust position.
Copying a control also copies the current settings of that control. The copied control displays below other controls placed on that Screen page.
Follow these steps to copy a control:
Select the control to be copied.
Deleting a control also deletes configuration for that control. If you add another control, it will have default settings.
Follow these steps to delete a control from a Screen page:
Select the control to be deleted.
Follow these steps to use the Undo button in Screen Builder:
Make a change in the Screen or any of its controls' settings. The Undo/Redo buttons are enabled.
Click the Undo button to undo the most recent change if necessary. Continue using the Undo button as many times as necessary or until the Screen's state when the Screen was created/opened.
Click the Redo button to redo any revision undone by the Undo button up to the current state.
Screen Builder automatically saves your Screen every five (5) seconds when changes are made to any of the configuration panels. Regardless of whether you publish your Screen prior to leaving Screen Builder, the next time you edit that Screen, the changes since its last publication remain intact.
If necessary, discard the changes to your Screen since its last publication.
Follow these steps to discard changes to your Screen since its last publication:
Click the Discard button. Screen Builder discards the changes since last starting to edit that Screen, and then closes. The Scripts page displays.
Since Screen Builder saves changes to your Screen automatically when changes are made to any of the configuration panels, it is not necessary to manually save your changes. However, you may close Screen Builder without publishing your changes, but keep all your changes intact.
While in Screen Builder, click the Close button. Screen Builder closes with your saved changes. The Screens page displays.
Place your cursor anywhere on the control not displaying the Duplicate Controlor Delete Controlbuttons.
Hold your cursor, then drag the control above or below other controls on that Screen page. Screen Builder previews where the control would display on the page based on how you position the control above or below other controls. If the control cannot be placed in a location because your cursor is above an existing control or too far to the left or right of the page, theicon displays in the preview.
Click the Duplicate Control button. The control copies with its current settings, and then displays below other controls placed on that page.
Click the Delete button . The control deletes. Other controls on that Screen page adjust their locations automatically.
Screen Builder displays the Undo and Redo buttons in the upper right corner of the Screen Builder canvas. The buttons are disabled when a Screen is initially created or opened until a change in the Screen is made.
Create a new Screen or click the Edit Screen icon to edit the selected Screen. Screen Builder displays.
While in Screen Builder, click the ellipses menu, and then select Discard Draft.