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

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).