Form Components API Guide

The form can have different components arranged in different layouts. Each control or component can be configured separately and customized.

Managing Form Contols or Components

• Adding Form Component: Drag and drop the component you need anywhere in the form. If you need to add it to a column or other layout, drop it within that component
• Editing Form Component: Hover over the component to display a set of options on the right. Without moving the mouse cursor away from the component, click on the gear icon to edit its properties
• Deleting Form Component: Hover over the component to display a set of options on the right. Without moving the mouse cursor away from the component, click on the delete icon to remove it from the form

Note

In the following documentation the terms Component and Field are used interchangeably to indicate a component that has been added to a form

General Properties

Note: The below properties are available for most components

Property	Description
Label	Enter the label that you want displayed for this component in the form
Label Position	Select the desired label alignment
Placeholder	Enter the placeholder text to be displayed
Description	This is additional help text that can be provided and will always be displayed below the component
Tooltip	The tooltip text will be displayed when a user hovers over the :fa-question-circle: icon next to the label
Custom CSS class	If you need to customize the control, you can add the class name here. The CSS needs to be added in the CSS Settings
Hidden	The component will be hidden and will not be displayed in the form (it will be visible in the designer). Hidden form fields can be used to hold any form data for processing via JavaScript etc
Hide Label	Hides the label
Initial Focus	Sets focus to this component when form is opened
Disabled	Form field will be displayed but cannot be edited
Table View :fa-window-close:	System Field, configuration not required and will be ignored
Modal Edit	Select this if the component should be displayed in a popup for edit. When the user taps on the component they can edit. This is useful for components like Signatures wherein the full mobile screen can be available to sign in a popup panel for example

Preview

Check preview to see how the form component will be rendered. You can also test the Model Edit in the preview. The preview is online (live) and will display immediately with any changes that have been made.

Common Validation Properties

Property	Description
Required	Make the field a required field, form cannot be submitted when empty
Unique	Valid only for Master Data Indicates a key field
Validate On	Select when the validation be done for this field
Error Label	Error label to display when this field validation results in an error
Custom Error Message	Set to a custom error message if required to display
Custom Validation	If the standard validation is insufficient and more complex rules are required, JavaScript code can be added for validating this field
JSONLogic Validation	Execute custom logic using JSONLogic

Common API Properties

Property	Description
Property Name	Unique name (in the current form) to identify this field/component
Field Tags	Add any tag for the field, this can be used to identify the field(s) in custom logic
Custom Properties	Any additional properties can be configured as key-value pairs, typically not requried

Conditional

Any form component can use conditional logic to hide or display it. The component can show or hide iteself based on another component that is part of the form. The condition logic can be based on text values of other components also.

Simple Logic

Property	Description
Display	Set to True to show or False to hide
When the form component	Choose the form component that this component depends on
Has the value	Set the value to check for

Advanced Conditions

When additional conditions need to be checked and the Simple Logic is insufficient, you can enter JavaScript code in the Advanced Conditions field to control the visibility of the component. Visibility is controlled by setting the variable show to true or false via your computations.

JSONLogic

You can also choose to use JSONLogic to execute your rules modelled in JSON

Logic

Any form component can use more flexible and powerful logic to control any property, value or even change multiple properties by working with the component’s schema direclty.

Logic is defined via a Trigger that can run Actions. Each trigger can run one or more actions to control multiple facets of the component itself.

Property	Description
Logic Name	Provide a friendly name to identify the logic’s purpose
Trigger Type	Choose the trigger type from Simple, JavaScript, JSONLogic or an Event that is raised by a Button or other components
Trigger Type: Simple	Choose the other component and the value it should have
Trigger Type: JavaScript	Code a JavaScript snippet to control the trigger
Trigger Type: JSONLogic	Execute custom logic using JSONLogic
Trigger Type: Event	Name of the event (from a button for e.g.) that will act as the trigger
Action Name	Provide a friendly name to identify the action
Action Type	Choose the action type from Property, Value or merging component schema
Action Type: Property	Choose the property that needs to be changed and choose the value to set it to
Action Type: Value	Code a JavaScript snippet to compute the value
Action Type: Merge Schema	Advanced. You can make changes to multiple properties here via JSON definition

Remember to save the Action(s) and Logic

---

Basic Controls / Components

Textfield

Use a Textarea component to accept single line text input

Property	Description
Prefix	Enter the text to show before a field such as currency sign like $. This can also be used to show a font-awesome icon in the control
Suffix	Enter the text to show after a field. This can also be used to show a font-awesome icon in the control
Input Mask	An input mask provides a predefined format for data entry. Use 9: numeric, a: alphabetical and *: alphanumeric
Multiple Values	Allows to enter multiple values for this textfield
Default Value	Default value for the textfield
Show Character Counter	Displays the character count, useful to limit to a fixed number of characters
Allow Spellcheck	Enable spell checker
Show Word Counter	Displays the word count, useful to limit to a fixed number of words
Persistent :fa-window-close:	System Field, configuration not required and will be ignored
Input Format	Sanitize the input to plain text, HTML or raw data
Protected :fa-window-close:	System Field, configuration not required and will be ignored
Database Index :fa-window-close:	System Field, configuration not required and will be ignored
Text Case	Control what case the text is entered in
Encrypted :fa-window-close:	System Field, configuration not required and will be ignored
Redraw On	Choose the component that controls the redraw of this component
Clear Value When Hidden	When a value is hidden, clear it
Custom Default Value	Code a JavaScript snippet to compute the value
Calculated Value	Code a JavaScript snippet to compute the value
Calculate on Server :fa-window-close:	System Field, configuration not required and will be ignored
Allow Manual Override of Calculated Value	Allow user to change the calculated value

Showing a Font Awesome Question icon as a prefix/suffix

<i class='fa fa-question'></i>

Textarea

Use a Textarea component to accept multi line text input

Property	Description
Prefix	Enter the text to show before a field such as currency sign like $. This can also be used to show a font-awesome icon in the control
Suffix	Enter the text to show after a field. This can also be used to show a font-awesome icon in the control
Multiple Values	Allows to enter multiple values for this textarea
Default Value	Default value for the textarea
Show Character Counter	Displays the character count, useful to limit to a fixed number of characters
Allow Spellcheck	Enable spell checker
Show Word Counter	Displays the word count, useful to limit to a fixed number of words
Rows	Number of rows to display
Editor	Type of editor to use for the textarea
Auto expand	Textarea expands automatically as the user types
Persistent :fa-window-close:	System Field, configuration not required and will be ignored
Input Format	Sanitize the input to plain text, HTML or raw data
Protected :fa-window-close:	System Field, configuration not required and will be ignored
Database Index :fa-window-close:	System Field, configuration not required and will be ignored
Text Case	Control what case the text is entered in
Encrypted :fa-window-close:	System Field, configuration not required and will be ignored
Redraw On	Choose the component that controls the redraw of this component
Clear Value When Hidden	When a value is hidden, clear it
Custom Default Value	Code a JavaScript snippet to compute the value
Calculated Value	Code a JavaScript snippet to compute the value
Calculate on Server :fa-window-close:	System Field, configuration not required and will be ignored
Allow Manual Override of Calculated Value	Allow user to change the calculated value

---

Number

Use a Number component to accept numeric input

The properties are similar to those configured for a Textfield

Property	Description
Minimum Value	Minimum value to accept
Maximum Value	Maximum value to accept

---

Password

Use a password component to accept secret inputs. While they are not diaplyed in the UI they are submitted as clear text to the server. Make sure server runs only in https mode to ensure data is secure during transit

The properties are similar to those configured for a Textfield

---

Checkbox

Use a checbox input to accept True/False values or Radio inputs to accept one of many values

Property	Description
Label Width	Width of the label in %
Label Margin	Margin of the label in %
Input Type	Checkbox or Radio
Input Type: Radio	Specify Key / value for label and value
Inline layout	Controls the display of the control and the text

---

Selectboxes

Use a select box input to accept multiple True/False values

Property	Description
Values	Add key/value pairs for each select box

---

Select

Use a select (or dropdown list) to allow user to select one or more inputs from a prefilled list

Property	Description
Data	Select the type of data to display in the list
Data: Values	Enter key/va;ue pairs to display in the select list
Data: URL	This will work only when online. Enter a URl that returns data in the required format
Data: Master data	Check the Master Data help doc
Data: Custom	Code JavaScript logic to compute the values
Data: Raw Json	Enter JSON data directly to be displayed in the list
Enable Static Search	Allow user to search entries
Search threshold	How exact the search needs to be. 0 for exact match and 1 for a loose match
Use exact search	Disabled Search threshold
ChoiceJS options	The ChoiceJS component is used for displaying the list. Additional options from ChoiceJS can be configured here

---

Radio

Use a radio input to accept one of many values

The properties are similar to those configured for a Checkbox where Input Type is set to Radio

---

Button

Add a button to perform a certain action when the user clicks on it

Property	Description
Action	Choose from Submit, Smart Data Component, Event, Custom or Reset (other options are for future use)
Action: Submit	Do not set to this. The form already has a Submit action button added automatically by the designer
Action: Smart Data Component	Check the Smart Data Component docs
Action: Event	Raise a custom event for other logic to run
Action: Custom	Code a JavaScript snippet to execute on button click
Action: Reset	Resets the form
Theme	Type of button to display
Left Icon	Enter the Font Awesome icon to display on the left side such as fa-question
Right Icon	Enter the Font Awesome icon to display on the right side such as fa-question
Disable on form invalid	Disables the button when there are any validation errors in the form. Missing required fields is a good example of a validation error

---

Advanced Components

Email

Use an Eamil component to accept a format validated email

The properties are similar to those configured for a Textfield

---

Url

Use a URL component to accept a format validated URL

The properties are similar to those configured for a Textfield

---

Phone Number

Use a Phone number component to accept a format validated phone number

The properties are similar to those configured for a Textfield

---

Tags

Use a Tags component to accept multiple tags in the form

The properties are similar to those configured for a Textfield

Property	Description
Delimiter	Choose the delimiter between tags

---

Address

Use an Address component to accept an address and validate it

The properties are similar to those configured for a Textfield

The Provider tab allows you to configure the provider for validation

---

Datetime

Use a Datetime component to accept a Date and Time from the user

The properties are similar to those configured for a Textfield

Property	Description
Display in timezone	Choose from viewer, UTC etc
Use Locale	Use locale settings to display date and time
Allow Manual Input	Allow user to enter date/time manually
Format	Date/Time format

In addition the Date and Time tabs control the date and time configuration individually

---

Day

Use a Day component to accept a day/month/year in the form

The properties are similar to those configured for a Datetime

In addition the Day, Month and Year tabs control the configuration individually

---

Time

Use a Time component to accept a time in the form

The properties are similar to those configured for a Datetime

---

Currency

Use a Curreny component to accept a currency value in the form

The properties are similar to those configured for a Number

---

Survey

Use a Survey component to include a Survey of questions in the form

Property	Description
Questions	Add the question text and the value to submit
Values	Add as many responses as needed for each question. For e.g. in a custmer satisfaction survey it could Be Excellent, Satisfactory, Needs Improvement

---

Signature

Use a Signature component to enable users to add a digital signature to the form. Users can either draw their signature on mobile (with a mouse on desktop) or simply Click to Sign their name. Signatures are embedded directly into the form and rendered as is in PDFs and also while printing.

Property	Description
Width	Width of the signing panel in pixels or %
Height	Height of the signing panel in pixels or %
Background Color	Background color (rgb or short codes like black) of the signing panel
Pen Color	Pen color (rgb or short codes like black) for the signing panel

---

Layout

HTML Element

HTML elements allow to add HTML snippets directly to the form. You can include any valid HTML

Property	Description
HTML Tag	The tag for this HTML element, default
CSS Class	Optional Bootstrap class
Attributes	Add Attribute/Value pairs that are valid for the chosen HTML Tag
Content	The actual HTML content to include
Custom CSS Class	Custom CSS class if any. Custom CSS needs to be added in the CSS Settings

---

Content

Content allows to add any text to the form. This could be notes for the user or any help text etc. This data is not submitted to the server when the form is completed. Enter the data to be displayed in the editor and format as required.

No additional configuration required.

---

Columns

Add a columns layout to the form to design a responsive form. The maximum width is 12 and you can add as many columns as needed to make up that total. For e.g. 2 columns of 6 width or 3 columns of 4 width etc. Also columns help to design responsive elements in the form. For e.g. on a mobile form the screen would adjust to 1 column width automatically to show all elements vertically.

Property	Description
Column Properties	Number of columns
Auto adjust columns	Adjust based on content
Hide column when children hidden	Hides the column if the child components within are hidden. Useful to hide an entire column and save space on screen

Add Components

Once the column layout is added to the form, drag and drop other components into the columns.

---

Fieldset

A fieldset can be used to create a title area as part of the form. This can be placed inside other Layout components or in between lots of data fields. Other components can be added into this layout. The data from the fieldset is directly submitted as part of the form and not under a separate key.

Property	Description
Legend	The Legend appears prominently at the top of the Fieldset layout

---

Panels

Panels can be used to create collapsible sections as part of the form. Other components can be added into the panel layout.

Property	Description
Collapse	Allow panel to be collapsed or not
Initially Collapsed	Panel displays collapsed when form opens

---

Table

A table can be used to create a tabular section as part of the form. Other components can be added into the cells of the table. For web view this is suitable but Tables are not responsive and its recommended instead to use a Column layout

Property	Description
Rows	Number of rows
Columns	Number of columns
Clone Row Components	If checked, the components from the first row are copied to all the other rows
Cell Alignment	Choose the desired alignment
Striped	Table styling with stripes
Bordered	Table styling with border
Hover	Highlight a row on hover
Condensed	Condensed table

---

Tabs

Tabs layout can be used to create a set of Tabs as part of the form. Other components can be added into the individual tabs. Use tabs when a lot of data has to be entered and the form should not have a “busy” view.

Property	Description
Tabs	Add the Tab name and the key

---

Well

A Well is a Bootstrap well that can be added to the form for a simple layout container. Add components into the well to group them together.

No additional configuration required.

---

Hidden

A Hidden component is not displayed. It can be used to compute a value using JavaScript and the computed value will be submitted to the server. The value will not be displayed in the client.

No additional configuration required.

---

Container

A Container is similar to a Fieldset that can be added to the form for a simple layout container. Add components into the well to group them together. The only difference is that the submitted data is grouped under the Container API key.

No additional configuration required.

---

Datamap

Data Map allows to collect a variable number of key / value pairs of data

Property	Description
Label for Key column	Label to display
Disable Adding/Removing rows	If set, the Add and Delete button are hidden. Useful to collect a fixed number of rows of data
Show Key Column before value	Displays key column and then value column

---

Datagrid

Data Grids allow users to add multiple components on to a line item grid. Add multiple components as required inside of the Data Grid. Datagrids have the flexibility to collect a variable number of rows while filling in data and is best suited for data sets like order items, inspection observations etc.

Any number of grids can be added within a form which is especially useful when needing the ability to add or duplicate multiple fields sets.

Property	Description
Disable Adding/Removing rows	If set, the Add and Delete button are hidden. Useful to collect a fixed number of rows of data
Allow Reorder	Move rows up and down to change their order
Conditional Add Button	Determine with JavaScript when the Add button is displayed
Add Another Text	Text to display to add another
Add Another Position	Choose where to display the button
Default Open Row	Displays open rows
Equal Column Width	Equal column width
Enable Row Groups	Choose if rows need to be grouped together
Initialize Empty	Start empty
Minimum Length	Minimum number of rows
Maximum Length	Maximum number of rows

---

Editgrid

Edit Grids allow users to add multiple components on to a line item grid. Add multiple components as required inside of the Edit Grid. Editgrids have the flexibility to collect a variable number of rows while filling in data. The grid as such displays data read only and provides an edit icon to edit all the data.

Property	Description
Disable Adding/Removing rows	If set, the Add and Delete button are hidden. Useful to collect a fixed number of rows of data
Open First row when Empty	Open row when empty
Templates	Header and Row templates can be customized and defined based on the example
Add Another Text	Text to display to add another

---

Tree

Similar to other grid layouts which hold other controls

---

Turbo Premium

SmartID

SmartID can be used in a form to generate a unique ID for each form when it is created. The template for the ID can be configured flexibly. Counter should mandatorily be part of the ID template.

Property	Description
Pattern	Create custom numbers by specifying a pattern. Available variables: ${counter} - Number, ${day} - 01 to 31, ${month} - 01 to 12, ${year} - 2021. For example, ${year} - ${counter} would be converted to 2021-00001 if zero prefix is true
Start Counter	The number to start generating from

One ID Per Form

Remember to add only one SmartID per form

---

Barcode

Many Forms like Inventory count etc. require Barcode scanning functionality. Any Barcode can be scanned and the scanned text copied to a text field.

The properties are similar to those configured for a Textfield

Property	Description
Update Value to Scanned Barcode	Set the barcode text scanned to the textfield
Trigger Smart Data Component	Raises an event to the selected Smart Data Component so that the SDC can download the requried data. Check the Smart Data Component docs

---

SelectBarcode

Barcode scanning functionality can also be attached to a Select (dropdown) field. Use a Select Barcode component to enable scanning in a select choice (dropdown) list. The scanned text is used to automatically select the correct item in the list. This is useful when scanning equipment for e.g. and selecting associated details automatically.

The properties are similar to those configured for a Select

---

SmartData

Use a Smart Data Component (also referred to as SDC) when data needs to be fetched online from a . This allows you to online fetch data from backend systems using Flows and updating the form.

Property	Description
Before Execute	Section determines actions to take before SDC is executed. This can be used to initialize or perform some computations before the execution
Execute	Section determines action that triggers the SDC to execute
Trigger on Form Load	Run the flow when the form is initialized when opened (run once)
Trigger On Component Action	Triggered by another form component such as Barcode Select and Button Event
Trigger on Data Change	Trigger when the data in the selected component changes
After Execute	Section determines actions to take after SDC is run and data fetched. This can be used to chain flows in the form and update other fields or initiate other SDC after this has run
Fire Event	Name of event that must be fired after the SDC has run
JavaScript	Custom JavaScript code snippet that needs to be executed after the SDC has run
Datasource Type	Select from Flow or URL and provide additional details

Pro Tip

Creating a form and assigning a Smart Data Component to it is a 2 Step Process

- Create form without the SDC but add all the other remaining fields
- Create the SDC Flow using the form
- Return to the design view of the form
- Add a new SDC component
- Associate the newly created Flow to the SDC

---

SmartTable

Use a Smart Table component to show data in a responsive tabular form. Also displays nested data. Typical use cases include running an SDC and populating data in the Smart Table based on user input like get list of Approvals to approve etc.

Note: The powerful Tabulator control is used for this purpose. For additional information check the Tabulator docs.

Property	Description
Columns Layout Mode	Choose the display mode for columns
Responsive Columns Layout	Choose the desired layout
Column Grouping	If columns are grouped, the required alignment
Frozen Columns	Freeze the first column from scrolling
Filter Header	Allow filtering each column
Movable Rows	Allow moving rows to change order
Multiselect	Allow multiselect of table rows
Add action button to each row	Adds an icon button to click and perform any action
Column Selection Menu	Allows to show or hide columns
Columns	Configure the columns to display
Column Header	Label to display, value identifies data field to display, Allow edit or not.
Set Item Headers	Add this configuration if you have a nested item table to display

Enabling Column Groups

To enable column groups, enter the group name and column name separated by a comma in the header field. For e.g, Name, First Name, Last Name will have one grouped column Name with two separate columns First Name and Last Name. And in value field enter fname,lname to associate the data field fName with First Name and lName with Last Name. Note that there are 3 entries in the label and only 2 in the value since the first label is the Group label.

---

File

Use a File component to attach files, pictures from camera etc to the form.

Property	Description
Storage	Choose Smart Storage for the most optimized storage, or BASE64
Display as Images	Thumbnails will be displayed
Upload only	Use to only upload files
Enable Web Camera	Enable capturing images via camera
Change Default Compression	Achieve better transmission speeds and optimizations by enabling this and setting the desired compression size and maximum Height or Width. The compressor will choose the most appropriate settings between them to performa lossless compression
File Types	Add the list of file types that can be attached
File Minimum Size	File Minimum Size
File Maximum Size	File Maximum Size

Annotations

Once the image is captured in the form, a powerful cropper and annotator are made available by default to markup the image for further details

---

SmartNestedForm

Use to nest another form within this form. This allows to reuse Nested Forms across forms and also to propagate changes to nested forms to all forms by maintaining once.

Property	Description
Form	Choose the nested form
Form Version	The current nested form version and comment is displayed
Form Update	The new nested form version and comment if any is displayed and allows to update

Updates to Nested Form

When a nested form is changed and published, it does not automatically updated in all forms where it is used. You can either update it individually from within the form or Update all by going to the detail view of the Nested Form.

^{_{Note: The builder embedded is based on some additional opensource components (Apache licensed) from formio and other OSS repos. These have been enhanced and customized by Unvired for Enterprise usage within the Turbo Apps and Forms products.}}