-
Notifications
You must be signed in to change notification settings - Fork 474
Form Renderer
The most important aspect of the Form.io platform is the ability to render a form dynamically within your application and then hook that form up to the REST API provided by the Form.io API platform. The Form Renderer within Form.io provides this capability.
As mentioned in the previous section, to use this library within your project, you will first need to install it as a dependency.
npm install --save ng2-formio
Once you have the module installed, you will now need to include the form renderer within your application by adding the FormioModule as a dependency within your application as follows.
import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { FormioModule } from 'ng2-formio';
import { MainComponent } from './main';
@NgModule({
imports: [
BrowserModule,
FormioModule
],
declarations: [
MainComponent
],
providers: [],
bootstrap: [
MainComponent
]
})
export class AppModule {}Once you have the module installed, you can now include the <formio> directive within your Modules template like the following.
import { Component } from '@angular/core';
@Component({
selector: 'my-app',
template: '<formio src="https://examples.form.io/example"></formio>'
})
export class MainComponent {}This provides a way to render the form within your application.
In addition to providing the URL of the form you wish to render, you can also pass the JSON form directly to the renderer as follows.
<formio [form]='{
"title": "My Test Form",
"components": [
{
"type": "textfield",
"input": true,
"tableView": true,
"inputType": "text",
"inputMask": "",
"label": "First Name",
"key": "firstName",
"placeholder": "Enter your first name",
"prefix": "",
"suffix": "",
"multiple": false,
"defaultValue": "",
"protected": false,
"unique": false,
"persistent": true,
"validate": {
"required": true,
"minLength": 2,
"maxLength": 10,
"pattern": "",
"custom": "",
"customPrivate": false
},
"conditional": {
"show": "",
"when": null,
"eq": ""
}
},
{
"type": "textfield",
"input": true,
"tableView": true,
"inputType": "text",
"inputMask": "",
"label": "Last Name",
"key": "lastName",
"placeholder": "Enter your last name",
"prefix": "",
"suffix": "",
"multiple": false,
"defaultValue": "",
"protected": false,
"unique": false,
"persistent": true,
"validate": {
"required": true,
"minLength": 2,
"maxLength": 10,
"pattern": "",
"custom": "",
"customPrivate": false
},
"conditional": {
"show": "",
"when": null,
"eq": ""
}
},
{
"input": true,
"label": "Submit",
"tableView": false,
"key": "submit",
"size": "md",
"leftIcon": "",
"rightIcon": "",
"block": false,
"action": "submit",
"disableOnInvalid": true,
"theme": "primary",
"type": "button"
}
]
}'></formio>This is a very simple example. This library is capable of building very complex forms which include e-signatures, columns, panels, field conditionals, validation requirements, and the list goes on and on.
The inputs for the <formio> directive allow you to control how the form renderer behaves. For example, to set the submission of a form (which will pre-populate the form with data), you can provide the following code which will set the form.
<formio src="https://examples.form.io/example" [submission]='{
"data": {
"firstName": "Joe",
"lastName": "Smith",
"email": "[email protected]"
}
}'></formio>The following inputs are accepted.
| Name | Description | ||||||
|---|---|---|---|---|---|---|---|
| src | To set the source URL of the form (or submission) to be rendered. Example: src="https://examples.form.io/example"
|
||||||
| form | To render the JSON schema of a form. Example: [form]='{"components":[...]}'
|
||||||
| submission | The submission JSON to pre-poulate the form. Example: [submission]='{"data": {"name": "Joe Smith"}}'
|
||||||
| service | Your own instance of the FormioService object to perform the requests. | ||||||
| readOnly | Make the form (and submission) read only. Great for when you are rendering a previous submission that should not be editable. | ||||||
| options | A JSON object of the follwoing options.
|
Once you have the form rendered within your application, the next step is to handle the submission within your Component. You can do this by using the (submit) output of the form renderer.
import { Component } from '@angular/core';
@Component({
selector: 'my-app',
template: '<formio src="https://examples.form.io/example" (submit)="onSubmit()"></formio>'
})
export class MainComponent {
onSubmit(submission: any) {
console.log(submission); // This will print out the full submission from Form.io API.
}
}Let's suppose you need to hook into the Form submission, make a call to your own service to perform a custom validation on that submission, and then when your validation passes, allow the submission to be handled. You may also want to tell the form that an error occurred within the Form submission and then provide the error. To do this, you will need to provide the options.hooks.beforeSubmit callback, which works as follows.
<formio src='https://examples.form.io/example' options='{
"hooks": {
"beforeSubmit": function(submission, callback) {
console.log(submission);
// Do something asynchronously.
setTimeout(function() {
// Callback with a possibly manipulated submission.
callback(null, submission);
}, 1000);
}
}
}'></formio>You may also wish to provide your own custom error.
<formio src='https://examples.form.io/example' options='{
"hooks": {
"beforeSubmit": function(submission, callback) {
console.log(submission);
// Do something asynchronously.
setTimeout(function() {
// Callback with a possibly manipulated submission.
callback({
message: "Something bad happened.",
component: null
}, null);
}, 1000);
}
}
}'></formio>With the <formio> directive, you can register for a number of different events that fire as the Form is being used and submitted. These events can be attached with the typical Angular 2 way using the following syntax.
<formio src="https://examples.form.io/example" (submit)="onSubmit($event)"></formio>
The following events are provided.
| Name | Description |
|---|---|
| (submit) | Called when the form is submitted. The submission object is passed to the callback function. |
| (render) | Called when the form is done rendering. |
| (beforeSubmit) | Called before a submission is made. The submission object is passed to the callback function. Note: If you need to manipulate the data, or even provide custom validations, then you should use the options.hooks.beforeSubmit handler instead. See documentation above. |
| (change) | Called when the form has been changed as in when someone is filling it out. |
| (invalid) | Called when the form is invalid. |