Developer Documentation

Return To Developer Documentation

Advanced Field Types For Module Settings

Learn about the Advanced Field types for module settings.

Note: This tutorial series is intended for advanced users. At least a basic understanding of coding in PHP and JavaScript is required.

Advanced fields are added automatically to all modules that are compatible with the latest version of the Divi Builder unless they specifically opt-out. Most advanced fields are configurable. Configuration for advanced fields can be defined in the get_advanced_fields_config() method of the module’s PHP class. To opt-out of an advanced field, simply set its key in the array to false.

Background (background)

The background field allows users to set the module’s background color, gradient, image, and/or video.

Background Field Configuration

  • css (array) — CSS style configuration
    • important (bool) — Whether or not styles should include !important
    • main (string) — CSS selector for the module’s main element
  • options (array) — Field definition parameter overrides
    • module_setting_slug (array)
      • parameter_1 (mixed) — Parameter value
      • parameter_2 (mixed) — Parameter value
  • settings (array)
    • disable_toggle (bool) — Don’t add a Background toggle group to the settings modal
    • tab_slug (string) — Modal tab slug
    • toggle_slug (string) — Modal tab settings group toggle slug
  • use_background_color (bool|string) — Show the background color tab
  • use_background_color_gradient (bool|string) — Show the background gradient tab
  • use_background_image (bool|string) — Show the background image tab
  • use_background_video (bool|string) — Show the background video tab

The accepted values for use_background_color, use_background_color, use_background_gradient, use_background_image, and use_background_video are:

  • true — Display fields in the module settings and handle frontend markup
  • false — Do not display fields in the module settings and don’t handle frontend markup
  • fields_only — Display fields in the module settings but don’t handle frontend markup

Background Field Configuration Examples

Borders (borders)

The borders field allows users to set the module’s border style, color, width, & radius.

Border Field Configuration

Modules can apply borders not only to their outermost container element, but also to elements inside it. Each key in the configuration represents a separate element that will have adjustable border settings. The border field configuration for the module’s outermost container element is set under the default key.

While only parameters that are specific to borders fields are shown below, all of the common field parameters are supported.

  • default (array)
    • css (array) — CSS style configuration
      • main (array) — CSS selectors for the module’s main element
        • border_radii (string) — CSS selector to be used for border radius styles
        • border_styles (string) — CSS selector to be used for border styles
    • defaults (array)
      • border_radii (string) — Default value for border radius.
        Format: link|top-left|top-right|bottom-right|bottom-left
        Example: on|3px|3px|3px|3px
      • border_styles (array) — Default values for border style properties
        • width (string) — Default value for border width
        • color (string) — Default value for border color
        • style (string) — Default value for border style
    • label_prefix (string) — Text to display in front of the setting label (localized)
    • suffix (string) — Suffix to append to the setting slug. Not required for default border field

Borders Field Configuration Examples

Box Shadow (box_shadow)

The box shadow field allows users to set the module’s box shadow (obviously 😉 ).

Box Shadow Field Configuration

Modules can apply box shadows not only to their outermost container element, but also to elements inside it. Each key in the configuration represents a separate element that will have adjustable box shadow settings. The box shadow field configuration for the module’s outermost container element is set under the default key.

While only parameters that are specific to the box shadow field are shown below, all of the common field parameters are supported.

  • default (array)
    • css (array) — CSS style configuration
      • custom_style (bool) — Use custom styles generation instead of the default
      • important (bool) — Whether or not styles should include !important
      • main (string) — CSS selector for the module’s main element
      • show_if (array) — Output styles if certain settings have certain values
        • setting_slug (mixed) — Setting value
      • show_if_not (array) — Output styles if certain settings do not have certain values
        • setting_slug (mixed) — Setting value
    • suffix (string) — Suffix to append to the setting slug. Not required for default field.

Box Shadow Field Configuration Examples

Button (button)

The button field handles all of the various settings for customizing the styling of buttons included in a module on the frontend. Unlike the other advanced field types, the Button field is not added to a module unless the module specifically opts-in by including it in its advanced fields configuration.

Button Field Configuration

Modules can include one or more Divi styled buttons in their HTML output on the frontend. Each key in the configuration represents a separate button that can be customized in the module’s settings. While only parameters that are specific to the button field are shown below, all of the common field parameters are supported.

  • button_slug (array)
    • box_shadow (array) — See Box Shadow Field for array structure
    • css (array) — CSS style configuration
      • alignment (string) — CSS selector for alignment styles
      • main (string) — CSS selector for the module’s main element
      • plugin_main (string) — Like main above but applies only with the Divi Builder Plugin
    • disable_toggle (bool) — Don’t add a Button toggle group to the settings modal
    • no_rel_attr (bool) — Don’t show field for customizing the button link’s rel attribute
    • use_alignment (bool) — Show button alignment setting

Button Field Configuration Examples

Filters (filters)

The filters field allows users to control CSS filters for the module.

Filters Field Configuration

  • child_filters_target (array) — Child element filters field configuration
    • depends_show_if (mixed) — Only show field when dependency has this value
    • tab_slug (string) — Modal tab slug
    • toggle_name (string) — Modal toggle group display name (localized)
    • toggle_slug (string) — Modal toggle group slug
  • tab_slug (string) — Modal tab slug
  • toggle_name (string) — Modal toggle group display name (localized)
  • toggle_slug (string) — Modal toggle group slug

Filters Field Configuration Examples

Fonts (fonts)

The fonts field handles all the settings related to customizing the styles for text that appears in the module on the frontend.

Fonts Field Configuration

Modules allow text styles to be adjusted not only to their outermost container element, but also to elements inside it. Each key in the configuration represents a separate element that will have adjustable text style settings. The fonts field configuration for the module’s outermost container element is set under the module key.

While only parameters that are specific to the fonts field are shown below, all of the common field parameters are supported.

  • module (array)
    • defaults (array) — Default values for settings
      • setting_slug_1 (mixed) — Default value
      • setting_slug_2 (mixed) — Default value
    • depends_show_if (mixed) — Only show settings when dependency has this value
    • disable_toggle (bool) — Don’t add a toggle group to the settings modal
    • font (array) — Font family field definition (accepts common field parameters)
      • sub_toggle (string) — Modal sub-toggle group slug
    • font_size (array) — Font size field definition (accepts common field parameters)
      • sub_toggle (string) — Modal sub-toggle group slug
    • header_level (array) — Header level field definition (accepts common field parameters)
      • sub_toggle (string) — Modal sub-toggle group slug
    • hide_font (bool) — Don’t show font family setting
    • hide_font_size (bool) — Don’t show font size setting
    • hide_letter_spacing (bool) — Don’t show letter spacing setting
    • hide_line_height (bool) — Don’t show line height setting
    • hide_text_color (bool) — Don’t show text color setting
    • hide_text_shadow (bool) — Don’t show text shadow setting
    • letter_spacing (array) — Letter spacing field definition (accepts common field parameters)
      • sub_toggle (string) — Modal sub-toggle group slug
    • line_height (array) — Line height field definition (accepts common field parameters)
      • sub_toggle (string) — Modal sub-toggle group slug
    • sub_toggle (string) — Modal sub-toggle group slug
    • text_color (array) — Text color field definition (accepts common field parameters)
      • sub_toggle (string) — Modal sub-toggle group slug
    • text_shadow (array) — Text shadow field definition (accepts common field parameters)
      • sub_toggle (string) — Modal sub-toggle group slug

Fonts Field Configuration Examples

Margin & Padding (margin_padding)

The margin & padding field handles settings for the module’s margin & padding.

Margin & Padding Field Configuration

  • custom_margin (array) — Margin field definition parameter overrides
    • parameter_1 (mixed) — Parameter value
    • parameter_2 (mixed) — Parameter value
  • custom_padding (array) — Padding field definition parameter overrides
    • parameter_1 (mixed) — Parameter value
    • parameter_2 (mixed) — Parameter value
  • disable_toggle (bool) — Don’t add a toggle group to the settings modal
  • use_margin (bool) — Show the margin settings
  • use_padding (bool) — Show the padding settings

Margin & Padding Field Configuration Examples

Max Width (max_width)

The max width field handles settings for the module’s max-width and alignment.

Max Width Field Configuration

  • options (array) — Field definition parameter overrides
    • module_setting_slug (array)
      • parameter_1 (mixed) — Parameter value
      • parameter_2 (mixed) — Parameter value
  • toggle_priority (int) — The priority for the modal toggle group
  • toggle_title (string) — The display name for the modal toggle group (localized)
  • use_max_width (bool) — Show the max width setting
  • use_module_alignment (bool) — Show the alignment setting

Max Width Field Configuration Examples

All Advanced Fields Configuration Examples

500,591 Customers Are Already Building Amazing Websites With Divi. Join The Most Empowered WordPress Community On The Web

We offer a 30 Day Money Back Guarantee, so joining is Risk-Free!

Sign Up Today