AngularJS Embedding

<form.io> provides an AngularJS module that allows building out forms and APIs on <form.io> and then embedding everything directly into your application with one line of code. When using this method, there is no other work needed to allow users to create, edit and delete resources within your application and when you make changes to the forms, they immediately update within your application.

The normal process to embed is to use bower to install the formio component with bower install ng-formio and then include all the dependencies in your html files with either gulp wiredep or manually. You can see examples of this inside our sample applications at https://github.com/formio?utf8=%E2%9C%93&query=formio-app-.

To make the process simpler for those who only need to embed on a website, we provide a build file, formio-full.js, with all dependencies already included. It can be found at https://github.com/formio/ngFormio/tree/develop/dist. Include this script on the page and instantiate an angular application with a dependency on formio and you can then directly embed forms.

Here is a working jsfiddle of the simplest way to do an embed.

ngFormio

The ngFormio library allows you to embed forms within an AngularJS application using a simple AngularJS directive.

<formio src="'https://examples.form.io/example'"></formio>

Which produces the following result.

The documentation for this Open Source Form Renderer Library found @ https://github.com/formio/ngFormio

Go to ngFormio on Github

ngFormBuilder

The Form Builder is an AngularJS directive where you can embed a full functioning Form Builder within your application using a simple directive as follows.

<formio-builder form="form"></formio-builder>

This produces the following form builder.

The Form builder is really just a glorified JSON schema builder which can then be fed into the Form Renderer as seen in the following codepen.

See the Pen Form.io Form Building and Rendering by Travis Tidwell (@travist) on CodePen.

This is the documentation for our Open Source Form Builder Library found @ https://github.com/formio/ngFormBuilder

Go to ngFormBuilder on Github

ngFormioGrid

The ngFormioGrid allows you to embed a Data Grid within your application where you can view the data submissions within a form using a simple directive.

<formio-grid src="'https://examples.form.io/company'"></formio-grid>

which produces the following

The documentation for this library can be found @ https://github.com/formio/ngFormioGrid

Advanced Documentation

To view the advanced documentation for this library, Go to the Documentation Section

ngFormioHelper

The ngFormioHelper library provides helper tools to assist developers in incorporating the components of Form.io such as Resource Management, Form Management, and User Authentication.

Detailed documentation for this library can be found @ ngFormioHelper

Advanced Documentation

Go to the ngFormioHelper Wiki to read more documentation over this library.

Adding the Formio Module

In order to embed your <form.io> project in your angular application, you will need to add the formio module. The formio module will create all scopes, providers and directives needed to embed <form.io> components within your app.

Bower

To add formio to your bower dependencies, run bower install --save ng-formio.

Adding the dependencies

Formio requires some dependencies on your HTML page to work properly. All of these dependencies can be found by looking at the formio bower.json file. The easiest way to include all of these dependencies within your webpage is to use a tool called Wiredep.

Wiredep

First you need to install wiredep.

  npm install -g wiredep

Next, add the following to your HTML page:

  <html>
    <head>
      <!-- bower:css -->
      <!-- endbower -->
    </head>
    <body>
      <!-- bower:js -->
      <!-- endbower -->
    </body>
  </html>

Next, run the following command to wire up all the dependencies.

  wiredep -s index.html

This should then wire all the dependencies into your page.

Example Page

To see this in action, here is an example page with all the dependencies already wired up for reference.

Initialize Angular

The next step is to initialize formio within your Angular application. This requires you to add the following to your angular.js declaration.

angular.module('myApp', ['formio']);

And of course, if you are not using Angular for your full application, you will need to make sure that the application name is provided on the <body> tag.

<body ng-app="myApp">

</body>

formio Directive

Form.io forms can be embedded direction into your angular application with one line of code. Simply pass in the name of the form to the directive and the formio module will render out the form for you. If you only pass in the form name, a form with default values will be rendered. This is useful for Creating new submissions.

<formio src="'https://yourproject.form.io/yourform'"></formio>;

Rendering Submission in Form

You can also render out a form for a previous submission with the values already set in it. This is useful for Editing functionality to allow users to edit previous submissions.

<formio src="'https://yourproject.form.io/yourform/submission/[submissionId]'"></formio>

Read-only Submissions in Form

You can provide a read-only flag to the formio directive which will tell the form to render as a Read only form where the data is populated but cannot be edited. This is good for Printable form submissions as well as viewing a form submission.

<formio src="'https://yourproject.form.io/yourform/submission/[submissionId]'" read-only=true></formio>

Attributes

src
The URL of the form or form submission to display.
form-action
The URL of the custom form action to handle submissions. If this attribute is provided, form submissions will be sent to that URL instead of Form.io. This is helpful if you need to pre-process data before sending it to Form.io.
form
An Object definition of the form to display. This can be used as an alternative to loading form definitions from the src attribute.
submission
An Object containing submission data to display. This is useful if you have already loaded submission data you wish to display on this form.
read-only
Makes form fields read only, which can be useful for Viewing submission results.
formio-options
An Object containing options to pass to Formio.js, often used with Formio.js plugins.

formioSubmissions Directive

In addition to forms that create submissions, the formioSubmissions directive can embed lists of previous submissions within your application. This is useful for creating lists of items to display within your applications.

<formio-submissions src="'https://yourproject.form.io/yourform'"></formio-submissions>

Attributes

src
The URL of the form to display the submissions of.
form
An Object definition of the form to display. This is helpful if you have already loaded the form that corresponds to the submission data.
submissions
An Array of submission data Objects to display. This is helpful if you have already loaded submissions you wish to display.
per-page
The number of submissions to list per page.

formioDelete Directive

This directive will show a delete confirmation dialogue and will, on confirmation, delete a form or submission. This directive triggers the cancel or a delete events depending on user input.

<formio-delete src="'https://yourproject.form.io/yourform/submission/[submission_id]'"></formio-delete>

Attributes

src
The URL of the form or submission to delete.
form
Alternatively, you can pass in the form definition as an attribute on the formio directive.
submission
If a submission has already been loaded, it can be passed in as an attribute.
form-action
The URL of the custom form action to handle delete requests. If this attribute is provided, HTTP DELETE requests will be sent to that URL instead of Form.io. This is helpful if you need to pre-process data before deleting it from Form.io.
resource-name
The resource name used in the delete dialogue for confirmation. If not provided, it will default to "form" or "submission", depending on the src attribute passed in.

Formio Events

The formio module emits events at various times. These events are designed to allow developers to respond to events that occur within the formio generated forms. For example, after a user creates a new submission, you may want to change the view to display that submission or send them to a thank you page. You can do this by responding to the formSubmission event:

$scope.$on('formSubmission', function(err, submission) { /* ... */ })

The following are all the events emitted by the above directives:

formSubmit
Called after a form is submitted, but before it has been sent to the server. This submission can be cancelled by calling `event.preventDefault()`.
Parameters:
submission: The submission that was submitted.
formSubmission
Called after a form is successfully submitted to the server. This can be either a create or an edit.
Parameters:
submission: The submission that was submitted.
formError
Called whenever client side validation fails.
Parameters:
error: The error that occurred.
formLoad
Called whenever a form is loaded from the form.io server. This is useful to customize forms before they are displayed.
Parameters:
form: The form that was loaded.
submissionView
Called whenever the view button is clicked in a `formioSubmissions` directive.
Parameters:
submission: The submission that is being viewed.
submissionEdit
Called whenever the edit button is clicked in a `formioSubmissions` directive.
Parameters:
submission: The submission that is being edited.
submissionDelete
Called whenever the delete button is clicked in a `formioSubmissions` directive.
Parameters:
submission: The submission that is being deleted.
submissionLoad
Called whenever a submission is loaded from the server.
Parameters:
submission: The submission that was loaded.
submissionsLoad
Called whenever multiple submissions are loaded from the server.
Parameters:
submissions: An array of submissions that were loaded.
cancel
Called whenever a delete dialog is cancelled.
delete
Called whenever a delete dialog is confirmed and a submission is deleted.
Parameters:
data: The data that was returned from the delete request.

Styling Forms

Since embedding {{ site.formio }} forms embeds them directly in your HTML pages instead of using iframes, you can easily add CSS styles to your application to customize form appearances.

Every form component is wrapped in a <div> with the class name form-field-type-{fieldType}. Use this to style all fields of a certain type. For example, to style only checkbox fields, you may have CSS that looks like this:

.form-field-type-checkbox {
    // Your styles go here...
}

The same <div> wrapping each form component also is given an id in the form form-group-{fieldKey}. The fieldKey corresponds to the unique Property Name given to each form component. You can find this in the API tab of the form component settings. Use this id to style a single specific form element. For example, to style a field with the key fullName, you may have CSS that looks like this:

#form-group-fullName {
    // Your styles go here...
}

Finally, you can configure most components with a custom CSS class that will be used when rendering the form. You can specify multiple class names by separating them with single spaces.

Conditional Fields

A frequent request is to have fields show and hide based on values in other fields. Building a fully functional UI for this would make using it daunting so instead we have enabled this through programming.

To have conditional fields, create a controller that wraps the form and send the submission variable into the form. Then watch the submission variable using $scope.$watch and then affect the displayed forms as needed. This will allow maximum flexibility into showing and hiding forms.

Here is a working example of showing and hiding fields in a jsfiddle. Feel free to try it out and modify it.

Form Translation

You can translate your {{ site.formio }} forms by wrapping Angular-Translate in your application.

There are a two ways of achieving this.

  1. You can call
$translateProvider.translation('en', {
  'Original String': 'Translated String'
});

This will register a new language to the translation provider. The Original String is the string within the form that you want to translate. It could be the field label, placeholder or dropdown value. You can include multiple strings in the language definition.

  1. You can include the translations in external files with https://www.npmjs.com/package/angular-translate-loader-static-files or other loaders.

From then on, use angular-translates language switching capability and the form will translate itself.