Form Templating

This functionality is new in the 4.x branch. If you are using the 3.x branch, we encourage you to upgrade to get this new functionality.

Introduction

The 4.x branch of the formio.js library (and corresponding framework libraries) have some significant enhancements and improvements. This page will outline the changes and how you can use them to further customize your form.io forms.

There are three primary ways that the 4.x branch has changed.

1. Instantiation of components

In previous versions of formio.js, components were only instantiated when the were visible in the DOM. In 4.x and later all components will be instantiated regardless of whether they are visible or not. This is important for setting initial values, calculating while hidden and running validations on hidden components. It also greatly cleans up more complex components like tables, datagrids and tabs.

2. Component lifecycles

In previous versions of formio.js, components had only one lifecycle function, the build method. This was triggered whenever a component was added to the DOM and was expected to initialize the component, add DOM elements to a root element (mostly using this.ce()) and attach all events to the dom elements. This was a very static process where functions would build out all the DOM elements of the component element by element and manually add them to the DOM. In addition, the logic of changing the DOM or attaching actions to DOM elements was completely intermingled with the rendering process. The end result was that components had a static layout. Theoretically it would have been possible to override the rendered DOM by overriding the build method but in reality it would have essentially involved creating an entirely new component.

Now, in the 4.x branch, the lifecycle is broken into three phases. These are init, render and attach. The init is run when the component is instantiated. It will not run again unless a rebuild is called. The render method is then called which is expected to return a string of html that represents the whole of the component. This string is then added to the DOM and a reference to the component's root DOM element is returned. Finally, the attach method is called and passed the reference to the root DOM element. The attach method is expected to find relevant parts of the DOM and attach events and logic to them. When the rendering of the DOM needs to change, like a component being hidden, a hidden flag is set on the component and it is redrawn. The component itself does not need to do the hiding. This is more consistent with how newer frameworks (like React and Vue) are rendering where they render based on the current state.

3. CSS Framework Templates and customizing templates.

Since we now have a proper rendering layer, we now support additional CSS Frameworks to bootstrap. In particular we have bootstrap 3, bootstrap 4, Semantic UI and are planning on adding support for Materialize (a generic Material UI framework). You can now select which CSS Framework template you want to render your forms in and apply the different CSS accordingly. In addition, you can even customize the html output by the form to modify how components render.

Setting a CSS Framework

When setting up an application, you can select which CSS Framework you want to render the output to. Form.io currently supports the following frameworks:

• Bootstrap 3 (bootstrap3)
• Bootstrap 4 (bootstrap)
• Semantic UI (semantic)
• Other - Contact us for help implementing another framework!

The default template is currently Bootstrap 4 so if you want to use that, you don't have to do anything else. In order to switch to a different framework, you will need to set it globally so that the renderer will use the framework's templates.

import { Templates } from 'formiojs';

Templates.framework = 'semantic';

If you are using a framework wrapper, you should import Templates from that wrapper instead of formio.js so that it will apply to the Formio instance within the wrapper as well. For example, if you are using react-formio you should do:

import { Templates } from 'react-formio';

Templates.framework = 'semantic';

Overriding templates

In addition to setting the global CSS Framework, you can also override specific templates within that framework. This allows you to change the html output of the component even as the component continues to function the same. In order to do this, simply set the template on the Templates object and the renderer will start using it.

You can do this one of two ways. First, by setting multiple templates:

Templates.current = {
  input: {
    form: '<div>My custom template</div>'
  },
  html: {
    form: '<div>My other custom template</div>'
  }
};

Or individually:

Templates.setTemplate('input', {
  form: '<div>My custom template</div>'
});

Refs

Custom Components

Server Side Rendering