Forms
Forms are the primary interface within the <form.io> system. Design a Form by dragging and dropping Form components onto the Form component area. Form components that are placed onto a Form will determine what that Form object looks like. You do not need to create an API before creating the Form. A compatible API will automatically be mapped out for you as you design your Form.
For an in-depth explanation of how Resources work, please read the Forms and Resources guide.
Forms can be created from the Project home page. Get to this page by clicking on the Project name from the User Portal page or clicking the edit tab at the top right of the page while within the Project.
At the bottom of the list of Forms, click the New Form button to begin creating a Form.
Enter a title for your Form. This will help you identify it later.
This is the machine name for your Form. It can only contain alphanumeric characters and will be automatically populate from the title you enter in camel cased (where the first word is lower cased and each subsequent word starts with a capital letter). Form Names can be changed if you do not wish to carry the Title. The Name field will be used when embedding the Form into your application.
The API Path is the endpoint for accessing the Form and Form submissions. Choose the endpoint you’d like to use.
Drag and Drop Form components on to your Form. See Form Components for more information on types of components and how to configure them.
Enter any settings desired in the advanced settings section. Currently custom submission URL is the only option for Advanced Settings. Saving a URL in this setting will send submissions to that URL instead of <form.io>. This is helpful if you want to handle the Form submissions within your own service or if you wish to pre-process the data before sending it to <form.io>. Use this only if you know what you are doing.
Forms can be edited from the Project home page. Get to this page by clicking on the Project name from the User Portal.
In the list of forms, click the Edit button to start editing a form.
When you are done editing, click the Save button.
Forms can be deleted from the Project home page by clicking on the trash icon next to the form. You will be prompted to confirm the form deletion.
Deleting a form cannot be undone. Use caution.
There are many situations where you would like to copy an existing form into a new form within your project, or between projects. Because of the cross project nature of this operation, the best way to accomplish this is to use the Form.io Command Line tool. First install the command line using the following command in your command prompt.
npm install -g formio-cli
Once you have the command line installed, you will then need to create the form which will serve as the destination form. You do not need to add any components to this form, but just keep it blank since the copy command will populate the destination forms components. Once you have the destination form created, you will then use the formio copy form command to copy your forms using the following syntax.
formio copy form <source> <destination>
As an example, the following command will copy a from in project.
formio copy form https://myapp.form.io/source https://myotherapp.form.io/destination
TO-DO: Documentation on the "Use" tab and what it means to "use" a form, i.e. to submit the form.
Form Versioning can extend the capabilities of any project cycle by giving users the ability to evolve current forms while preserving the integrity of previous iterations. Form Versioning allows for detailed deployment tracking, allowing teams to see who has updated a form, when a change was made, and any notes associated with the update. Additionally, Form Versioning can be used to revert to previous incarnations while safeguarding all submission data.
Form Versioning is limited to Enterprise level projects. Users without an Enterprise level project can still experience versioning via any Trial level project.
To get started, create or enter an existing project. For the purpose of this walk-through, an HTML element will be anchored to the top of each form to keep track of the current iteration.
To enable Form Versioning, expand the Advanced Settings tab by clicking on it.
In the Form Revisions section, expand the select dropdown menu and select either Enable option.
Form Revisions can be configured in two different ways:
Enabled – Use current form version when viewing submission
Will display all form submission data in the most recent form revision.
Enabled – Use original form version when viewing submission
Will display form submission data in the form revision that it was captured in.
This functionality extends to wherever users choose to view their submission data. This includes viewing their data from within the <form.io> platform or externally like inside the users application.
Afterwards, click either Create Form if creating the a new form or Publish when interacting with an existing form. Once saved, Form Versioning is now enabled and the Revisions tab is now available for user interaction.
Once inside the revisions interface, users can see the full scope of their current development cycle. Important information such as who made the revision, when the revision was made, the revision number, and any notes made are all available. Additionally, several actions are now available.
Use
Will enter the traditional form
Usetab in that form revision.
Data
Will display form submission data that was captured in that form revision.
Restore
Will make a clone of the current revision, iterating the Vid to the most recent revision.
These items will be covered in depth further down.
With Form Versioning enabled, users can begin iterating through different form revisions. Note that this revision has a new field added. Additionally, this guide has iterated the tracking HTML field manually to illustrate a change in form version, this is not an automatic process.
At the bottom of each form, users can enter a revision note that will appear alongside other important information in the Revisions tab once published.
Once complete, pressing the Publish Form action will create a new revision and will be visible on the revisions page.
Note that the system has automatically iterated the Vid number now that multiple revisions exist.
By default, the Use tab will display the most recent form revision (the one with the highest Vid).
However, users can interact with the Use action from within the Revisions tab to use specific form revisions.
When using Vid #1, the original form is displayed, notice how (C) Version Field is no longer present.
When using Vid #2, notice (C) Version Field is present again as well as the change to the tracking field.
A 3rd revision has been added where (B) Version Field has been removed. Additionally, the following submissions have been made to each for form version:
Version 1: 2 submissions made
(A) { Apple1, Apple2 }
(B) { Banana1, Banana2 }
Version 2: 3 submissions made
(A) { Apricot1, Apricot2, Apricot3 }
(B) { Blueberry1, Blueberry2, Blueberry3 }
(C) { Cherry1, Cherry2, Cherry3 }
Version 3: 2 submissions made
(A) { Avocado1, Avocado2 }
(C) { Carrot1, Carrot2 }
A simple inspection of the Data action for Vid #1 will reveal the two submissions listed in the table above.
Notice that only submissions made using Vid #1 are displayed. Ergo Apricot and Avocado entries are not present.
To view all submissions, click the Data tab at top and all 7 entries will display.
Notice, that (B) Version Field entries are not displayed.
Not to worry, as illustrated above, the data is still there. Recall that the most recent form revision removed (B) Version Field and as a result the data table only displays key value pairs that exist within the active form.
Since (B) Version Field data is hidden due to the current form revision not having that field, the restore action can be evoked to recover the former layout. From the Revision tab, selecting Restore will being the restoration process.
Afterwards, users are redirected to the form editor where additional revisions can be made, a revision note can be made, and other components added. Notice, that (B) Version Field has been restored and a note has been made.
Upon publishing the form, a return visit to the Revisions tab will reveal a new revision, Vid 4. Additionally, the note made during the restoration process is also visible.
It is important to note that restoring a form does not overwrite or alter the original revision. Instead, a new revision is made which is why there are now 4 revisions. Continuing, a visit to Data tab will reveal that (B) Version Field and its respective data, has returned.
Form Versioning also supports a draft feature where changes can be made without publishing a new version. Continuing with the example, (D) Version Field has been added and saved as a draft.
An inspection of the revisions tab will reveal that a draft now exists.
Drafting is primary used to test form construction without overwriting the active form revision. As a result once a draft is published, it will disappear from the revisions page. Lastly, there can only ever be one active draft at a time.
TO-DO: Documentation on form embedding.
