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.
- Align field
- Border field
- Button Group field
- Code field
- Color field
- Date field
- Dimension field
- Editor field
- Font field
- Form field
- Gradient field
- Icon field
- Link field
- Loop settings fields
- Multiple audios field
- Multiple photos field
- Photo field
- Photo sizes field
- Post type field
- Raw HTML field
- Select field
- Service fields
- Shadow field
- Suggest field
- Text field
- Textarea field
- Time field
- Time zone field
- Typography field
- Unit field
- Video field
The align field displays a button group used to select either left, center or right values. The following screenshot shows the Alignment field button group in the UI and what the choices are:
You can also set custom return values using the optional
values param as shown in the example.
Returns left, center or right unless custom values have been defined.
Here is an example of an align field with custom return values.
The border field displays a compound field with inputs for constructing borders. Using our live preview system will take care of the complexities of previewing the border field for you.
An array of border data.
To render the CSS for your border field, use the
FLBuilderCSS::border_field_rule helper method in your
frontend.css.php file as shown below.
Button Group field
The button group field displays a group of buttons for selecting a single value when one of the buttons is clicked. Only one button can be selected at a time. When no button is selected, the default setting applies. Here's a screenshot example of a button group used in the Typography section.
The selected string value.
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.
A date/time string.
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 dimension field type allows custom unit selects and popup value sliders. See the code examples for the unit field.
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 gradient field displays a compound field with color, stop, type, angle, and position inputs for constructing a gradient. Using our live preview system will take care of the complexities of previewing the gradient field for you.
An array of gradient data.
To render the CSS for your gradient field, use the
FLBuilderColor::gradient helper method in your
frontend.css.php as shown below.
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
You can toggle other fields like the select field type using the
show value, as seen in the following code example.
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.
You can show Target or No Follow checkboxes without having to code those fields yourself. The following screenshot shows how they appear in the UI.
To enable these checkboxes, set the
show_nofollow values to
true in your field config, as shown in the following code example.
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.
Raw HTML field
The raw HTML field displays raw HTML specified using the
content param. It does not return a value to your settings because it is only meant for output, not input.
This field does not return a value.
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 shadow field displays a compound field with inputs for constructing a shadow effect. Using our live preview system will take care of the complexities of previewing the shadow field for you.
An array of shadow data.
To render the CSS for your shadow field, use the
FLBuilderColor::shadow helper method in your
frontend.css.php file as shown below.
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. There is an optional
maxlength key-value pair, shown in this example, and you can set any value you want. Beaver Builder has no maximum number of characters in its textareas, but you can use
maxlength if you want to limit the number of characters that a user can enter.
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 typography field displays a compound field with font, style, spacing, and shadow inputs for customizing the look of text.
Using our live preview system will take care of the complexities of previewing the typography field for you.
An array of typography data.
To render the CSS for your typography field, use the
FLBuilderCSS::typography_field_rule helper method in your
frontend.css.php file as shown below.
The unit field displays a text input for entering a number.
The number entered by the user.
Custom unit select
You can add a custom unit select (such as px, vh, %) to unit fields. These selects allow you to choose from a predefined list of values, as shown below. When using custom unit selects, you don't have to define the unit in your preview config, also shown below.
Settings with a custom unit select will receive a related setting with the
_unit suffix, as shown in the example below. Together with the original setting, you can build the full value.
Note: If you choose to set only one value for your custom unit select (such as
px), it will still show up but won't be a selectable field.
Popup value slider
You can enable a popup slider control for unit fields when they are focused. This lets users change the values using a slider instead of the keyboard.
To enable the popup slider for a field, simply set the
slider value in your field config to
Examples of more advanced setups are shown below, allowing you to customize the
step values for the slider. If you are using custom units, you can customize the values for each unit as well.
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