Form Builder overview

As of v10.5.0, Preside provides a system that enables content administrators to build input forms to gather submissions from their site's user base.

Enabling form builder

Pre 10.13.0

In versions 10.5 to 10.12, the form builder system is disabled by default. To enable it, set the enabled flag on the formbuilder feature in your application's Config.cfc$configure() method:

component extends="preside.system.config.Config" {

	public void function configure() {
		super.configure();

		// ...

		// enable form builder
		settings.features.formbuilder.enabled = true;

		// ...
	}
}

10.13.0 and above

As of 10.13, the form builder system is enabled by default. However, the v2 of the data model is turned off by default. To enable it:

component extends="preside.system.config.Config" {

	public void function configure() {
		super.configure();

		// ...

		// enable form builder
		settings.features.formbuilder2.enabled = true;

		// ...
	}
}

Forms

Forms are the base unit of the system. They can be created, configured, activated and locked by your system's content editors. Once created, they can be inserted into content using the Form Builder form widget. A form definition consists of some basic configuration and any number of ordered and individually configured items (e.g. a text input, select box and email address).

Useful references for extending the core form object and associated widget:

• Form builder: form (Preside Object)
• Form builder form: add form
• Form builder form: edit form
• Widget configuration form: Form builder form

Form items and item types

Form items are what provide the input and display definition of the form. i.e. a form without any items will be essentially invisible. Content editors can drag and drop item types into their form definition; they can then configure and reorder items within the form definition. The configuration options and display of the item will differ for different item types.

The core system provides a basic set of item types whose configuration can be modified and extended by your application or extensions. You are also able to introduce new item types in your application or extensions.

See Form Builder item types for more detail.

Form actions

Form actions are configurable triggers that are fired once a form has been submitted. The core system comes with a single 'Email' action that allows the CMS administrator to configure email notification containing the form submission.

Developers can create their own custom actions that are then available to content editors to add to their forms. See Form Builder actions for more detail.

Form builder permissioning

Access to the Form Builder admin system can be controlled through the CMS permissioning system. The following access keys are defined:

• formbuilder.navigate
• formbuilder.addform
• formbuilder.editform
• formbuilder.lockForm
• formbuilder.activateForm
• formbuilder.deleteSubmissions
• formbuilder.editformactions

In addition, a formbuildermanager role is defined that has access to all form builder operations:

settings.adminRoles.formbuildermanager = [ "formbuilder.*" ];

Finally, by default, the contentadministrator role has access to all permissions with the exception of lock and activate form.

Defining more restricted roles

In your own application, you could provide more fine tuned form builder access rules with configuration along the lines of the examples below:

// Adding perms to an existing role
settings.adminRoles.contenteditor.append( "formbuilder.*"                  );
settings.adminRoles.contenteditor.append( "!formbuilder.lockForm"          );
settings.adminRoles.contenteditor.append( "!formbuilder.activateForm"      );
settings.adminRoles.contenteditor.append( "!formbuilder.deleteSubmissions" );

// defining a new role
settings.adminRoles.formbuilderviewer = [ "formbuilder.navigate" ];