Developer Documentation

Form and Data Dictionary Development processes

Form design and data processes

Form and Data Dictionary Development processes

Form Design

Learn about the Form Components and the settings available within the Form Components.

A Form component collects user data and serves as the display or user interface within the system. Form components define the type of widget that users will enter their data and will automatically add a property to the resource endpoint to interact with the Form component.

Adding a Form Component

To add a form component to a form, drag and drop the component from the left column into the desired location within the form.

Each new form starts with a submit button automatically added to it. This can be removed or edited as necessary.

Drag and drop a component from the left column to any place in the form

Editing a Form Component

To edit a form component on a form, hover over the component and click the gear icon. You will then be presented with a settings form for the component.

Click the Edit (gear) button to edit a form component

The settings for a form component are different for each component type.

General Settings

Below is a list of general settings that are offered for the majority of our components.

Basic Components

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.

Widget: You can change widget. The widget is the display UI used to input the value of the field.

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 ACE, CKEditor or Quill WYSIWYG editor for the end user which is configured within the component settings.

Rows: This allows control over how many rows are visible in the Text Area.

Editor: This option will turn the text area into the WYSIWYG Editor user interface of your choice.

Editor Settings: Here you can modify the code base of the WYSIWYG Editor to customize the UI specific to your needs.

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 password instead of text. This will cause the field to display asterisks instead of the value entered.

Check Box

A check box can be used for 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 list of options.

Values: These are the values that will be selected on this field. The Value column is what will be stored in the database and the Label is what is shown to the users.

Select

The Select displays a list of values in a dropdown list to users. Users can select one of the values.

Values: These are the values that will be selected on this field. You should fill Data Source Values. The Value column is what will be stored in the database and the Label is what is shown to the users.

Raw JSON: Enter a JSON Array into Data Source Raw JSON to use. It should be formatted as an array of objects with named properties.

URL: Enter a url with a data source in JSON Array format. This can be used to populate a Select list with external JSON values. For example, suppose you wish to populate your Select dropdown with a list of all States of the U.S. You can use an external JSON array like the following.

https://cdn.rawgit.com/mshafrir/2646763/raw/states_titlecase.json

Place that in Data Source URL. Then you will need to provide the Value Property as well as change the Item Template so that it will pull the right value as well as display correctly within the dropdown. The following image shows how the configuration would look like for this particular setup.

This will now turn your select dropdown into a list of available States of the U.S.

Value Property: If Raw JSON, URL or Custom is selected as Data Source Type, enter the name of the property for the objects that will contain the value that will be stored in the database. If it is not specified, the item itself will be used.

Search Query Name: If URL or Resourse is selected as Data Source Type, enter the name of the search query parameter to filter requests with. Example, if your url is http://api.dogs.com/dogs, and Search Query Name is set to type, and then user types nice in the Select field, then this component will send a request to http://api.dogs.com/dogs?type=nice and update the Select items with the results. If this option is omitted, no new requests will be made when user enters text in the select field.

Item Template: Use the template field to determine how the values will be displayed in the Select dropdown. You can use the item variable to access the current object in the array. For example, you can embed the value by using {{ item.value }} in a template.

Dynamic Select Filtering

A very common use case that many people have in forms is to dynamically filter a Select dropdown based on the selection of another Select dropdown. The most typical use case is a form that provides the Make, Model and Year of vehicles where when you select the Make dropdown, it filters the Model dropdown for those that are inside that Make. This functionality is covered in detail in our user guide resources section.

Radio

The Radio allows the user to check only one value from list of options.

Button

Buttons can be added to perform various actions within the form.

Action: This is the action that will be performed. Currently there are the next actions that can be performed - Submit, Save in State, Event, Custom, Reset, OAuth and POST to URL.


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.

28 phone number

29 phone vali

Tags

Multiple or single tags can be used to categorize items. Use the tag component when it’s useful for the user.

Address

Important Notice: With recent changes to the Google GeoCode API usage policy, you are now required to provide the Google GeoCode API key along with the configuration for the Address component. Please see the section below on how to setup and configure this within your Google account.

The address form component is a special component that does lookups for addresses entered. It can be entered in free form and will save the address as well as geolocation and other information.

17 address

Google Maps API Key

Due to recent changes to the Google Geocode API usage policies, this is now required for all Address components. To setup an API key, you must follow the following directions.

You will then paste this API key into the place on the Address component modal that says Google Maps API Key.

Required: If checked, the field will be required to have a value.

Date/Time

Date/Time form components can be used to input dates, times or both dates and times.

22 date time

23 date

24 time

26 date time vali

 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.

currency

Resource

A resource field allows users to reference other resources in your project. For example, if you have a Director resource and a Movie resource, you can add a resource field on the Movie to reference the Director.

30 resource

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.

31 signature

Nested Form

Nested Form component allows you to insert one (child) Resource/Form with all its fields into another (parent) Resource/Form.

For example, if you have Song resource (parent) and Artist resource (child) and you want to create both Song and Artist submissions by submitting one form, you may use Nested Form component for this case.

Custom

Custom components allow creating a form field with a custom JSON schema that can be rendered as anything within a frontend application. This is usefully for special or complex form fields that don’t already exist in form.io. Using this type, any kind of field can be created.

To use a custom component, create a JSON definition of the field with the information needed to render it. Create a custom field and paste the JSON object into it. This must be a valid JSON object.

{ "type": "custom", "isNew": true, "key": "custom", "protected": false, "persistent": true }

There are several properties that are required but you may add any additional properties that you would like.

Type

The type property will be used to select which component to render on the frontend. It cannot be an existing field type.

Key

The key field is where the data will be saved to. This must be unique per field. For example, if key = 'customers' then the value of the field will be saved in data.customers.

Persistent

This will determine whether or not the value is saved to the main database. This is useful for using Remote Middleware, verify password fields or sending the data in an action but not saving it.

Protected

This will determine whether or not the field will be visible from the API. If it is a protected field then it will only be writeable but not readable.

Rendering

In order to render the custom component, the frontend application must register the component template. This is done in the config step with the formioComponentsProvider.

app.config(\[ 'formioComponentsProvider', function (formioComponentsProvider) { formioComponentsProvider.register('checkmatrix', { title: 'Check Matrix', template: 'formio/components/check-matrix.html', settings: {} }); } \]);

The template will then be used to render the component. In addition, a controller may be added to the template to create more interactive form elements.

This is a working example of a custom component. It is a Matrix checkbox that changes the number of columns and rows based on two other form fields.

reCAPTCHA

reCAPTCHA component implements reCAPTCHA v3.

Type of event

Event to which this reCAPTCHA component would react

Button Key

API Key of the button for reCAPTCHA component to react to (only for Button Click type of event)

Project Settings

If you want to use reCAPTCHA component on your forms, you need to set reCAPTCHA’s Site Key and Secret Key in your Project Settings on portal:

  1. Go to your project on portal -> Settings -> Integrations -> reCAPTCHA
  2. Specify Site Key and Secret Key with values from your reCAPTCHA Admin panel
  3. Save Settings
  4. As a result your project will have following in its JSON:

"settings": { "recaptcha": { "secretKey": "your_secret_key", "siteKey": "your_site_key" } }

Render from URL

The easiest way to use reCAPTCHA component is to add it to your form using our form builder and render using its URL. In this case you don’t need to do any additional work, just do following:

Formio.createForm(document.getElementById('formio'), 'your_form_url').then(function(form) { // Provide a default submission. form.submission = { data: { } }; });

Render from JSON

If you want to render form from JSON, you’d also need to do following:

  1. Your form should have following settings added to its JSON:

{ "settings": { "recaptcha": { "isEnabled": "true", "siteKey": "your_site_key" } } }

  1. Before rendering form you need to set Project URL to the URL of project where you have your reCAPTCHA Secret Key set in settings:

Formio.setProjectUrl('<your_project_URL'); //for ex. https://examples.form.io/

After above is done you can render the form from JSON:

Formio.createForm(document.getElementById('formio'), 'your_form_json').then(function(form) { // Provide a default submission. form.submission = { data: { } }; });

How it works

When you add reCAPTCHA component to the form, you can specify if it’s going to react on Form Load or on Button Click (for Button Click you’ll also need to specify to which button it should react).

Form Load reCAPTCHA

When your form with Form Load reCAPTCHA emits ‘formLoad’ event, we send verification request to Google for action called ‘&lt;your_form_name&gt;Load’. Google’s responce becomes the submission value of your Form Load reCAPTCHA component:

{ "data": { "reCaptcha": { "success": true, "challenge_ts": "2019-01-11T10:29:39Z", "hostname": "your_domain", "score": 0.9, "action": "&lt;your_form_name&gt;Load" } } }

Button Click reCAPTCHA

When any button is clicked on your form, our renderer searches for Button Click reCAPTCHA component tied to a button with same API Key as clicked one. If renderer finds this reCAPTCHA component, we send verification request to Google for action called '&lt;your_button_key&gt;Click'. Google's responce becomes the submission value of your Button Click reCAPTCHA component:

{ "data": { "reCaptcha": { "success": true, "challenge_ts": "2019-01-11T10:29:39Z", "hostname": "your_domain", "score": 0.9, "action": "&lt;your_button_key&gt;Click" } } }

Example

Please see this example of rendering form with reCAPTCHA component.

Component 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’ the property.

Component Layout Settings

In addition to Layout Components, which are detailed in the next section of this guide, 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.

layout

Conditional Components

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:

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.

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

Calculated Value

Caclulated values allow calculating values based on the values in other fields of the form. Calculated values uses plain javascript and can return any value to the field. There are two variables available to calculate off of, data and row. data is the full data in the form. You can access values within it by using the field keys. For example data.myfieldkey. If you field is within a datagrid, there is an additional variable available of row which contains the values for that row of the datagrid. You can access the values the same as with data as row.myfieldkey. The values are also in data.mydatagrid\[0\].myfieldkey and data.mydatagrid\[1\].myfieldkey plus each additional row as the index.

Also you have access to special util variable - library of useful functions. More information about util library could be find here.

Return the calculated value in the value variable and it will be set. Each time the form values change it will be recalculated. You do NOT need to watch form fields as you do for other custom logic in your form. It will automatically update.

It is very common to disable the field using calculated values.

Form and Data Dictionary Development processes

Form Builder Layout Components

Layout components are used to change the general layout of forms

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.

If you wish to insert more complicated HTML in your form, see the Content component

HTML Element settings

HTML Tag: The name of the HTML tag to display.

CSS Class: The CSS class to add to the HTML Element. You may specify multiple classes by separating them with single spaces.

Attributes: Attributes and their values to add to the HTML Element. This is commonly used to add href attributes to <a> tags, or src attributes to <img> tags.

Content: The text content of the HTML Element. While adding more child HTML tags here will properly display them, it is recommended you use the Content component to easily write and preview more complex HTML.

Refresh on Change: Makes the HTML Element re-renders whenever any value in the form changes. It might be useful when you want the HTML Element to display dynamic data of the other components after they are filled in with values during the form filling. Simply enter{{ data.{componentApiKey} }} into the HTML Element and enable this setting.

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.

Refresh on Change: Makes the Content component re-renders whenever any value in the form changes. It might be useful when you want the Content component to display dynamic data of the other components after they are filled in with values during the form filling. Simply enter{{ data.{componentApiKey} }} into the Content component and enable this setting.

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.

Column Properties: Here you can configure a number of columns that will be displayed in a form and specify the size, width, offset, push and pull settings for each column. When configured, you can easily rearrange the columns using the drag & drop feature without a need to make everything from scratch.

Auto Adjust Columns: If all the nested components inside one of the columns are hidden, all the other columns position will be adjusted.

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.

Legend: A Field Set Legend that will appear for the component in the form.

Panel

A Panel is used to wrap groups of fields with a title and styling. This currently maps to Bootstrap Card - Header and Footer.

Title: A Panel Title that will be displayed at the top of the Panel.Theme: The theming of the Panel. Select one of the options to have the class added to the wrapper div.Collapsible: Turn the Panel into a collapsible Panel. It might be useful if you want to improve usability of the form that has a big number of components, allowing users to hide the fields they don't want to see while they are filling one or another section of the form.Initially Collapsed: The Panel will be collapsed on form load. Applied only when the Collapsible setting is enabled.

Table

A Table component allows creating a Table with columns and rows that allow adding additional components within it.

Number of Rows: Number of rows that will display in the Table.

Number of Columns: Number of columns that will display in the Table.

Clone Row Components: Clones the components that are in a cell of one of the columns to all the other cells of that column. Might be useful if you want to add a lot of Table rows that will have the same content.

Cell Alignment: Horizontal alignment for cells of the Table. Can be Left, Center and Right.

Striped: Adds striped shading to the Table rows.

Bordered: Adds visible borders for the Table.

Hover: Highlights a row on a mouse hover.

Condensed: Condenses the size of the Table, making it takes less space.

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. This currently maps to Bootstrap Navs

Tabs: A data grid that allows adding, configuring, reordering and removing tabs.

Vertical Layout: Makes the navigation bar display in vertical orientation instead of horizontal, configured by default.

Well

Wells are wrapped in a div with a class. These currently map to Bootstrap Cards.


Form and Data Dictionary Development processes

Cliqon requirements

Use the blank_form.json to start a new form.

Enter the table name (if this is a form to create a new table) as the name or key of the Panel

Make sure the field names are added to each field as the name or key for the field

 

Site Design Blocks

Reference guide for site and page design blocks and strings

Site Design Blocks

Design Blocks

// Use this inside an li tag
    function workspaceLink($lcd, $action, $table, $token) {
        $attrs = "
        class='pointer'
        hx-post='/cmsapi/$lcd/$action/'
        hx-target='#workspace' 
        hx-vals='{\"table\": \"$table\", \"token\": \"$token\"}'
        ";
        return $attrs;
    }

 <ul class="links">

       <li @raw( workspaceLink($lcd, 'getdatatable', 'dblinks', $token) )>Useful Links</li>

       <li @raw( workspaceLink($lcd, 'getdatatable', 'dbdocuments', $token) )>Documents</li>    

       <li @raw( workspaceLink($lcd, 'getcalendar', 'dbevents', $token) )>Calendar</li>

       <li @raw( workspaceLink($lcd, 'getgallery', 'dbimages', $token) )>Gallery</li>

</ul>

Notes

Article Link

    // Use this inside an li tag
    function articleLink($lcd, $ref, $token) {
        $attrs = "
        class='pointer'
        hx-post='/cmsapi/$lcd/getdocument/'
        hx-target='#workspace' 
        hx-vals='{\"table\": \"dbdocuments\", \"reference\": \"$ref\", \"token\": \"$token\"}'
        ";
        return $attrs;
    }

<div class="footer-widget">
          <h6>Services</h6>
          <ul class="links">
                  <li @raw( articleLink($lcd, 'ref', $token) )>Web Design</li>
                  <li @raw( articleLink($lcd, 'ref', $token) )>Web Development</li>
                  <li @raw( articleLink($lcd, 'ref', $token) )>Content Management</li>
                  <li @raw( articleLink($lcd, 'ref', $token) )>App Development</li>
            </ul>

</div>

Publishing data

Publish data on the front end website, especially, datatables, datacards, gallery and calendar

Publishing data

Datatables

 

 

Initial data

You can either supply initial data through the options object or by starting with a table that already has data filled in.

If you start out with a table that already contains header cells, you can add these attributes to individual header cells to influence how the corresponding column is treated:

If you start out with a table that already contains data, you can add these attributes to individual cells to influence how the cell is being processed:

Module creation

Allows for the creation and management of new modules for the Application

Module creation

Introduction

General introduction

Creating a new module

Module creation

Preparation

The things to consider and to have to hand before starting

 

Module creation

Menu entries

Administrative menu entries

Start with the menu entries. Example is Accounting module

          # Ledgers
            [[admenu.topleft.content.submenu]]

                label = '9999:Ledgers'
                title = '9999:Ledgers to which all transactions belong'
                icon = 'landmark'
                id = 'ledgers'
                event = 'actionbutton'
                action = 'fetchadminsubpage'
                table = 'dbledger'
                displaytype = 'datatable'
                url = 'getdatatable'
                acl = 70
                submenu = false
                parent = 'content'

            # Transactions
            [[admenu.topleft.content.submenu]]

                label = '9999:Transactions'
                title = '9999:Generates a cash book for a bank account with analysis'
                icon = 'cash-register'
                id = 'transactions'
                event = 'actionbutton'
                action = 'fetchadminsubpage'
                table = 'dbtransaction'
                displaytype = 'cashbook'
                url = 'getcashbook'
                acl = 70
                submenu = false
                parent = 'content'

            # Journals
            [[admenu.topleft.content.submenu]]

                label = '9999:Journals'
                title = '9999:Generates two sided transactions that must balance'
                icon = 'coins'
                id = 'journals'
                event = 'actionbutton'
                action = 'fetchadminsubpage'
                table = 'dbtransaction'
                displaytype = 'datajournal'
                url = 'getdatajournal'
                acl = 70
                submenu = false
                parent = 'content'

Things to note:

We will convert 9999's to real entries in Strings and Translations in due course.

Unique ID for each menu entry is advisable. Icons from Fontawesome. Just significant part of free icon name (no need for fa-). Can the data display and entry be satisfactorily handled by existing admin facility or do wee need to write special routine. If the latter, should this be in ApiExtended or as a Plugin? 

Programming the module

Module creation

Programming the Module