A brand new Form Builder for Neos

Welcome the new Form integration to the Neos CMS backend and new possibilities to render Forms with Flow

– Written by

Quick recap

HTTP Forms are a very old and important concept of the Web Platform and Fluid had support for them right from the start.
But we always knew we would need some dedicated tool chain that allows for easy and extensible Form handling in Flow and Neos.
So almost six years ago, in December 2011, Sebastian Kurfürst and me started to work on the Form API and -Builder.

The result were two packages. The core Flow Form Framework that provides an API to create and a YAML Builder (formerly known as Form Builder) that provided a Graphical User Interface to build Form Definitions.
Today the Form package is active with every Neos installation and is used to run the Neos Setup.

Extensibility vs Usability

One of our main goals has always been to come up with a flexible and extensible framework that allowed developers and integrators to create many kinds of Forms. That's why all Forms have support for multiple pages and are based on a configurable Preset that can substantially influence behavior and rendering – allowing Form to be served via Command Line Interface for example.

That extend of flexibility doesn't come for free. The increased complexity raises special challenges regarding the usability for developers as well as integrators.

The former Form Builder

For the reasons mentioned above the original Form Builder was created, to ease creation and modification of Form Definitions.

That was an important step and the project is still used and maintained. But the implementation has some drawbacks:

  • Poor Neos integration: The Builder can be installed along side with Neos of course, but it requires additional MVC Routes and there is no authentication built in
  • Cumbersome process: To create/update Form Definitions, a YAML file needs to be copied around
  • Only static forms: Using configuration files for the Form Definitions makes them easy to copy and source-control. But they can't be as dynamic as a Fusion- or database-based Definition for example.
Neos Form YAML Builder

The Neos Form YAML Builder (formerly known as Form Builder)

The new Form Builder

There are quite some projects with different strategies to tackle these challenges. Amongst them there are some really interesting ideas and you should check them out if you're interested (see links below for a selection)

While these projects served as great source of inspiration for the new Form Builder, we decided to start a new package within the Neos namespace creating a common foundation we can build upon.

The result is the Neos.Form.Builder package, that seamlessly integrates into the Neos Backend.

The new Form Builder

The new Neos Form Builder within the Neos User Interface

Features

Some of the features of the new Form Builder package:

Content Repository Persistence

The basis for the Neos Form Builder is the new persistence backend that allows Form Definitions to be stored in the Content Repository.

Therefore the package comes with NodeType definitions representing all of the Form Elements of the default presets plus a set of Mixins that allow custom Form Elements to be added easily.

FormBuilderNewElementWizard.png

New Element Wizard inside a Form

FormBuilderCustomStylesShadow.png

Custom rendering for the Form ContentCollections

Custom Styles for the Backend

The Form Builder is not a new application or Neos Module but it integrates into the regular Frontend Editing experience.

Complex Forms with multiple Pages, Validators and Finishers can lead to a cluttered interface that makes it hard to click the right container in the Neos backend.

Thus the package includes custom CSS that can be included to render some icons for the special Form ContentCollections, greatly improving the User Experience.

Fusion based Form Definitions

When creating Forms via the Neos Backend, their Definition is stored in the Content Repository, as mentioned above

But in fact everything is processed by Fusion, allowing for "manual" specification of Forms (see example to the right).

This enables you to use the whole Fusion power (pun intended). So you can, for example, adjust the rendering of a Form Field depending on the currently authenticated account or pre-fill the Form with data from the current context otherwise.

FormBuilderFusionDefinitionShadow.png

A simple contact Form defined in plain Fusion

Fusion based Rendering

Even though Form Definitions are based on Fusion with the Neos Form Builder, the rendering of Forms has not been changed. By default it is still based on the FluidRenderer and templates for all the Form Elements.

That approach is flexible and probably the easiest for developers that are used to working with Fluid. When a lot of custom rendering is required, though, it can lead to a duplication and accidental complexity.
For these cases the – also brandnew – Neos.Form.FusionRenderer package will come handy.

It defines a new Form Preset that replaces the default Form Renderer with a Fusion implementation. The default prototypes render elements just like the "default" preset would. But now the complete output is adjustable with a bit of Fusion code.

The following example will remove the labels of all elements and render their content as placeholders instead: 

prototype(Neos.Form.FusionRenderer:FormElement) {
    label >
    fieldContainer.field.attributes.placeholder = ${element.label}
}

Make sure to have a look at the Fusion prototypes to see how they work together and how they can be manipulated to your needs.

Note: The FusionRenderer package doesn't require Neos, you can use it in Flow applications as well!

Sponsoring / Credits

Creating the Flow Form Framework has been one of these projects that is really difficult to kickstart out of a "personal itch" that frankly drives most of our voluntary work on Flow and Neos.
It's difficult because it means a lot of work without immediate pay-offs (API design, testing, documentation, ..).
So while we knew that we would need concepts and tooling for forms in Flow from the start, it took a sponsoring from akom360 GmbH back then to plan a mini Sprint in Dresden to kickstart this project (have a look at 2012-Sebastian presenting the result).

Work on the new Neos Form Builder has also been supported by a sponsoring, this time from internezzo ag and Format D GmbH – they both share a Bronze Core Feature Sponsor Badge. Thank you very much for your support, it's greatly appreciated!

Thank you also to my great co team members and other individuals helping me with discussions, tips and bug reports. Namely: Benno Johnson, Bernhard Schmitt, Gerhard Boden, Martin Ficzel, Peter Rauber, Sebastian Kurfürst and Wilhelm Behncke!

Links

More Form Packages

We tried to incorporate good ideas from many existing packages into this project, but we could not stuff everything into this one release.
If you're missing a specific functionality, make sure to have a look at these packages, too: