Form activity
Introduction
Form activity is a UI activity in Casewhere workflow. New form creation will be easier and less time-consuming with this activity.
For example:
- In Casewhere Admin:
- In Worker site
In this document, we will bring in:
| Sections | Description |
|---|---|
| How to add a new form | Steps to add a new form |
| Form Design | Overview about Form Design section in the Form Activity |
| Form Script | Overview about Form Script section in the Form Activity |
| Validation Rules | Overview about Validation Rules section in the Form Activity |
| Navigation | Overview about Navigation section in the Form Activity |
| Advanced Settings | Overview about Advanced Settings section in the Form Activity |
How to add a new form
In Edit Workflow Definition step, click on Form icon in Add Activity Definitions section and drag it to the added Step panel:
After the drag-and-drop step, the dialog of creating Form activity will be opened. There are 2 required fields in this dialog: Name, Display Name. You must fill them to save the form:
Other configurations for the form are not required. It can be done in either creation step or editing step.
Form design
Form design is the section where you can configure the user interface of a form. You can add fields to the form from data source or toolbox. You can also configure the properties, events of a field, add variables for a field in the form.
Overview
There are 3 sections in Form Design: Fields and variables, Form area, Properties & Events configuration
Add field to form from Data source
Step 1 - Add data source:
- In Fields tab of left menu, click on Add button:
- Then, the dialog named Add Data Source is opened with fields:
- Data Class: this field is required. You need to specify the data class your form will interact with. If you don't see any data class here, you will need to enable these data classes in your workflow definition. See here for more information.
- Name: This field is required. The data source name must be unique. Casewhere uses the data class name by default, but you can change it. You can reference the data source by name in scripting.
- Reference Type: this field is required. At the moment, Casewhere only supports Single Object:
- Single Object: only 1 data object will be created after the form is submitted in worker site
- Reference To: this field is required. You need to select 1 of 2 options:
- New Object: use this option if you want to create a new data object
- Existing Object: use this option if you want to edit an existing data object
- After filling all required fields and clicking on Save button, the list of fields of the data source will be displayed in left menu. You can also add multiple data sources:
- You can also edit/delete the added data source by selecting 1 data source, and click on the Edit/Delete button:
Step 2 - Add field to form and other actions:
- In the list field of the data source, click on a field that you want to add to the form. Then, drag the field to the form area and drop it into the expected cell. You can also change the position of the field by dragging and dropping to another cell. You can also add multiple fields in one cell.
- If you want to delete the added field from the form, click on the added field and press the Delete key on your keyboard. If you want to delete all added fields in 1 row, click on a cell in the row and click on 'Remove row'.
- You can also merge 2 cells horizontally by selecting 2 cells in a row, then clicking on Merge Cells. To selecting 2 cells, use the Shift key.
- If you want to split a merged cell, select the cell and click on Split Cell.
Step 3 - Save the form:
- By clicking on Save or Save and Close button, changes on form will be saved.
Add field to form from toolbox
Besides adding field to form from the data source, you can also add fields from the Toolbox. Toolbox is a list of components which you can add directly to the form.
- Step 1 - Open Toolbox list
Click on Toolbox tab next to Fields tab to open the Toolbox list. The components in this list are:
| Component name | Description |
|---|---|
| Label | To add a label element |
| Textbox | To add a textbox field |
| Masked Textbox | To add a textbox field with specific validation of input values |
| Checkbox | To add a checkbox field |
| Numeric Textbox | To add a textbox field that allows to input numeric values only |
| Text Area | To add a text-area field |
| File Upload | To add a file upload field |
| Select | To add a drop-down list field |
| Datepicker | To add a date time field |
| Radio List | To add a radio button field with multiple options |
| Checkbox List | To add a checkbox field with multiple options |
| Hidden Field | To add a hidden field |
| Time Input | To add a time selection field |
| Custom HTML | To add a field which you can customize HTML |
| Button | To add a button field |
| PDF Viewer | To add a PDF Viewer field |
| Word Editor | To add a Word Editor field |
| Widget Container | To add a widget container which you can create a new widget or reuse another widget |
| Monaco Editor | To add Monaco editor |
| Icon Picker | To add an icon picker field with pre-set icons. |
- Step 2 - Add component to the form
Click on a field in Toolbox list and drag it to the form area and drop it into expected cell.
Add workflow variable
- Step 1 - Open Variables tab
- Step 2 - Click on Add new variable field
- Step 3 - Input name of variable and press the Enter key to add the variable. (Variable can only be created in Scripted activity)
- Step 4 - Select an added field in Form area, and select Properties menu item. In Properties list, expand Data binding list and select the variable.
Field properties configuration
After adding a field to the form, by selecting the field, Properties menu will be opened in the right of form area. You can configure specific properties for the fields. The properties are:
| Property name | Description |
|---|---|
| CSS Class | Is used to fill name of a CSS that is applied for UI of the field. It can be CSS class of a component in Worker site component, Theme or Bootstrap library. |
| Client Data Binding | Is used to bind data to a field that does not exist in data source. |
| Client Enabled Rule | You can add enabled rule for the field according to a specific field value. |
| Client Readonly Rule | You can add read-only rule for the field according to a specific field value. |
| Client Required Rule | You can add mandatory rule for the field according to a specific field value. |
| Client Visible Rule | You can add visible rule for the field according to a specific field value |
| Data Binding | Is used to bind a workflow variable to the field |
| Default Value | Is used to fill default value of the field on UI |
| Enabled | If you choose true, the field will be always enabled. If you choose false, the field will be always disabled. You can also custom the enabled for the rule by selecting Custom and add expression |
| Field Label | Is used to field the label of the field on UI |
| Help Text | Is used to select the text resource for help text of the field. You can also create new text resource for the help text by clicking on Create new key link item |
| Help Text Icon | Is used to fill icon name for help text |
| Help Text Position | Is used to set the position of help text: - Label: help text icon is displayed at the right of field label, help text will be displayed by hovering over help text icon - Input: help text icon is displayed at the right of the field, help text will be displayed by hovering over help text icon - Inline: help text is displayed above the field. |
| Label Alignment | Is used to set the alignment for the label: Left, Right, Top |
| Label Width | Is used to set the width for the field |
| Name | Is used to change name of the field |
| Min value | Is used to set min value can be input to the field |
| Max value | Is used to set max value can be input to the field |
| Placeholder | Is used to fill text in placeholder of the field |
| Range message | Is used to define error message when input value does not match min/max range |
| Readonly | If you select true: the field is always able to read only If you select false: the field is always able to read and edit If you select Custom: you can customize the specific rule of reading or editing for the field |
| Required | If you select true: the field is always required If you select false: the field is always non-required If you select Custom: you can customize the specific rule of mandatory for the field |
| Required message | Is used to select text resource for Required message. You can create new required message by clicking on Create new key |
Field events configuration
In Properties & Events section, by clicking on Events tab, list of events will be displayed. You can configure action of an event for the field. Those events are:
| Event name | Description |
|---|---|
| Blur | Is used to define the action when the field loses focus |
| Change | Is used to define the action when value of the field is changed |
| Click | Is used to define the action when the field is clicked |
| DbClick | Is used to define the action when the field is double clicked |
| Focus | Is used to define the action when the field gets focus |
| KeyDown | Is used to define the action when user is pressing a key |
| KeyPress | Is used to define the action when user presses a key |
| KeyUp | Is used to define the action when user releases a key |
| MouseDown | Is used to define the action when a mouse button is pressed down on the field |
| MouseEnter | Is used to define the action when the mouse pointer is moved onto the field |
| MouseLeave | Is used to define the action when the mouse pointer is moved out of the field |
| MouseMove | Is used to define the action when the mouse pointer is moving while it is over the field |
| MouseOver | Is used to define the action when the mouse pointer is moved over the field |
| MouseUp | Is used to define the action when the mouse button is released over the field |
Form Scripts
Form scripts is the section where you can view the script of the added form in Form Design: HTML, JavaScript, CSS.
The script is read-only. Casewhere will auto-generate the script when you modify the form design.
Validation Rules
Validation Rules is the section in the Form activity dialog where you can create, edit the validation rule.
For example, below is a validation rule for user's date of birth:
Create a new Validation Rule
By clicking on the Create button, a dialog to add validation rule will be opened:
In this dialog, there are fields:
| Field Name | Description |
|---|---|
| Name | Is used to fill name of the validation rule |
| Expression | Is used to fill expression of the validation rule |
| Error Message | Is used to fill error message when field value does not match validation rule |
| Active | Is used to activate or deactivate the validation rule. If the checkbox is unticked, the rule will be deactivated |
Edit a Validation Rule
By selecting an existing validation rule, then clicking on Edit button, the dialog of editing validation rule will be opened. You can change the name, expression, error message, active state of the validation rule.
Edit position of a validation rule in the list
You can use Up and Down button to change the position of a validation rule in the list. First, select a rule, then click on Up/Down button move it up/down.
Navigation
Navigation section in Form activity is where you can configure the navigation logic for your activity.
More details can be found in: Workflow-navigation
Advanced Settings
Advanced Settings is the section in the Form activity where you can configure some additional advanced settings for the form.
The advanced settings are:
| Settings name | Description |
|---|---|
| Auto Commit Changes | If this checkbox is ticked, the filled data will be committed automatically without completing whole flow. This settings is used to support the case of multiple activities that next activity need the data of the previous one before completing the flow. You need to carefully consider using this settings because it can impact the performance if it is used everywhere without necessary. |
| Ask users to confirm unsaved changes | If this checkbox is ticked, a warning message will be displayed when user leaves the form without saving changes |
| Enable Save Draft | If this checkbox is ticked, saving draft function will be enabled |
| Save Draft Warning Message | Is used to fill the warning message which will be shown when user leaves the form without saving it. By this, the potential issue of losing data can be avoided. |
| Audit Event Name | Is used to customize the event name for audit. From version 2.7, Casewhere auto audit all events that change the data state. The activity name is used for audit by default but you can customize it by using this settings. |
After complete all configuration, by clicking on Save, all changes will be saved.