Premium Components
Learn more about Premium Components below
Form.io provides access to private modules that contain premium components and themes for enterprise plans. In order to use them, you will need to be granted access and use the pkg.form.io registry to install the modules.
- 1.Ensure you have a form.io user account. Contact [email protected] and request access to private modules.
- 2.Go to https://pkg.form.io and log in with the username and password of your form.io account. Please note that this is the USERNAME and not email address of your account in form.io. You can access your username by logging into portal and going to your account information at the top right. If you are able to log in to https://pkg.form.io then you have been granted access and are using the correct username and password.
- 3.From within your project, log in to the package registry by running the following command:npm adduser --registry https://pkg.form.ioEnter the same username and password from step 2.
- 4.Find the package you want to install in your app. Premium is a very common one. To install it, from the command line in your app.npm install @formio/premium --registry https://pkg.form.ioThis will install the package within your application.
- 5.To use it, in the main file of your app, Formio.use() the package. Depending on your language, do something like the following. (With react or vue, import Formio from react-formio or vue-formio instead of formiojs).import { Formio } from 'formiojs';import premium from '@formio/premium';Formio.use(premium);
- 6.Render forms as usual. Premium components will now be installed in your app.
A Dynamic Wizard allows you to collect an array of object values and then saved data is output to a table view as new rows are added. Filling an array element (field) occurs in steps, where each component inside the Dynamic Wizard is a separate step.
The principle of operation is based on the behavior of the Wizard. However, when you click the next step button, the current page of the Wizard remains the same until you have progressed through all of the fields within the Dynamic Wizard. The table view of the filled data appears with the successful passage of the last step, or when you click on the cancel button.
How do I use the Dynamic Wizard?
To create a Dynamic Wizard flow, the form must first be in Wizard mode in order to make the component available within the form builder. The Dynamic Wizard will initially be empty when it is added to the form, however, other components are added to create the Dynamic Wizard flow. Use Layout components to change the formatting and field layout of the wizard flow.
The Dynamic Wizard is only available when the Form is displayed in Wizard format. This component does not work inside regular Webforms or PDF First forms.
The Dynamic Wizard component will display in the Premium component grouping when form is in Wizard mode
Below is an example of a user building a form with a Dynamic Wizard containing a First Name and Last Name field which will display each field individually. A Field Set containing a group of fields will display as a set in the flow as opposed to displaying individually like the First and Last Name fields.
Building out the Dynamic Wizard
When the form is rendered and the user is filling out the form, the wizard will present each component followed by the next based on the order they were placed inside the Dynamic Wizard. Users will enter data into the first field and press the Next button to proceed to the next step.
Press the Previous button to review or modify data entered into previous fields.
Below is the same form shown in the previous screenshot rendered and being filled out by a user. We can see the First Name is displayed first based on the field order inside the Dynamic Wizard.
Rendered Dynamic Wizard - Step #1
The user clicks the Next button to progress to the Last Name field which is the 2nd component inside the Dynamic Wizard.
Rendered Dynamic Wizard - #2
In the final step, we can see the Field Set component Contact Information rendered which contains a set of fields.
Rendered Dynamic Wizard - Step #3
After completing the final step within the Dynamic Wizard, the table view of the entry displays a summary of the entered data.
If you want to modify the saved data entry, press the 'Edit Row' button next to the appropriate entry. The Dynamic Wizard entry will open displaying the fields where data can be modified.
If you want to remove a certain data entry, click the 'Remove Row' button. Clicking the Add Another button will create a new Dynamic Wizard entry and the user will progress through the previous steps finalizing the entry with the table view of all entries.
The Table View formatting, including buttons, can be customized using the Header, Row, and Footer templates found within the Dynamic Wizard settings.
Unique Settings
Guidance
JSON
Header, Row, and Footer Templates: Flexibility to customize the grid using basic JavaScript. Within the Template section of the component settings, the user can modify what type of components are displayed within the grid row along with the header/footer.
Row CSS Class: Add a CSS Class to the row wrapper.
Enable Row Drafts: Save rows bypassing any field validation within the Dynamic Wizard. Normal validation will execute when the form is submitted.
- The Dynamic Wizard is only available when the Form is displayed in Wizard format. This component does not work inside regular Webforms or PDF First forms.
- Only one Dynamic Wizard can be placed on a Wizard page. In order to add another one, add a new Wizard page and place the Dynamic Wizard in there.
- Dynamic Wizards can not be nested inside other Dynamic Wizards
{
"label": "Dynamic Wizard",
"tableView": false,
"rowDrafts": false,
"key": "dynamicWizard",
"type": "dynamicWizard",
"input": true,
"components": []
}
What is the Data Source?
The Data Source component is a hidden form component that is typically used to fetch data from an external source using an API endpoint. This component will not be visible to the end user but the stored data can be used for various reasons and use cases such as custom validation, calculation, data outputs, and more.
How do I use the Data Source?
To use the Data Source, start by dragging and dropping the field from the Premium component grouping in the Form Builder. Although the component is hidden when rendered, the field will be visible when editing the form.
The first setting you need to configure is the Fetch URL which will be the source of data the component will retain. Inherently, the Data Source will not do anything to the retained data, however, other fields and variables on the form can use the data to perform certain functions like field or application logic.
Below shows an example of the Data Source being used to fetch Data from an external URL and using the Trigger to execute business logic on the form.
Example Using External API URL
In this example, we are going to be fetching data from an external API URL hosting JSON containing a list of USA states. We are then going to use a checkbox on our form to trigger a Data Source event. That triggered event will then execute calculated logic to output the fetched data to fields inside a Data Grid.
Start off by adding the Data Source component to the builder. Within the settings, click the Fetch tab and add the following to the URL field:
https://cdn.rawgit.com/mshafrir/2646763/raw/states_titlecase.json
Data Source Fetch Settings
Next, let's add our trigger component to the form. Add a Checkbox and name the component 'Populate'. Open the Data Source settings and click the Trigger tab. Click the Trigger on data change dropdown and select the 'Populate' checkbox from the form. This component will act as the Trigger to execute the event. Next, add the following for the Triggered Event which will be the event sent to the Form when the Trigger component is checked:
populateState
Data Source Trigger Settings
For our final step, we need to add the fields that will host the data population and configure Logic for those fields to execute when the Data Source event has been received.
First, let's add a Data Grid to the form. Because we are going to fetch data with many entries we need the Data Grid to ensure we have the necessary rows to populate the states. Add two text fields called Name and Abbreviation. Ensure the Property Name for the fields matches the JSON values from the Fetch step.
Now that we have our fields in place, we need to add logic to the Data Grid to populate the data from our Data Source to the fields inside the grid. Edit the Data Grid settings and click the Logic Tab. Set the Trigger Type to Event and add the Event Name: 'populateState' to match our Data Source event. Set the Action Type to Value and add the following to the JavaScript content:
value = data.dataSource;
Please note, the property name reference inside the Javascript should match the Data Source property name.
You should have a form looking something like this:
Data Source Form Using The Form Builder
The only thing left to do is test our form. When the Populate checkbox is ticked, the Data Source is triggered to fetch the Data and fire off an event. Our Data Grid contains logic that is listening for the event and will populate the Data being stored from the Data Source to our Name and Abbreviation fields inside the Data Grid. Because our Name and Abbreviation field's property name matches the names inside the JSON URL, the data population will calculate the fields seamlessly.
Unique Settings
Guidance
Examples
JSON
The Trigger Settings will determine how and when the external data will be stored in the Data Source component.
Trigger on Form Init: Loads data once the form is rendered and ready for use.
Trigger on Server: Loads data on the server during validation.
Trigger on Data Change: Specifies a component the value change of which will have the data stored in the Data Source component be refreshed. A new request will be sent again.
Trigger on Blur of Component: Specifies a component on which blur, data stored in the Data Source component should be refreshed. A new request will be sent again.
Trigger on Event: Specifies the name of the event on which data stored in the Data Source component should be refreshed. A new request will be sent again.
Triggered Event: If specified, an event with the specified name will be triggered once the data load was triggered.
The Fetch Settings determine the source and the method for retrieving the External Data
Data Source Type: Specifies a source type from which data will be fetched. Available options: URL, IndexedDB.
Settings when URL Settings
Data Source URL: The API endpoint to which a request is made to retrieve data.
Method: The method to be used when making a request to the specified endpoint. Available options: GET, POST.
Request Headers: HTTP request headers to be used when making a request to the specified endpoint.
Forward Headers: Forwards the headers passed to the server to the fetch endpoint.
Form.io Authentication: Passes Form.io Authentication headers with the request.
Enable To Store Request Result in the Cache: If checked, the result of each API call to the specified endpoint will be cached. That means, if the Data Source refresh is triggered again with the same URL, it won't make a real request to that URL, but rather take the result of the previous request with the same URL from the cache.
Uncheck this setting, if the returned data from the URL updates frequently and should be kept up-to-date.
Settings when IndexedDB is selected
Choose From Existing Databases?: Allows selecting an existing database.
Database Name: The name of the indexedDB database.
Table Name: The name of a table in the indexedDB database.
Existing Database Name: The name of the existing indexedDB database.
Existing Table Name: The name of an existing table in the indexedDB database.
Use Cases:
- Perform custom validation based on external data
- Use the Data Source with other components like text fields, to display external information to the form user.
- Save external data in the submission for future use or calculations (e.g. currency exchange rate at the moment of submission)
Populating Data From An External URL
The following examples connect the DataSource component to an API URL listing the USA States. Use the Embed URLs to copy these example forms into your project.
- Show State by the entered abbreviation using Data Source
- Show States Abbreviations Cheat Sheet using Data Source Form Embed URL: https://gtbvdrunldplvre.form.io/datasourceexample2
{
"label": "Data Source",
"persistent": "client-only",
"trigger": {
"init": false,
"server": false
},
"refreshOn": "populate",
"event": "fetchMe",
"dataSrc": "url",
"fetch": {
"url": "https://myurl.json",
"method": "get",
"headers": [
{
"key": "",
"value": ""
}
],
"mapFunction": "",
"forwardHeaders": false,
"authenticate": false
},
"allowCaching": true,
"key": "dataSource",
"type": "datasource",
"input": true,
"tableView": false
}
What is the reCaptcha component?
Form.io is a hidden component that utilizes Google's reCAPTCHA v3. This reCaptcha version returns a score for each request without user friction. The score is based on interactions on your form and can help determine if the score represents a human or malicious interaction.
How do I Use The reCaptcha Component?
To use this component, you must first setup a reCaptcha within the Google Developer portal. Once setup, ensure you copy the reCaptcha's Site Key and Secret key within your project.
- 1.Go to your project on portal > Settings > Integration > Google reCAPTCHA
- 2.
- 3.Save the Settings
As a result, your project will contain the following JSON:
"settings": {
"recaptcha": {
"secretKey": "your_secret_key",
"siteKey": "your_site_key"
}
}
Once the integration is complete add a reCaptcha to a form. The component is hidden on the rendered form but will be visible within the Form Builder. Open the component settings and choose whether you want the reCaptcha to execute when the Form Loads or Trigger on button click.
When the reCaptcha is executed and the form is submitted, the reCaptcha results can be found in the metadata of the submission.
Render From JSON
If you want to render form from JSON, you’d also need to do following:
- 1.Add the following settings to the Form JSON:{"settings": {"recaptcha": {"isEnabled": "true","siteKey": "your_site_key"}}}
- 2.Before the form is rendered, set the Project URL to the URL of project you have your reCAPTCHA Secret Key set:Formio.setProjectUrl('<your_project_URL'); //for ex. https://examples.form.io/
You can now render the form using JSON:
Formio.createForm(document.getElementById('formio'), 'your_form_json').then(function(form) {
// Provide a default submission.
form.submission = {
data: {
}
};
});
Unique Settings
Guidance
JSON
Type of Event: Sets the type of event to which the reCAPTCHA component would react to: Button Key, Form Load
Button Key: API Key of the button for the reCAPTCHA component to react to (only for 'Button Click' type of event).
Trigger on Form Load
When your form with Form Load reCAPTCHA emits ‘formLoad’ event, a verification request is sent to Google for action called ‘<your_form_name>Load’. Google’s response 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": "<your_form_name>Load"
}
}
}
Trigger on Button Click
When any button is clicked on your form, our renderer searches for Button Click reCAPTCHA component tied to a button with the same API Key as clicked one. If the renderer finds this reCAPTCHA component, a verification request is sent to Google for action called '<your_button_key>Click'. Google's response 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": "<your_button_key>Click"
}
}
}
Use the reCaptcha component to protect your forms from bot spamming and malicious activity.
{
"key": "recaptcha",
"type": "recaptcha",
"input": true,
"tableView": false,
"label": "reCAPTCHA"
}
The Resource component has been deprecated. Use the Select with the Data Source Type set to "Resource" instead which is a more robust and flexible way to reference resource data.
What is the File component?
A File component allows users to upload and download files to a form. In order to use the File component, file storage must be set up. This can be done from the project settings. See File Storage for the types of providers supported.
How do I use the File component?
Form.io does not host any uploaded files on forms. Instead, files are stored with the Storage Provider selected for the component which allows uploading and downloading files to and from it. Form.io does store a reference to the files which allows uploading and downloading files to and from the provider and seamless integration into your app.
Before a provider can be selected for the component, the provider must first be integrated into the Form.io project. Navigate to the following documentation on File Storage setup.
Once a storage provider has been set up, you can then select that provider within the File component Provider settings. Additional settings such as file display, enabling webcam for mobile devices, and file type validations can be set.
Unique Settings
Field Examples
Guidance
JSON
The storage providers which the file will be stored and accessed from. Select the appropriate provider. All providers excluding URL and IndexedDB require integration configurations setup inside the project settings.
S3: file storage and retrieval using any S3 compatible service, specifically designed for Amazon Web Services S3
URL: Setup your own or use an existing service that can upload and serve files. For more information on how to set up the server, follow the link
Private Download: Makes the file download send a POST request to the download URL with the x-jwt-token header. This will allow your endpoint to create a Private download system.
Custom Request Options: Allows passing the custom xhr options.
File Form-Data Key: Key name that you would like to modify for the file while calling API request.
IndexedDB - Upload your files to a predefined IndexDB API
Database: The name of the indexedDB database.
Table: The name of a table in the indexedDB database.
Base64 - Files are locally stored in your browser. This provider should only be used for testing purposes.
CSV - INFO COMING SOON.
Directory: This field will append all files with the string so that they are in a directory on the storage provider. Must end in “/”.
File Name Template: Allows specifying a template for the name of the uploaded file(s). Regular template variables are available (
data, component, user, value, moment etc.), also fileName, guid variables are available. Theguid part must be present and will be added automatically if not found in the template. Upload Only: Allows only to upload file(s) and consequently the download, in this component, will be unavailable.
Display As Image(s): Instead of a list of linked files, images will be rendered in the view.
Image Size: The image size in pixels for previewing images.
Enable Web Camera: Allows using an attached camera to directly take a picture instead of uploading an existing file.
Webcam Width: The webcam size in pixels for taking pictures.
File Types: Allows specifying file types to classify the uploads. This is useful if you allow multiple types of uploads but want to allow the user to specify which type of file each is.
File Pattern: Dictates which file extensions will be allowed to upload. Files not specified in this field will be prevented from being uploaded.
File Minimum/Maximum Size: Allows setting a minimum/maximum file size for uploaded files.
File Maximum Size: Allows setting a maximum file size for uploaded files.
{
"label": "Upload",
"tableView": false,
"storage": "",
"webcam": false,
"fileTypes": [
{
"label": "",
"value": ""
}
],
"key": "file",
"type": "file",
"input": true,
"options": {}
}
Property | Description | Value | Required | Default |
|---|---|---|---|---|
image | If this file component should be used for managing images | boolean | false | false |
imageSize | If this file component is configured as an image upload, then the size of images that are shown when uploaded. | string | false | 200 |
What is a Nested Form?
The Nested Form component allows you to insert an existing Form or Resource (child form) into another Form or Resource (parent form). All fields contained within the child form, including all field settings, will display accordingly, in the Parent form.
How do I use a Nested Form?
Nested Forms are easy to use. Simply drag and drop the Nested Form component onto your Parent Form and select a Form a Resource from your Project. The Nested Form will display as an empty component in the builder but will display the Child form fully when rendered.
In the following example, I want to utilize a form and its set of fields multiple times throughout my project. Instead of recreating the same form with the same fields and settings, create a single form called Contact Information.
Contact Information Form
Next, let's add this form to one of the existing forms inside the project. The screenshot below shows a Parent 'Application' form. Instead of adding individual fields, we are going to use the Nested Form component to pull in our Contact Information form.
Add aNested Form component, click the Form tab and select the Contact Information from the Form dropdown.
When the form is rendered, not only do we see the two fields from the Parent form but also the fields included in our Nested form. All settings and configurations for the Nested Form fields are retained
After submitting the form, the Submission Data will merge the Child and Parent data together. Child data will still save to the primary child form as well as the Parent form primary submission.
Use Nested Forms to save time by constructing forms that you know will be reutilized through the course of your project and application. Use Nested Forms to integrate child forms into all different kinds of parent forms within your application, all while collecting and housing submission data into one primary source.
Nested Forms For Remotely Deployed Projects
If your project is remotely deployed with subdirectories, set up your application to perform an API call like the following:
Formio.setProjectUrl(<project_URL>).
This will help Formio understand where to fetch nested resources from and will set up base URLs properly.
Unique Settings
Field Examples
Guidance
JSON
Form: Select a child Form/Resource that you’d like to nest into the parent form
Save as reference: Check if you’d like to save only _id of the child form submission instead of storing all child submission object inside of parent submission. This will also help all changes you’ve made in child submission be reflected in parent submission. If not checked, the entire child submission object will be saved. Any updates or changes made to the child submission data will not be reflected in the parent submission.
What is the Tagpad?
The Tagpad component allows the form designer to add an image URL to the component. Additional components, like a Text Field, can then be added to the Tagpad image. This allows form users to 'tag' a point on the image and input data associated with the tagged point. Tagged points and corresponding input data will be saved with the submission data when the form is submitted.
How do I use the Tagpad?
Use a publically accessed image when using the Tagpad
Inside the Form Builder, drag and drop the Tagpad component from the Premium component grouping onto the form. Within the Tagpad settings, copy and paste your image URL to the corresponding field. Once set, the image will display in the Preview section of the component settings.
Tagpad Settings
After adding your image URL, use the form builder to add additional components inside the Tagpad dropzone.
Add components inside the Tagpad
These components will display for the user when an area is 'tagged' on the image. The form user can then input field data to the corresponding dot tag which will be saved with the submission. Add as many dot tags as needed to the image. View or update input values for any saved dot by clicking the dot. Remove a dot tag and corresponding data by clicking the red trash can icon.
End user interacting with the Tagpad component
Tagpad visual guide
Unique Settings
Guidance
JSON
Width: Default image width
Height: Default image height
Dot Size: Default size of the dot tag
Dot Size Stroke: Default dot tag border width
Dot Custom Label: Default label of the dot tag
Dot Value Template: The HTML template representing the Dot values tagged by the form user. This template can be modified within the Template tab within the Tagpad settings. There are four variables that can be modified within the template:
- Dot:
- Index:
- Array:
- Instance:
Use the Tagpad component when input data is needed represented by a visual dot tag on an image. Some common use cases for the Tagpad:
Healthcare Forms
Vehicle Fleet Inspection
Construction Compliance
Home Inspection Reports
Case Reporting
{
"label": "Tagpad",
"imageUrl": "https://myimageurl.jpeg
"tableView": false,
"key": "tagpad1",
"type": "tagpad",
"input": true,
"components": []
}
What is the Sketchpad?
The Sketchpad allows a form designer to add a public image to the Sketchboad component. End users interacting with the form can then sketch on the image using a WYSIWG-type editor. Sketches made on the drawing will be saved with the submission data when the form is submitted.
How do I use the Sketchpad?
Use a publically accessed image when using the Sketchpad
Start by dragging over the Sketchpad component from the Premium component grouping onto the form. Within the Sketchpad settings, copy and paste your image URL to the corresponding field. Once set, the image will display in the Preview section of the component settings and on the form builder.
Once set, end users interacting with the form can click the image to open a module. Here the user can perform different actions like drawing on the image, adding object shapes, changing line thickness, and selecting the sketch color. These settings are controlled by the end user inside the module window. The form designer can also change the default values for the mentioned settings.
Sketchpad Visual Guide
Unique Settings
Guidance
JSON
Image URL: Image that will display on the Sketchpad component
Set Size Automatically: The form renderer automatically sizes the image based on available form space
Default Zoom: How close or far the image will appear to the form user
Default Line Width: Default width of the line strokes
Default Circle Size: Default line width of the circle shape
Use the Sketchpad component when a drawn visual representation is needed on an image from the form user. Some common use cases for the Sketchpad:
Healthcare Forms
Vehicle Fleet Inspection
Construction Compliance
Home Inspection Reports
Case Reporting
{
"label": "Sketchpad",
"imageUrl": "https://myimageurl.svg",
"tableView": false,
"key": "sketchpad",
"type": "sketchpad",
"defaultLineWidth": 5,
"input": true
}
What is the Review Page?
The Review Page component presents form users with a summary of their data before submitting the form. This component is code free and simple to configure, catering to non-developer users.
How do I use the Review Page?
To set up the Review Page, you will first need to add other components to the Form, the Review Page will populate data from those components in real-time. Once you have other components in place, drag and drop the Review Page from the Premium component group. Open the settings and click the Review Fields dropdown. This dropdown will populate all of the available fields within your form. Select any single input field from the available components. The selection order of the components will also dictate the order they appear on the Review Page.
Now that the Review Page is configured, Use your form to test out the summary. As the Form is filled out the form, the Review Page will output the data of the selected fields to the Summary section of the component.
Why should I use the Review Page?
Using the Review Page is a great way to give your users a chance to review their data before submitting the form which can help reduce user errors and make for a better user experience.
Unique Settings
Guidance
JSON
Review Fields: Multi-Select dropdown that will populate all of the available fields within your form. Select any single input field from the list. The selection order of the components will also dictate the order they appear on the Review Page.
- If you are utilizing PDF downloads, it may not be beneficial to have the Review Page part of the output. To remove the Review Page from the PDF download, simply move the Review Page component inside a Panel and add the following Field Tag to the Panel settings
viewer:hide. This will include the Review Page when a user is filling out the Form, but remove the component when viewing the PDF Download.
{
"label": "Review Page",
"type": "reviewpage",
"input": true,
"key": "reviewPage",
"tableView": false,
"tag": "div"
}
The Signature component allows the end-user to digitally sign a signature pad with either their finger on a touch-enabled device or with the mouse pointer. When the form is submitted, the Signature pad will be converted into an image and stored with the form submission.
Unique Settings
JSON
Provider: This dropdown will determine what kind of Signature pad to use.
Default: Standard digital signature that can be signed upon form submission
Box Sign: Selecting Box Sign will allow you to set up an eSign workflow.
{
"label": "Signature",
"tableView": false,
"provider": {
"name": "default",
"tagtype": 1
},
"key": "premiumsignature",
"type": "signature",
"input": false
}
Custom components allow users to create a custom field using the JSON schema of other component types. When complete, these custom components will be rendered using a front-end application. This is a very useful and flexible option to create special or complex form fields that might not be offered with the out-of-the-box form builder.
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.
Custom JSON Elements
Type: The type property will be used to select which component to render on the front end. 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.Type: The type property will be used to select which component to render on the front end. 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.
Data Table Component allows you to easily work with large sets of data. It is similar to the Edit Grid in the sense that Data Table also allows you to collect an array of object values and then construct it as a table view as you add new rows. The Data Table also supports showing/hiding of columns, pagination, sorting, and filtering to find needed data and etc.
Example of Data Table Component
By default, the Data Table is empty, but can have other form components placed inside.
Data Table without components in the edit form
The example below illustrates components placed inside the Data Table. A new column is automatically added whenever another component (with checked Table View setting) is added to the Data Table interface.
Data Table with components in the edit form
Allows you to show only columns you need now.
Allows you to show manipulate a big bunch of data by separating it into smaller pieces - pages. You can go to the first/previous/next/last page and choose the size of a page.
Allows you to sort data in Data Table using arrow buttons in the header or "Sort Ascending" and "Sort Descending" buttons in column menu.
Allows you to filter data in Data Table using the "Filter" section in column menu.
Provided filter operations such as "contains", "matches", "less than", "greater than", "equals", "not equals" and etc.
Allows you to edit data of Data Table with no need to open Edit Modal. Just like in Excel.
- 1.Add Data Table and Data Source. Add Components to Data Table with Property names corresponding to the field names in the data from api. Make sure that Table view is checked for every component you want to see in table.
2. Set your Data Source URL on Fetch tab and Trigger on form init on Trigger tab
3. Go to Data tab of Data Table Component and set Redraw on to Data Source and Calculated Value to
value = data.dataSource
4. That's it! Go to Use tab and check out.
Allows populating a Data Table with data from a custom endpoint/resource.
Distinctive features of the API-driven Data Table:
- only displays the data received from the endpoint/resource;
- populated data cannot be modified or deleted;
- data is excluded from the form submission;
- not displayed in read-only mode;
- supports lazy-loading and requests data from the endpoint/resource for every operation like sorting, filtering and pagination.
In the example, we use the submissions endpoint of the form.io form as the source of data for API-driven Data Table.
- 1.Create a resource/form with the title ‘Data Table Source’. Add 4 components to it with keys: id, firstName, lastName, age. Make several submissions for this form.
Form that is used as a data source for API-driven Data Table
2. Create a new form. Add a Data Table component. Add some components to Data Table and make sure the components inside Data Table have Table View enabled.
In our example, we have added 5 components with keys: employeeId, firstName, lastName, age, created.
API-driven Data Table with components
3. Go to Fetch tab in the Data Table settings and enable fetch. Set your Data Source URL.
In addition, the following settings can be configured:
- Request Headers: Headers that will be added to the request to ‘Data Source URL’.
- Form.io Authentication: If checked, Form.io authentication headers are added to the request to ‘Data Source URL’. Mainly used if Data Table data is requested from a Form.io endpoint.
- Enable to Store Request Result in the Cache: If checked, the requests and their results will be stored in the cache.
- Transform Data: Custom code that transforms the data, received from the ‘Data Source URL’, before setting it to Data Table. Data Table expects the data to be an array of objects with keys equal to keys of components inside the Data Table. If the data received from ‘Data Source URL’ does not correspond to this format, please, transform it here.
- Default Sort Query: The sort query that is used by default if a Data Table column sorting is not set.
- Custom Fetch Provider: The name of your custom provider that extends the default Formio fetch provider (FetchProvider or UrlFetchProvider) and is added to global Formio Providers.
The Fetch tab configuration for our example looks like this:
Fetch tab configuration of the API-driven Data Table
Transform data settings:
4. Configure Data Table components.
The following additional settings are available for API-driven Data Table components in Display tab:
- Column Query Property: This component property is used in filtering and sorting queries. If the property is not defined, the component key is used instead.
- Disable sorting and filtering in Data Table: If checked, sorting and filtering functionality is not available for the Data Table column containing this component.
In our example, set up Column Query Property for the components with the keys employeeId, firstName, lastName, age. The Column Query Property is equal to the path to the value in object that comes from the endpoint: employeeId – data.id, firstName – data.firstName, lastName – data.lastName, age – data.age.
Column Query Property configuration for API-driven Data Table component with key employeeId
5. That is it! Go to the Use tab. Data Table is populated with data from the endpoint.
Requirements to custom endpoint used as a source of data for API-driven Data Table:
- supports partial content and returns Content-Range header
- supports sorting and filtering
If custom endpoint does not support some range, filtering or sorting query parameters used by API-driven Data Table by default, a custom provider can be created based on the default Formio URL Fetch Provider.
import {Formio} from 'formiojs';
import premium from '@formio/premium';
Formio.use(premium);
const UrlFetchProvider = Formio.Providers.getProvider('fetch', 'url');
class CustomFetchProvider extends UrlFetchProvider {
getData(params) {
//your custom code.
//should return a promise with array of data
}
}
Formio.Providers.addProvider('fetch', 'MyCustomProvider', CustomFetchProvider);
To have the data table use a custom provider, use the name of the custom provider to configure Custom Fetch Provider in Fetch tab of the Data Table settings.
Custom Fetch Provider Configuration
You can populate Data Table with components and data from a resource, you have in your current project. Look at the example below.
- 1.add a resource to your project with title 'Data Table Resource' and add some components there:
Data Table Resource form
- 2.create a new form and add Data Table component in it. Open Data Table settings and configure the fetch tab like this:
- enable fetch;
- select Resource for the Fetch Source Type field;
- select a resource that you would like to use as a source of components and data for your Data Table;
- add some fields of the source form that you would like to see in your Data Table. Each selected field will become a column in the Data Table and will display in the order in which it was added to the Grid Components setting;
- additionally, you can set Default Sort Query, that is expected to be equal to the path to sorted value on submission object of the resource from (e.g. data.age).
Fetch Tab configuration for Data Table populated from Resource
Save the Data Table settings. Save the form.
- 3.That is it! Go to the Use tab. Data Table is populated with components and data from your resource.
Data table populated from resource
Data Table component Display settings
Field | Description |
Sortable | If checked, allows you to sort data in Data Table. |
Filterable | If checked, allows you to sort data in Data Table. |
Inline editing | If checked, allows you yo edit data with no need to open Edit Modal. |
Items per page | Allows you to choose default page size of data displayed in Data Table. |
Show add button | If checked, allows you to add data to Data Table. |
Show edit button | If checked, allows you to edit data in Data Table. |
Show delete button | If checked, allows you to delete data from Data Table. |
Show delete all button | If checked, allows you to delete data from Data Table. |
Delete all confirmation message | Allows you to configure confirmation message before delete all. Visible only when Show delete all button is checked. |
Add Advanced Header | If checked, allows you to add an advanced header. |
Add row select configuration | Adds an additional column Select and allows you to use “rowSelectChange” event. Visible only when Add Advanced Header is checked. |
You can add Button Components, HTML Element Components and Content Components into Data Table and configure them to add dynamic behavior using
row variable.Add Button Component inside Data Table, set its Action to Custom. Then add
alert(JSON.stringify(row, null, 2)); the line to Button Custom Logic field to see JSON data of row.
You also can use
row and rowIndex variables in HTML Element Component and Content Component to customize their view for each row.For example, set this code to Content field of HTML Element Component and you will see a simple inline chart based on the number field.
<div style="width: {{row.number}}%; height: 30px; background: {{row.number > 60 ? '#3fb618' : row.number > 20 ? '#ffdc31' : '#e25652'}}">
<b> {{row.number}}%</b>
</div>
Last modified 11d ago