CMDG 14: Create custom fields

In addition to creating custom modules, developers can also define custom fields for use in settings forms using their own HTML.

Note: Creating custom fields significantly changed in 2.0 as we moved to purely JavaScript based settings forms. The old 1.x method still works, but it will significantly slow down the loading of your forms as they'll need to be rendered on the server in PHP.

Create custom field files

Create a new PHP or HTML file for your custom field. This file should contain markup for an Underscores JavaScript template in the same flavor that WordPress core uses for wp.template. If you're not familiar with those type of templates, read up on Underscores templates and wp.template.

Note: You do not need to wrap your template in <script></script> tags with an ID. Beaver Builder will handle that for you.

Inside your field file you will have access to the following properties on the data object.

data.field object
The config that you defined for this field in your module's PHP file.

data.globalSettings object
The global settings object for Beaver Builder.

data.name string
The name (or key) for this field as it will be stored on the settings object when saved.

data.settings object
The saved settings for the form this field is a part of.

data.value string
The saved value for this field.

Using those properties, you can create any type of field markup that you wish. Just make sure something is using the data.name and data.value properties so it can be properly saved. Here is an example of a simple text field file.

Register custom field files

Once you have created your custom field files, you'll need to register them using the fl_builder_custom_fields filter. That filter will pass a $fields array to your callback function with the array keys being the field types and the array values being the paths to the fields. The field type you enter will be what you need to use in your module's form config to use that field.

Note: Your field type should be prefixed so it doesn't clash with core field types or other custom fields. For example, if you have a field type toggle, it should be my-toggle in case the core plugin ever introduces a toggle field type.

Register your custom fields to be autoloaded by Beaver Builder, as shown below.

After you have registered your custom field file, it can be used in your module settings as follows.

Enqueue custom field assets

Developers may also wish to enqueue CSS and JavaScript assets for their fields while Beaver Builder is active. This is done in the same way you typically enqueue assets, except that the enqueue calls are wrapped in an if statement that checks to see if Beaver Builder is active:

Previous:
13. Sanitize field values
Next: 
15. Helpers