Self Help - Forms

Last modified on 2023/07/25 18:31

A form is a type of resource in a Self Help project. It is used to collect information entered by users when running a procedure.

  • Forms are built and managed in edit mode in Desktop Studio.
  • They can be inserted in the procedure of a Self Help project. Open url.png See the use case.
  • The information collected is stored in project variables that can be used in automatic or manual actions during the procedure.
  • They can be dynamic. Open url.png See the description.
     

Structure of a form

  • A form is made up of cells, each of which can contain an element, e.g. text field, list of values, etc.  Open url.png See Types of elements in forms
  • The properties of each element can be modified to define the form's visual aspect and behavior on screen.

Example

  • Define a form to collect the information required for creating a ticket in Service Manager
       Open url.png See the use case for the Service Manager connection package.
  • Define a form to collect the information required for sending an email via a connector
  • Define a dynamic form for displaying the different logos of EasyVista products on a given page depending on the user's options
       Open url.png See the use case.
            Example - Dynamic form - Two choices.png

Caution

  • When you reduce the number of rows or columns in a form, all of the rows or columns that exceed the number you specify will be deleted.

    example  Form with four rows reduced to three rows ==> The last row of the form will be deleted.
    Modify form structure.png

  • You cannot modify an element's type once you have inserted it in a form. You must delete it and then create it again.

Best Practice

  • Use dynamic forms as an alternative to a tree structure with several branches.
  • Create groups of fields to structure your form.
  • Use labels to add titles to different sections in a complex form.
  • Copy and paste to move different form elements.
  • You can initialize the items in a list of values in different ways. Open url.png See Input/Output tab > Advanced Mode.
    • If the values in the list are only used in the form, you can use parameters to enter them. Their display is restricted to the objects using them and those calling them. This is the default option.
    • If you want to reuse the values in the list in other forms within the same Self Help project, you should enter them using variables in the project library. They will then be visible and common to all objects in the Self Help project.

Characteristics of forms

Dynamic forms

   Open url.png See the use case.

  • Dynamic forms contain one or more dynamic fields. Open url.png See the properties of the Type and Validation tab in the Description pane.
  • A computing procedure, transparent to users, is associated with the dynamic form. It is used to run a script found in the macro of an Action step.
    Note: The computing procedure is unique, regardless of the number of dynamic fields in the form. It must therefore take into account all of the criteria in the form page.
  • When a dynamic field value is modified, the computing procedure is run and the page will be refreshed using the new criteria.

Types of elements in forms

Element Description Display
Input field Displays a label followed by a field for entering text in a single row. Element type - Input field.png
Password field Displays a secure field for entering a password.

The characters entered are automatically hidden by the tilde, *.

Element type - Password field.png
Group of fields Used to group several elements together in a cell. Element type - Field group.png
Label Displays text in read-only mode without an input field.

example Add titles to separate sections

Element type - Label.png
Multiple choice list of values Displays a list from which users can select multiple values.

Several display modes are available, e.g. action buttons, checkboxes, lists, etc. Open url.png See the description.

Element type - Multiple choice value list.png
Single choice list of values Displays a list from which users can select only one value.

Several display modes are available, e.g. action buttons, checkboxes, lists, etc. Open url.png See the description.

Element type - Single choice value list.png
Multiple lines input field Displays a field for entering text in multiple rows. Element type - Multiple line input field.png

Display modes for lists of values

Multiple choice list of values and Single choice list of values elements

        Open url.png See How to specify a list of values.

Display mode Description Display
Buttons Values appear as action buttons.

They can be displayed all in one row or one below the other.

Users can select several values.

List value appearance - Button.png
Radio buttons Note: Only for single choice lists of values.

A radio button appears next to each value.

They can be displayed all in one row or one below the other.

Users can select only one value.

List value appearance - Radio button.png
Checkboxes Note: Only for multiple choice lists of values.

A checkbox will be placed next to each value.

They can be displayed all in one row or one below the other.

Users can select several values.

List value appearance - Checkbox.png
Lists Values are displayed in a list.

Users can select several values.

List value appearance - List.png
Drop-down list Note: Only for single choice lists of values.

Values are displayed in a drop-down list.

Users can select only one value.

List value appearance - Dropdown list.png

Screens description

        Form studio.png

(1) Explorer pane: Displays the project variables and elements in the form.

(2) Conception pane: Workspace for designing the form, with a toolbar  at the top of the pane. Open url.png See How to create a form.

(3) Description pane: Pane specific to the element selected in the Conception pane, used to define its contents and layout.

Toolbar

        Conception pane - Toolbar.png

 List of functionalities

  • Used to toggle between read-only mode and edit mode.
  • Used to save the form.
  • Used to add a form element only in an empty cell. Open url.png See the detailed procedure.
  • Used to add a row or column.
  • Used to delete a row or column.
  • Used to show or hide the grid around cells.
  • Used to undo or redo the last modification.
  • Used to change the writing language.

Description pane

The Description pane is specific to the element selected in the Conception pane.

Global form properties

Used to define the structure of the form:

  • Number of rows and columns in the form.
  • Space between each cell. By default, 5 px.
     

Access: Click outside the form in the Conception pane.

      Description Pane - Global properties tab.png

Label properties tab

Note: Only for Label elements

      Description Pane - Label properties tab.png

Tooltip: Text found below the form element, displayed to users.

Best Practice icon.png  Use this field like an input wizard.

Layout: Layout options for the form element.

  • Row span / Column span: Used to merge the cell containing the element with empty adjacent cells.
    • To merge empty adjacent rows, specify the Row span field.
    • To merge empty adjacent columns, specify the Column span field.

example  Row span = 2
Element - Merge cells.png

  • Position: Position of the element, i.e. label and input field if applicable, within the cell. Move the cursor over Help icon.png to see possible positions.
            Element - Position.png
  • Horizontal fill: Used to indicate if the element's width should be adjusted to occupy the entire width of the cell (box is checked) or if its original width should be kept (box is not checked).
  • Vertical fill: Used to indicate if the element's height should be adjusted to occupy the entire height of the cell (box is checked) or if its original height should be kept (box is not checked).

Display tab

Used to configure the display of the form element selected in the Conception pane.

      Description Pane - Display tab.png

Title bar: Label of the form element, displayed to users.

  • The icon next to the title shows the type of element.
  • Translate the label into different languages by selecting the language you want from the drop-down list at the right of the toolbar.

Tooltip: Text found below the form element, displayed to users.

Best Practice icon.png  Use this field like an input wizard.

Layout: Layout options for the form element.

  • Row span / Column span: Used to merge the cell containing the element with empty adjacent cells.
    • To merge empty adjacent rows, specify the Row span field.
    • To merge empty adjacent columns, specify the Column span field.

example  Row span = 2
Element - Merge cells.png

  • Position: Position of the element, i.e. label and input field if applicable, within the cell. Move the cursor over Help icon.png to see possible positions.
            Element - Position.png
  • Horizontal fill: Used to indicate if the element's width should be adjusted to occupy the entire width of the cell (box is checked) or if its original width should be kept (box is not checked).
  • Vertical fill: Used to indicate if the element's height should be adjusted to occupy the entire height of the cell (box is checked) or if its original height should be kept (box is not checked).
     

Selector appearance (Note: Only for Multiple choice list of values and Single choice list of values elements): Display modes available for the list, e.g. action buttons, checkboxes, lists, etc.  Open url.png See Display modes for lists of values.

  • Only for buttons, radio buttons and checkboxes: Select the Horizontal box to display all values in a single row.
     

Label (Note: Except for Label elements): Layout options for the form element's label field.

  • Width:
    • Automatic: The width of the label field will automatically be adjusted to the size of the label.
    • Specific: Specify the desired display width in pixels.
  • Left and On top: Used to indicate if the label field should be positioned to the left or over the element's input field. 
  • Position: Position of the label within the label field. Move the cursor over Help icon.png to see possible positions.
     

Input field (Note: Except for Label elements): Layout options for the form element's input field.

  • Width (Note: Only if the Horizontal fill box in the Layout section is not checked): Display width of the input field.
  • Height (Note: Only for Multiple lines input field elements and only if the Vertical fill box in the Layout section is not checked): Height of the input field.
  • Align within the column (Note: Only if the Left box is selected in the Label section): Used to indicate if the input field should be aligned with the other labels in the column (box is checked) or if its original position should be kept (box is not checked).
     

Rows and columns (Note: Only for Group of fields elements): Used to specify the number of rows and columns for cells in the group of fields.

example  Group of fields with two rows and four columns
Element - Group.png

Type and Validation tab

Note: Except for Group of fields and Label elements):

Used to manage the validation behavior of the form element selected in the Conception pane.

      Description Pane - Type validation tab.png

Input type (Note: Only for Input field, Password field and Multiple lines input field elements): Used to specify the type of input for users when completing the form element, e.g. string of characters, numeric value, etc.

Show empty value (Note: Only for Single choice list of values elements): Used to specify if an empty item should be displayed in the list of values (box is checked) or not (box is not checked). If an empty item is displayed, it will appear at the top of the list.

Best Practice icon.png  Select the box if you do not want to force users to select a value. You can add a comment to explain this choice in the Empty value text field.

Dynamic Field (Note: Only for Input field, Password field, Multiple choice list of values and Single choice list of values elements): Used to specify if the form element is a dynamic field (box is checked) or a static field (box is not checked). If it is dynamic, a computing procedure will run each time the field value changes and the page will be refreshed.

Best Practice icon.png  You can define a dynamic field to refresh the page based on the criteria specified by the user.open url.png See the use case.

Validating (Note: Only for Input field, Password field and Multiple lines input field elements): Options for defining the behavior of the input field.

  • Input is read-only: Users cannot modify the field.
  • Input is required: Users must enter a value.
    • Mandatory fields are indicated by the asterisk ( *). 
    • An error message will appear and users will be prevented from moving on to the next step until the field is completed.

Add validation filter on the field (Note: Only for Input field, Password field and Multiple lines input field elements): Used to add validation conditions for a field in order to force users to respect a data entry format. open url.png See the procedure.

  • You can apply several conditions to a given input field. In this case, all of them must be respected.
  • The list of operators, e.g. equal to, starts with, contains, etc. is defined by EasyVista. You cannot add new ones.
  • You can define a blocking error message when user input does not respect the validation conditions of the filter.

Input/Output tab

Note: Except for Group of fields elements.

Used to manage input and output variables for the form element selected in the Conception pane, and to refresh the lists of values.

Normal mode

Description Pane - Input output tab.png

Default Value

  • For Input field, Password field and Multiple lines input field and Label elements: Value displayed by default for the form element.
    • This may be a text (Simple) or a script (Expression). Simple option: The text will replace the label of the element. Expression option: The script will run when the form is opened.
  • For Multiple choice list of values and Single choice list of values elements: Number of items in the list of values for the form element.

Fixed list values (Note: Only for Multiple choice list of values and Single choice list of values elements): Number of items in the list of values for the form element.

Linked library variable (Note: Except for Label elements): Name of the library variable linked to the form element.

  • A library variable can be created as an input and output variable.
  • You can modify the names of variables in Advanced mode.
  • For List of values elements, this can be:
    • A simple variable for a single choice list of values.
    • A table for a multiple choice list of values.

Advanced Mode

Description Pane - Input output tab - Advanced mode.png

Values of the list (Note: Only for Multiple choice list of values and Single choice list of values elements): Used to specify how items in the list of values are initialized. Open url.png See Best practice.

  • Values of the list (default option): The values are the items added to the list when the element was created (Values of the list option).
    • Click Update list to refresh them. Open url.png See How to specify a list of values.
    • You can export them to the Self Help project library and use them in forms in another project.
  • Project Library: Items in the list are initialized using variables from the Self Help project library.
    • Click  Update to modify the properties of the list of values.
    • Click Update to select another variable from the library.
  • Parameter: Items in the list are initialized using an input parameter.
     

Input value: Used to specify how the input value associated with the form element will be initialized.

  • The value can be a variable from the Self Help project library, a parameter or a free expression linked to a form element (Fixed value).
     

Output value (Note: Except for Label elements): Used to specify how the form element value specified by the user will be stored.

Procedures

See detailed step by step on Self Help portal

How to create a form

Step 1: Select the Self Help project.

1. Select the Self Help project in the tree structure of the Explorer pane.

2. Click Tree expand icon.png to display the tree structure.

Step 2: Create the form.

1. Right-click the folder where you want to create the new form.
         Create new procedure.png

2. Select New > Form from the contextual menu.
The form will be inserted in the Explorer pane. Its name will be <New form>.

3. Rename the form.
The Explorer pane will be refreshed.

Step 3: Initialize the structure of the form.

1. Double-click the form in the Explorer pane.

  • The Conception pane will appear.
  • The first cell in the form will appear.
            First area form.png

2. Specify the number of rows and columns for your form.

  • Click outside the form in the workspace in the Conception pane.
    The Global form properties tab will appear in the Description pane.
  • Specify the format you want.
     The form will be refreshed.
            Enter form structure.png

3. You can add rows and columns individually.

  • Click Add icon.png at the bottom of the form to add a row.
  • Click Add icon.png to the right of the form to add a column.
     

Step 4: Design the form.

1. Click Add element type icon.png inside a cell and select the type of element you want to add from the contextual menu. Open url.png See Types of elements in forms.
        Form - Create new element type.png


2. Specify the element depending on its type, e.g. list of values, input field, etc. and click Finish.

   Open url.png See the detailed procedures.

3. Repeat the procedure to add other cells in the form.

Modify the contents of a cell

  • Click the cell in the Conception pane.
    blue outline will appear.
            Conception Pane - Active field.png
  • Make your changes in the Description pane. Open url.png See the description of properties.
    Note: Warning icon.png Used to indicate that errors were detected, e.g. name not specified, error with a condition, etc. Move the cursor over the icon to display its details in a tooltip.
            Conception Pane - Field with problem.png

4. Edit the layout of the form.

   Open url.png See the advanced procedures.

Step 5: Check that the form is correctly displayed.

1. Insert the form in one of the steps of your procedure.

  • Click and drag the form from the Explorer pane to the relevant step in the Conception pane.
            Insert form into step - Drag and drop.png

2. Check the workability of the form.

  • Click Launch procedure dropdown list.png in the toolbar of the Conception pane. 
  • Select Launch procedure icon.png Launch the procedure.
    • The step will run. 
    • The form will appear in your Web browser.
  • Check that the form works correctly.

Detailed procedures

How to create a form element with input

Input field, Password field and Multiple lines input field elements

Note: The form element is made up of a label and an input field.

Step 1: Create the form element.

1. Right-click an empty cell in the form in the Conception pane.

2. Select Add from the contextual menu and click the type of element you want to add.
The properties window will appear.
        Form - Input area properties.png

3. Enter the label of the input field.
Note: This label will appear when the form is accessed in execute mode, and will be displayed to users.

4. Select the type of input field for the form element, e.g. string of characters, numeric value, etc.
Note: You can modify this subsequently in the Type and Validation tab in the Description pane.

5. Select the Required field box if you want users to complete this field.

Step 2 (optional): Specify input and output parameters for the field.

1. Select the Manual management option if you want to map parameters with existing variables in the project manually.

Note: The default option, From project library, is used to generate parameters in the project library automatically using the title of the field.

example  Other information field ==> Name of parameters: Other_information

Step 3 (optional): Define the layout of the form element.

1. Specify the exact display width, in pixels, of the form element, i.e. label and input field, in the Field size field. 

2. Select the Align label on column size option to align the label of the field with the other labels in the column. 

3. Select the Forced size (text size if empty) option to specify the exact display width of the label.
Note: By default, the display width will automatically be adjusted to the size of the label.

Step 4: Save the form element.

1. Click Finish.

  • The new form element will be inserted in the Conception pane.
    *The Description pane will appear.

Step 5 (optional): Enhance the behavior and layout of the form element.

1. Make the required modifications to the behavior of the form element, e.g. validation filters, type of input, etc. using the properties in the Type and Validation tab in the Description pane.

2. Enhance the layout of the form element using the properties in the Display tab in the Description pane.

   Open url.png See the advanced procedures.

3. Adapt the input and output parameters of the form element using the properties in the Input/Output tab in the Description pane.

How to create a list of values

Multiple choice list of values and Single choice list of values elements

Note: The form element is made up of a label and a list of values.

Step 1: Create the form element.

1. Right-click an empty cell in the form in the Conception pane.

2. Select Add from the contextual menu and click the type of element you want to add.

The properties window will appear.
        Form - Value list properties.png

3. Enter the label of the list of values.
Note: This label will appear when the form is accessed in execute mode, and will be displayed to users.

4. Select the Required field box if you want users to select one or more values from the list.

Step 2 (optional): Specify input and output parameters for the field.

1. Select the Manual management option if you want to map parameters with existing variables in the project manually.

Note: The default option, From project library, is used to generate parameters in the project library automatically using the title of the field.

example  Other information field ==> Name of parameters: Other_information

Step 3: Define the items in the list of values.

Enter items manually

1. Click Create list.
The window for entering values will appear.
        Form - Define value list.png

2. Click Add only Label.

Note: By default, each value is associated with a form variable with the label name.
Click Add Label/Value if you want to name variables manually.

3. Enter the label of the value in the Label column.
Note: The label is the text that users will see in the list. 

4. (optional) Enter the name of the variable associated with the label in the Value column.
Note: This value is not displayed in the list.

5. Repeat the procedure for each item in the list.

6. Click Finish.

Create items using existing project variables

1. Click Add variable.
The list of object variables will appear.

2. Select the project variable to be associated with the item in the list of values.

Step 4 (optional): Define the layout of the form element.

1. Specify the exact display width, in pixels, of the form element, i.e. label and list of values, in the Field size field. 

2. Select the Align label on column size option to align the label of the field with the other labels in the column. 

3. Select the Forced size (text size if empty) option to specify the exact display width of the label.
Note: By default, the display width will automatically be adjusted to the size of the label.
 

Step 5: Save the form element.

1. Click Finish.

  • The new form element will be inserted in the Conception pane.
    *The Description pane will appear.

Step 6 (optional): Enhance the behavior and layout of the form element.

1. Indicate the display mode for the list of values. 

  • Select the Display tab in the Description pane. 
  • (Note: Only for buttons, radio buttons and checkboxes) Select the Horizontal box to display all values in a single row.

2. Make the required modifications to the behavior of the form element, e.g. empty value, or dynamic field, using the properties in the Type and Validation tab in the Description pane.

3. Enhance the layout of the form element using the properties in the Display tab in the Description pane.

   Open url.png See the advanced procedures.

4. Adapt the input and output parameters of the form element using the properties in the Input/Output tab in the Description pane.

Configure the form parameters

Advanced procedures

How to enhance the layout of a form

Merge cells to display a form element

example  Merge two rows to display an input field
Element - Merge cells.png

1. Click the form element in the Conception pane.

2. Select the Display tab in the Description pane.

3. Specify the number of rows and columns occupied by the element in the Layout tab.

4. Enhance the display using the other properties in the section.

  • Select the Horizontal fill box if you want the form element to occupy the entire width of the cell.
  • Select the Vertical fill box if you want the form element to occupy the entire height of the cell.
  • Select the position of the label field as regards the input field.
            Element - Position.png

5. Click Save disk icon.png in the toolbar of the Conception pane to save the form.

Adjust the display of the label field and input field for the form element

1. Click the form element in the Conception pane.

2. Select the Display tab in the Description pane.

3. Adjust the label field using the properties in the Label section.

  • Specify the display width of the label field.

Best Practice icon.png  Select Automatic to adjust the width of the field to the size of the label automatically.

  • Select the position of the label field as regards the input field.

4. Adjust the input field using the properties in the Input field section.

  • Note: (Only if the Horizontal fill box is not checked) Specify the exact display width of the input field.

Best Practice icon.png  Select Align label on column size to ensure that all labels in the list have the same size. (Note: Only if the Left box is selected for displaying the label.)

  • Note: Only for lists of values.
    • Select the display mode for the list of values in the Selector appearance field. Open url.png See the description.
    • (Note: Only for buttons, radio buttons and checkboxes) Select the Horizontal box to display all values in a single row.

5. Click Save disk icon.png in the toolbar of the Conception pane to save the form.

How to add a validation filter

Input field, Password field and Multiple lines input field elements

Step 1: Select the form element.

1. Click the cell containing the form element in the Conception pane.

The properties of the element will appear in the Description pane.

Step 2: Define the validation filter.

1. Select the Type and Validation tab in the Description pane.

2. Click Add icon.png Add validation filter on the field.

3. Define the first filter condition.

  • Select the operator from the drop-down list.
    Note: To define a condition built using a regular expression, select the Regexp operator.
  • Double-click the right column and specify the authorized value.
    Note: Conditions for the Email, Phone and French Postal Code operators are predefined. You cannot enter any value.

4. Repeat the procedure for the other filter conditions.

5. (optional) Type the error message to be displayed when user input does not respect the validation filter conditions.

example  ID input field

  • Regexp operator; Value=[a-zA-Z]{4}[0-9]{4}.  ==> User input must consist of four letters in the upper or lower case, followed by four numbers
  • Error message: Your ID is incorrect.  It must consist of four letters in the upper or lower case, followed by four numbers.

Step 3: Test the validation filter.

1. Click Save disk icon.png in the toolbar of the Conception pane to save the form.

2. Run the procedure that includes the form.

   Open url.png See How to display a form in a procedure step.

3. Enter an incorrect value in the input field where you applied the validation filter.

4. Check that the filter conditions prevent user input and that the error message is displayed.

How to use a form in a procedure

How to display a form in a procedure step

1. Double-click the procedure in the tree structure of the Explorer pane.

The procedure will appear in the Conception pane.

2. Click and drag the form from the Explorer pane to the relevant step in the Conception pane.

        Insert form into step - Drag and drop.png

The form will appear as a resource used by the step.
        Insert form into step - Form as resource.png

3. Run the procedure to test that the form is correctly displayed in the step.

How to use form variables in procedure steps

   Open url.png See the use case.

Note: The steps where form data is used must be defined after the step where the form was inserted.

Step 1: Insert form variables in a step.

1. Double-click the procedure in the tree structure of the Explorer pane.

The procedure will appear in the Conception pane.

2. Click the step that will display form data in the Conception pane.
The content of the step will appear in the Description pane.

3. Insert text in the Content tab of the Description pane.

4. Click and drag the form variable from the Explorer pane to the Content tab, and place it just after the text you previously inserted.
        Insert variable into step - Drag and drop.png

5. Repeat the procedure to add the other form variables.

Step 2: Check that the form is correctly displayed.

1. Run the procedure.

2. Answer the questions in the form.

3. Move through the procedure until the step where the form values are displayed.

4. Check that your answers are correctly displayed.

Use cases

Create a standard form

   Open url.png See the detailed procedure

This use case describes a form that enables users to know if they are eligible for a new smartphone based on their answers. Users must have worked two or more years for the company and be required to travel for business frequently.
         Example - Standard form.png

Create a dynamic form

   Open url.png See the detailed procedure

This use case describes a dynamic form that displays the different logos of EasyVista products on a given page depending on the user's options and to refresh the page based on the user's selected options.
        Example - Dynamic form - Two choices.png

Tags:
Powered by XWiki © EasyVista 2022