CMDG 10: Setting fields reference

Note: Don't use either the type or connection key in a setting field. Those two keys are reserved for internal use.

Code field

The code field displays an Ace editor for working with code.

Return value
A string containing the user-submitted code.

Color field

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.

Return value
The hexadecimal color value excluding the hash (#) sign.

Dimension field

The dimension field displays four number inputs for top, right, bottom, and left values.

Return value
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.

Editor 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.

Return value
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...

Font field

The font field displays a select for choosing a font family and a select for choosing a corresponding weight.

Return value
An array with the family and weight values as shown below.

Form field

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.

Return value
An object containing a property for each of the settings defined in the form.

Usage
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.

Icon field

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.

Return value
The icon class names, such as fa fa-flag.

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.

Return value
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 FLBuilderLoop::query method.

Return value
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.

Usage
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.

Return value
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.

Return value
A JSON encoded array of attachment ids for each photo selected.

Photo field

The photo field displays a WordPress media lightbox that allows users to select a single photo.

Return value
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.

Return value
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.

Return value
The post type slug, such as post or page.

Select field

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.

Return value
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.

Service fields

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.

Return value
The values for the service fields will be stored in your module's settings object.

Usage
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 autoresponder type.

Once your module is saved, you can access the service instance:

You can also access the saved account data by doing the following...

Suggest field

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.

Return value
A string of comma-separated values that the user has selected.

Text field

The text field displays a standard HTML text input.

Return value
The text entered by the user.

Textarea field

The textarea field displays a standard HTML textarea input.

Return value
The text entered by the user.

Time field

The time field displays inputs for selecting the hour, minutes and period of the day (am/pm).

Return value
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.

Return value
The time zone string.

Unit field

The unit field displays a text input for entering a number.

Return value
The number entered by the user.

Video field

The video field displays a WordPress media lightbox that allows users to select a single video.

Return value
The attachment id for the selected video.

Previous:
9. Module method reference
Next: 
11. Responsive fields reference