CMDG 10: Setting fields reference
Note: Don't use either the
connection key in a setting field. Those two keys are reserved for internal use.
- Code field
- Color field
- Dimension field
- Editor field
- Font field
- Form field
- Icon field
- Link field
- Loop settings fields
- Multiple audios field
- Multiple photos field
- Photo field
- Photo sizes field
- Post type field
- Select field
- Service fields
- Suggest field
- Text field
- Textarea field
- Time field
- Time zone field
- Unit field
- Video field
The code field displays an Ace editor for working with code.
A string containing the user-submitted code.
The color field displays a color picker that can be used to pick a custom color. If
show_reset is set to true, users will also be able to clear the color which results in an empty value. You can also set
show_alpha to true to show the alpha slider in the picker.
The hexadecimal color value excluding the hash (#) sign.
The dimension field displays four number inputs for top, right, bottom, and left values.
The dimension field doesn’t return a single value on your
$settings object. Instead, it will return four values corresponding to top, right, bottom, and left, using the key for your setting as a prefix. For example, if my setting has a key of
margin, the values returned will be as follows
The dimension field is configured as follows.
The editor field displays a WordPress editor that can be used to insert text just as you would on the post edit screen. If
media_buttons is set to true, the Add Media button will be available above the editor.
The HTML content generated by the editor.
If you would like to enable oEmbed in your editor fields, set the
wpautop param to
false and output your text in frontend.php like so...
The font field displays a select for choosing a font family and a select for choosing a corresponding weight.
An array with the family and weight values as shown below.
A form field is a nested form that can be launched from within an existing form. For a live example of this, check out the Items tab of the Accordion module. There you will see that when you click the Edit Item link, a nested form is displayed for you to edit that particular item.
Note: You can't nest form fields.
An object containing a property for each of the settings defined in the form.
In order to use the form field, you must have a form defined. That is done similar to registering a module but instead uses the
FLBuilder::register_settings_form method. That method takes your form ID as well as an array of form config data (again similar to a module's form).
Once you have a form defined, you can reference it in your field's config array by setting the
form value to the ID of the form you registered. You should also set the
preview_text value to the ID of a field that is defined in your form.
The icon field displays an icon selector that can be used to pick a custom icon. If
show_remove is set to true, users will also be able to clear the icon which results in an empty value.
The icon class names, such as
The link field displays a text input for entering a URL and a select button that shows a dialog when clicked for selecting a post of any type to link to.
The link entered by the user.
Loop settings fields
Loop settings aren't actually a single field but a collection of fields that make up a tab in the settings panel. That tab allows users to select things like Post Type, Order, Terms and more that you can use to create a WordPress loop using the
All of the values for the loop settings will be stored in your module's settings object. You shouldn't need to access those settings directly (although you can if you want to). Instead, just pass them to the
FLBuilderLoop::query method, as shown below, and it will take care of everything for you.
To use the loop settings, simply create a new tab array that links to the loop-settings.php file instead of defining sections and fields like a standard tab array.
When a user saves your module, you can create a loop in your frontend.php file, as follows:
You can also display pagination for your loop:
Multiple audios field
The multiple audios field displays a WordPress media lightbox that allows users to select multiple audio files.
A JSON-encoded array of attachment IDs for each audio file selected.
Multiple photos field
The multiple photos field displays a WordPress media lightbox that allows users to select multiple photos.
A JSON encoded array of attachment ids for each photo selected.
The photo field displays a WordPress media lightbox that allows users to select a single photo.
The attachment ID for the selected photo. In addition to the attachment ID, the photo field also provides the photo URL as a separate variable in your module's settings object. That variable has the same name as your photo field with the suffix
_src appended to it, such as
my_photo_field_src. This is useful if all you need is the URL and don't need to deal with the attachment ID or data. If
show_remove is set to true, users will also be able to clear the photo which results in an empty value.
Photo sizes field
The photo sizes field displays a select input containing the available WordPress photo sizes as values.
The photo size string that can be used in functions such as
the_post_thumbnail($size) to retrieve a specific photo size.
Post type field
The post type field displays a select input containing the available WordPress post types as values.
The post type slug, such as post or page.
The select field displays a standard HTML select input. Select fields can also be setup to show/hide other tabs, sections and fields within your settings by using the toggle array as shown in the example below. If the value selected by the user matches one defined in your toggle array, those tabs, sections and fields will be shown; otherwise, they will be hidden.
The value selected by the user.
You can also make a select field that has the ability to select multiple values by setting the multi-select config value to true as shown below. If that is set, this field will return an array of selected values.
The service field isn't actually a single field but a collection of fields that make up a section in a settings form tab. These fields allow users to enter account information for a specific service (such as MailChimp) and save API connection data. You can then use the saved data in your modules to do things such as subscribe someone to a mailing list.
The values for the service fields will be stored in your module's settings object.
To use the service fields, simply create a new section array that links to the service-settings.php file instead of defining fields like a standard section array. You also need to define the type of services that you would like available in the services list. Beaver Builder currently supports the
Once your module is saved, you can access the service instance:
You can also access the saved account data by doing the following...
The suggest field displays a text input that returns a list of suggested results as the user types. It is currently designed to work with posts (of any type), terms (tags, categories, etc.), users and links (to a post of any type).
The action value of the config array currently accepts one of four values...
fl_as_posts- Search posts. The data value of the config array must be the slug of the post type you want to search. Returns an array of post IDs.
fl_as_terms- Search terms. The data value of the config array must be the slug of the term you want to search. Returns an array of term IDs.
fl_as_users- Search users. Returns an array of user IDs.
fl_as_links- Search links. Returns an array of permalinks.
A string of comma-separated values that the user has selected.
The text field displays a standard HTML text input.
The text entered by the user.
The textarea field displays a standard HTML textarea input.
The text entered by the user.
The time field displays inputs for selecting the hour, minutes and period of the day (am/pm).
An array containing the hour, minutes and period.
Once your module is saved, you can access the values:
Time zone field
The time zone field displays an input for selecting a specific time zone.
The time zone string.
The unit field displays a text input for entering a number.
The number entered by the user.
The video field displays a WordPress media lightbox that allows users to select a single video.
The attachment id for the selected video.
9. Module method reference
11. Responsive fields reference