Form Building

Overview

Forms are essential to Didge, this is where the users are going to fill up according to their tasks. This will be attached to the Operation or Resource to be used by users when it is active or manually triggered.

When creating a form, you will see the fields at the left side of the screen. Simply drag these fields into the empty space on the right.

The fields are separated by categories:

  • Basic
  • Settings
  • Advanced
  • Layout
  • Data
  • Premium

Basic

This is where all the basic fields are found. It is the commonly used category for making your forms.

These are the following fields:

  • Slider - A slider can be used for measuring data or anything involving numbers. E.g quantity, temperature, etc.
  • Text Field - A Text Field can be used for short and general text input. There are options to define input masks and validations, allowing users to mold information into desired formats.
  • Text Area - A Text Area has the same options as the Text Field form component. The difference is that it will be a multi-line input field that allows for longer text. The Text Area can also be utilized as an ACE, CKEditor or Quill WYSIWYG editor for the end user which is configured within the component settings.
  • Number - Number fields can be used whenever a field should be limited to a type of number value. There are options to set Thousands Separator, set Decimal Places and Require Decimals.
  • Password - The password field has the same options as a text field component. It differs from a text field in that its html <input> type will be a password instead of text. This will cause the field to display asterisks instead of the value entered.
  • Checkbox - A check box can be used for a boolean value input field. It can either be on or off. There are options to set Shortcut and Input Type.
  • Select Boxes -  The Select Boxes allows the user to check multiple values from a list of options.
  • Select - The Select displays a list of values in a dropdown list to users. Users can select one of the values
  • Radio - The Radio allows the user to check only one value from a list of options.
  • Button - Buttons can be added to perform various actions within the form.

Settings

This is the category used for making form settings. It contains this field:

  • Settings Container -  The settings container allows a user to add fields inside of it, to be used in the form settings. Any form field you put here will be reflected in the Form Settings. Which will then apply when you are making an Operation or Resource.

Advance

It includes the following fields:

  • Email - The email component is nearly identical to the text field component. The Email component has a custom validation setting that, if set up correctly, can ensure the value entered is a valid email address. The email component can also more easily be integrated into a form’s email action. Use this component when you want an email address field for your form.
  • Url - The URL component is nearly identical to the text field component. The URL component has a custom validation setting that, if set up correctly, can ensure the value entered is a valid url.
  • Phone Number - The phone number form component can be used to enter phone numbers in a form.
  • Tags - Multiple or single tags can be used to categorize items. Use the tag component when it’s useful for the user.
  • Address - The Address component is a special component that performs an address lookup based on user input using several map and location providers. Address data can also be entered in free form and will save the address as well as geolocation and other information. 
  • Date/ Time - Date/Time form components can be used to input dates, times or both dates and times.
  • Day - The Day component can be used to enter values for the Day, Month, and Year using a number or select type of field.
  • Time - The Time component can be used to input time using different time widgets you would like to use.
  • Currency - The Currency component should be used when a field should display currency amounts on a form. This component holds a numeric input mask that allows two decimal values and automatically adds commas as a user inputs a currency amount.
  • Survey - The Survey component works similar to the radio. Instead of one question, users are able to select a value for multiple questions which are configured within the component settings. Survey is a great component to utilize when asking multiple questions with the same context of answers or values.
  • Signature - A signature field is a special field that allows someone to sign the field with either their finger on a touch enabled device or with the mouse pointer. This signature will be converted into an image and stored with the form submission.

Layout

It includes the following fields:

  • HTML Element - An HTML Element component may be added to a form to display a single HTML Element. This is useful if you wish to quickly insert and configure some HTML in your form. All unsafe HTML is stripped before rendering to prevent cross-site scripting exploits. This includes tags like <script>, <embed>, and <style>, and attributes like onmouseover or onload.
  • Content - A Content component may be added to a form to provide non-field information. For example, if you need instructions at the top of a form that are for display only, use the Content component. The Content component value is not submitted back to the server. A WYSIWYG editor has been provided to help with formatting the content. If you use the HTML view of the editor, note that all unsafe HTML is stripped before rendering to prevent cross-site scripting exploits. This includes tags like <script>, <embed>, and <style>, and attributes like onmouseover or onload
  • Columns - This component can be used for grouping other components, like Text Field, Text Area, Checkbox etc., into configurable columns. It might be useful if you want to display more than one component in one line.
  • Field Set - A Field Set can be used to create a title of an area of the form. This is useful to put inside Layout components or in between lots of related components. The Field Set is for display only and will not be saved to the API.
  • Panel - A Panel is used to wrap groups of fields with a title and styling.
  • Table - A Table component allows creating a Table with columns and rows that allow adding additional components within it.
  • Tabs - This component allows creating tabs for grouping different sets of components. To switch between tabs, there is a navigation bar with tab buttons, each of which opens an appropriate tab with a set group of components. Only one tab at a time displays in a rendered form.
  • Well - Wells are wrapped in a div with a class.

Data

It includes the following fields:

  • Settings Container - The settings container allows a user to add fields inside of it, to be used in the form settings.
  • Hidden - A Hidden component can be added to a form to create a resource property that can be custom set in a form. You can use JavaScript to set the value on the client side and when the form is submitted the value will be set on the resource. There is no front end widget for hidden components. They don't display in the rendered forms.
  • Container - A Container is a wrapper around a set of fields, similar to a Field Set. The major way they are different is the way that the data is stored. For most layout components, field values are stored directly in the data of the submission. For example, a Field Set with the following fields:

firstName = First Name field

lastName = Last Name field

would submit as:

{

data: {

firstName: “Joe”,

lastName: “Smith”

}

}

However, with a Container, the fields are put into an object with the container key. This is useful for creating more complex objects within your form.
For example, a Container with the key user and the same fields above would submit as:

{

data: {

user {

firstName: “Joe”,

lastName: “Smith”

}

}

}

  • Data Map - A Data Map component allows users to create key / value pairs. Both the key and the value fields can get the values while filling out the form. New pairs can be added to the form by the 'Add Another' button, and removed by the 'X' (Remove Row) button. The Data Map with the dataMap key would submit as:

{

data: {

dataMap {

key: "Kuhn - Kshlerin"

key1: "Keebler, Brown and Lind"

key2: "Franecki, Lehner and Prohaska"

}

}

}

  • Data Grid  - Data Grids allow users to add multiple components on to a line item grid. Once placed, users can add multiple components inside the Data Grid. Additionally, any number of grids can be added within a form, which is especially useful when needing the ability to add or duplicate multiple field sets. By default, the grid is empty, but can have other form components placed inside.
  • Edit Grid  - Edit Grids allow users to replicate a table like structure when it comes to the capture and display of form data. Users can add multiple components inside the Edit Grid. Additionally, any number of grids can be added within a form, which is especially useful when needing the ability to add or duplicate multiple field sets. By default, the grid is empty, but can have other form components placed inside.
  • Tree - A Tree component is very similar to the Edit Grid component. It replicates a table like structure when it comes to the capture and display of form data. But, in comparison with the Edit Grid, the Tree component creates a tree-like pattern where users can create a numerous number of data branches. There can only be one top level data entry - a root data entry, which is followed by level 1 data branches, which then are followed by level 2 data branches and so on. By default, the component is empty, but can have other form components placed inside.

General Settings

  • Display

    • Label - The name or title for this component.
    • Hide Label - Hide the label of this component. This setting will display the label in the form builder, but hide the label when the form is rendered.
    • Label Position - Position for the label for this field.
    • Label Width - The width of the label on line in percentages.
    • Label Margin - The width of label margin on line in percentages.
    • Placeholder - The placeholder text that will appear when this field is empty.
    • Description - The Description is text that will appear below the input field.
    • Tooltip - Adds a tooltip icon to the side of this field.
    • Error Label - The label that will display for the field when a validation error message is shown.
    • Input Mask - An input mask helps the user with input by ensuring a predefined format. For a phone number field, the input mask defaults to (999) 999-9999.
      • 9: numeric
      • a: alphabetical
      • *: alphanumeric
    • Allow Multiple masks - This setting will allow you to set multiple input masks for the field. The mask is selected by the user via a dropdown list and will dynamically switch the mask for the field when selected. This feature is only available on our formio.js renderer.
    • Prefix - The text to show before a field. An example is ‘$’ for money
    • Suffix - The text to show after a field. An example would be ‘lbs’ for weight.
    • Custom CSS Class - A custom CSS class to add to this component. You may add multiple class names separated by a space.
    • Tab Index - Sets the tabindex attribute of this component to override the tab order of the form.
    • Multiple Values - If checked, multiple values can be added in this field. The values will appear as an array in the API and an “Add Another” button will be visible on the field allowing the creation of additional fields for this component.
    • Enable Spell Check - This setting will enable spell check on the field.
    • Protected - If checked, this field is for input only. When being queried by the API it will not appear in the properties. You can still see the value on form.io by viewing the form submissions.
    • Persistent - If checked, the field will be stored in the database. If you want a field to not save, uncheck this box. This is useful for fields like password validation that shouldn’t save.
    • Hidden - A hidden field is still a part of the form JSON, but is hidden when viewing the form is rendered.
    • Initial Focus - Make this field the initially focused element of the form when rendered. We recommend configuring this setting only once on your form. If more than one component on the form has the Initial Focus setting checked, only the last component in the JSON structure with the setting enabled will be focused on the form.
    • Hide Input - Hide the input when viewing the form from the front end browser. This does not encrypt on the server. Do not use for passwords.
    • Disabled - Disable this field on the form.
    • Show Label in DataGrid - Show the label of this component when in a datagrid.
    • Table View - If checked, this value will show up in the table view of the submissions list.

  • Data

    • Persistence Mode - Persistence means that the data in the field will stay, or persist. The data is input by the End-User in their submissions. This is not the default data set in the form builder or Form Settings, rather data the user can input and update in their Operation submissions. There are three options here:
      • Default: no data persistence
      • Operation: the data entered by the user persists through Operations. Data persists from one Operation instance to the next, and so on. Updates to the existing data are overridden with the newly entered data, moving forward.
      • Operation Instance: the data entered by the user persists through that Operation only. Data does not persist from one Operation instance to the next. New Operation instances have the data purged from the field.
Note: Persistence Mode in the form builder enables this feature on a field basis. At the Operation Settings, there is a further Persistence with the same options. At the Operation Settings level, the settings apply to the entire Operation, meaning all fields in the Operation at once. This is useful when bulk persistence is needed.
Persistence Mode is very useful for End-Users to make on-the-fly updates to certain Operation data. Rather than creating an entity, or linking a Resources, Persistence Mode provides a highly simplified and agile way to manage user-input default values in Operations.
    • Multiple Values - If checked, multiple values can be added in this field. The values will appear as an array in the API and an “Add Another” button will be visible on the field.
    • Default Value - The Default Value will be the value for this field, before user interaction. Having a default value will override the placeholder text.
    • Persistent - If checked, the field will be stored in the database. If you want a field to not save, uncheck this box. This is useful for fields like password validation that shouldn’t save. Please note this is different and unrelated to Persistence Mode.
    • Input Format - Force the output of this field to be formatted in a specific format.
    • Protected - If checked, this field is for input only. When being queried by the API it will not appear in the properties and also should not appear in exported data. You won’t be able to see the value in the Operation, but it will be stored in the database under the hood.
    • Database Index - Set this field as an index within the database. Increases performance for submission queries.
    • Text Case - When data is entered, you can change the case of the value.
    • Truncate Multiple Spaces - Remove multiple spaces, empty space in the lines beginning, lines end, and delete empty lines
    • Redraw On - Redraw this component if another component changes. This is useful if interpolating parts of the component like the label.
    • Clear Value When Hidden - When a field is hidden, clear the value
    • Custom Default Value - Write JavaScript or JSON to customize the value the field will be defaulted to.
    • Calculated Value - Calculated Values allows form designers to write custom javascript to facilitate calculation of data input between fields on a form.

How do I use Calculated Values?

To apply field calculations, open the component settings and click the Data tab. Scroll down the settings window and click the Calculated Value

    • Calculate Value on server - Checking this will run the calculation on the server. This is useful if you wish to override the values submitted with the calculations performed on the server.
    • Allow Manual Override of Calculated Value - When checked, this will allow the user to manually override the calculated value.

  • Validation

    • Validate On - Determines when this component should trigger front-end validation
    • Required - A required field must be filled in before the form can be submitted
    • Unique - Makes sure the data submitted for this field is unique, and has not been submitted before
    • Minimum Length - The minimum length requirement this field must meet
    • Maximum Length - The maximum length requirement this field must meet
    • Minimum Word Length - The minimum amount of words that can be added to this field
    • Maximum Word Length - The maximum amount of words that can be added to this field
    • Regular Expression Pattern - The regular expression pattern test that the field value must pass before the form can be submitted.
    • Error Label - The label for this field when an error occurs.
    • Custom Error Message - Error message displayed if any error occurred.
    • Custom Validation - Custom Validations allow form designers to write their own custom code to satisfy complex logic validations and rules on a per-field basis within the Validation tab of the component settings.

How do I use Custom Validations?

Open the components settings of the field you want to apply the validation rule to and click the Validation tab

      • Enter custom validation code:

Example:

valid =(input==data.email)?true:'Email must match primary email field';

valid = (input === 'Joe') ? true : 'Your name must be "Joe"';

You must assign the valid variable as either true or an error message if validation fails.

    • Secret Validation - Check this if you wish to perform the validation ONLY on the server side. This keeps your validation logic private and secret.
    • JSONLogic Validation - Use JSON Logic as an alternative to Javascript when writing Advanced Conditions. The same concepts detailed in the Advanced Conditions section still apply. Replace the Javascript variables and operators with JSON Logic.
    • Custom Errors - This allows you to set different custom error messages for different errors (in contrast to “Custom Error Message”, which only allows you to set one error message for all errors). E.g.

{

  "required": "{{ field }} is required. Try again.",

  "maxLength": "{{ field }} is too long. Try again."

}

You can set the following keys (among others):

required

min

max

minLength

maxLength

minWords

maxWords

invalid_email

invalid_date

invalid_day

invalid_regex

mask

pattern

Custom

Depending on the error message some of the following template variables can be used in the script:

{{ field }} is replaced with the label of the field.

{{ min }}

{{ max }}

{{ length }}

{{ pattern }}

{{ minDate }}

{{ maxDate }}

{{ minYear }}

{{ maxYear }}

{{ regex }}

  • API

    • Property Name - Form components directly translate to a resource property on the API that is generated for the form. By default a property name is generated by camel casing the field title. You can change the property name by going to the API tab in the form component settings.
    • Field Tags - Tag the field for use in custom logic or within your application
    • Custom Properties - This allows you to configure any custom properties for this component by setting a ‘Key’ and ‘Value’ for the property.

  • Conditional

    The conditional component requires an API key to be configured to function correctly. Any form component can use conditional logic to determine when to hide or display itself. The settings for a conditional field, are configured on the component itself, and can be found by viewing the Conditional tab within the components settings. The conditional logic is based on the following rules:
      • Each field can hide or display.
      • The visibility is dependent on another component defined within the form.
      • The logic is activated when the configured field contains the plaintext value defined in the settings.

    In addition to Simple Conditional logic, you can also use Advanced Conditional logic, which uses actual JavaScript for any combination of conditions.

    JavaScript conditional logic requires you to set the value of show to either true or false.You have access to the current value of any form component via the data object, and the components API key. Advanced Conditional logic will only work, if Simple Conditional logic isn’t already defined.

      • show = data.showHiddenField == true;
    When using Advanced Conditional logic with the select boxes form component, you must use the following syntax to get the value of the select box, which will always be true or false, depending on if it is checked or not: data.selectbox_component.selectbox_value. 

    • Logic

    To access the Logic feature, open the components settings of the conditional field and click the Logic tab. Click the +Add Logic button to create a new logic instance. Give the Logic instance a name that is easily identifiable in the future.
      • Triggers - Set the Trigger Type to determine how the condition is written and triggered. Configuring the Trigger will depend on what Trigger Type you select. The Trigger Types are listed below:
        • Simple - The Simple Trigger type utilizes the same UI and configuration methods found in the Conditional tab.
        • Javascript - Write your own custom conditionals using Javascript code. The Javascript Trigger type utilizes the same UI and configuration methods used for Advanced Conditionals.
        • JSON Logic - Use JSON Logic as an alternative to Javascript when writing Logic Conditions.
        • Event - Use the Event option when creating your own custom events on your form.
      • Actions - Now that our Trigger is set, add an action that will execute when the condition is triggered. Click the +Add Action button, give the Action a name, and select an action Type. This will dictate what type of action will execute when the condition is triggered. There are four Action Types you can choose from:
        • Property - Conditionally change field settings such as Required, Label, Disabled, and more! Depending on the selected Component Property, configure the Set State to True or False (EX setting a required flag) or input the conditional property Text (EX changing the Label property).
        • Value - Change or populate data values in the conditional field using Javascript. The following variables are available to use in your Javascript code:

    "row", "data", "component", and "result"

        • Merge Component Schema - Not all field settings and configurations are offered with the Property action type. Directly update the field Schema Definition to configure additional settings using Logic conditions, dynamically change labels or value selections, and populate interpolated data from other fields.
        • Custom Action - Execute a custom event workflow. Typically coincides with other fields such as the Hidden Field, Data Source, and Button components.

    • Layout

      • HTML Attributes - you can marginally change the arrangement of the components on your Form within the Layout settings. Each component allows for marginal layout changes from top, bottom, left, and right.

    To change the layout, simply input a margin amount in the Top, Right, Bottom, or Left field. Components will be arranged accordingly depending on what margin field you input to. Set margins must be a valid CSS measurement input like “10px” in order to render properly.

      • PDF Overlay - The settings inside apply only to the PDF forms
        • Style - Custom styles that should be applied to this component when rendered in PDF.
        • Page - The PDF page to place this component.
        • Left - The left margin within a page to place this component.
        • Top - The top margin within a page to place this component.
        • Width - The width of the component (in pixels).
        • Height - The height of the component (in pixels).

     

      Back to Admin Docs