Note: This tutorial series is intended for advanced users. An advanced understanding of coding in PHP and JavaScript is required.

Advanced fields are automatically added to all modules 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() module’s PHP class method. To opt out of an advanced field, 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

<?php

class SIMP_SimpleHeader extends ET_Builder_Module {

	// Example 1: Include Background Field using its default configuartion
	public function get_advanced_fields_config() {
		return array();
	}

	// Example 2: Include Background Field using a custom configuartion
	public function get_advanced_fields_config() {
		return array(
			'background' => array(
				'options' => array(
					'background_color' => array(
						'default'          => et_builder_accent_color(),
					),
				),
			),	
		);
	}
	
	// Example 3: Do not include Background Field
	public function get_advanced_fields_config() {
		return array(
			'background' => false,
		);
	}
}

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 with adjustable border settings.

The border field configuration for the module’s outermost container element is set under the default key.

While only parameters specific to border fields are shown below, all 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) — The default value for border-radius.
    Format: link|top-left|top-right|bottom-right|bottom-left
    Example: on|3px|3px|3px|3px
  - border_styles (array) — The default values for border-style properties
    width (string) — The default value for border width
    color (string) — The default value for border color
    style (string) — The default value for the 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

<?php

class SIMP_SimpleHeader extends ET_Builder_Module {

	// Example 1: Include Borders Field using its default configuartion
	public function get_advanced_fields_config() {
		return array();
	}

	// Example 2: Include Borders Field using a custom configuartion
	public function get_advanced_fields_config() {
		return array(
			'borders' => array(
				'default' => array(
					'css'      => array(
						'main' => array(
							'border_styles' => "{$this->main_css_element}.simp-custom-class",
						),
					),
					'defaults' => array(
						'border_radii' => 'on|3px|3px|3px|3px',
					),
				),
			),
		);
	}
	
	// Example 3: Do not include Borders Field
	public function get_advanced_fields_config() {
		return array(
			'borders' => false,
		);
	}
}

Box Shadow (`box_shadow`)

The box-shadow field allows users to set the module’s box shadow.

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 with 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 specific to the box shadow field are shown below, all 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

<?php

class SIMP_SimpleHeader extends ET_Builder_Module {

	// Example 1: Include Box Shadow Field using its default configuartion
	public function get_advanced_fields_config() {
		return array();
	}

	// Example 2: Include Box Shadow Field using a custom configuartion
	public function get_advanced_fields_config() {
		return array(
			'box_shadow' => array(
				'default' => array(
					'css' => array(
						'main' => "{$this->main_css_element}.simp-custom-class",
					),
				),
			),
		);
	}
	
	// Example 3: Do not include Box Shadow Field
	public function get_advanced_fields_config() {
		return array(
			'box_shadow' => false,
		);
	}
}

Button (`button`)

The button field handles the various settings for customizing the styling of buttons included in a module on the front end.

Unlike the advanced field types, the Button field is only added to a module if it 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 front end.

Each key in the configuration represents a separate button that can be customized in the module’s settings. While only parameters specific to the button field are shown below, all 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 the 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 a field for customizing the button links rel attribute
- use_alignment (bool) — Show button alignment setting

Button Field Configuration Examples

<?php

class SIMP_SimpleHeader extends ET_Builder_Module {

	// Example 1: Include Button Field using its default configuartion
	public function get_advanced_fields_config() {
		return array();
	}

	// Example 2: Include Button Field using a custom configuartion
	public function get_advanced_fields_config() {
		return array(
			'button' => array(
				'primary_button' => array(
					'box_shadow'    => array(
						'css' => array(
							'main' => "{$this->main_css_element} .simp-button--primary",
						),
					),
					'css'           => array(
						'plugin_main' => "{$this->main_css_element} .simp-button--primary",
						'alignment'   => "{$this->main_css_element} .simp-button-wrapper",
					),
					'label'         => esc_html__( 'Primary Button', 'simp-simple' ),
					'use_alignment' => true,
				),
			),
		);
	}
	
	// Example 3: Do not include Button Field
	public function get_advanced_fields_config() {
		return array(
			'button' => false,
		);
	}
}

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 the field when a 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

<?php

class SIMP_SimpleHeader extends ET_Builder_Module {

	// Example 1: Include Filters Field using its default configuartion
	public function get_advanced_fields_config() {
		return array();
	}

	// Example 2: Include Filters Field using a custom configuartion
	public function get_advanced_fields_config() {
		return array(
			'filters' => array(
				'child_filters_target' => array(
					'tab_slug'    => 'advanced',
					'toggle_slug' => 'image',
				),
				'css'                  => array(
					'main' => '%%order_class%%',
				),
			),
		);
	}
	
	// Example 3: Do not include Filters Field
	public function get_advanced_fields_config() {
		return array(
			'filters' => false,
		);
	}
}

Fonts (`fonts`)

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

Fonts Field Configuration

Modules allow text styles to be adjusted to their outermost container element and elements inside it.

Each key in the configuration represents a separate element with adjustable text style settings.

The font field configuration for the module’s outermost container element is set under the module key.

While only parameters specific to the fonts field are shown below, all 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 a dependency has this value
- disable_toggle (bool) — Don’t add a toggle group to the settings modal
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 the line height setting
hide_text_color (bool) — Don’t show text color setting
hide_text_shadow (bool) — Don’t show text-shadow setting
sub_toggle (string) — Modal sub-toggle group slug

Fonts Field Configuration Examples

<?php

class SIMP_SimpleHeader extends ET_Builder_Module {

	// Example 1: Include Fonts Field using its default configuartion
	public function get_advanced_fields_config() {
		return array();
	}

	// Example 2: Include Fonts Field using a custom configuartion
	public function get_advanced_fields_config() {
		return array(
			'fonts' => array(
				'body'   => array(
					'css'   => array(
						'line_height' => "{$this->main_css_element} p",
						'plugin_main' => "{$this->main_css_element} p",
						'text_shadow' => "{$this->main_css_element} p",
					),
					'label' => esc_html__( 'Body', 'simp-simple' ),
				),
				'header' => array(
					'css'          => array(
						'main'      => "{$this->main_css_element} h2, {$this->main_css_element} h1, {$this->main_css_element} h3, {$this->main_css_element} h4, {$this->main_css_element} h5, {$this->main_css_element} h6",
						'important' => 'all',
					),
					'header_level' => array(
						'default' => 'h2',
					),
					'label'        => esc_html__( 'Title', 'simp-simple' ),
				),
			),
		);
	}
	
	// Example 3: Do not include Fonts Field
	public function get_advanced_fields_config() {
		return array(
			'fonts' => false,
		);
	}
}

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

<?php

class SIMP_SimpleHeader extends ET_Builder_Module {

	// Example 1: Include Margin & Padding Field using its default configuartion
	public function get_advanced_fields_config() {
		return array();
	}

	// Example 2: Include Margin & Padding Field using a custom configuartion
	public function get_advanced_fields_config() {
		return array(
			'margin_padding' => array(
				'css' => array(
					'important' => 'all',
				),
			),
		);
	}
	
	// Example 3: Do not include Margin & Padding Field
	public function get_advanced_fields_config() {
		return array(
			'margin_padding' => false,
		);
	}
}

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

<?php

class SIMP_SimpleHeader extends ET_Builder_Module {

	// Example 1: Include Max Width Field using its default configuartion
	public function get_advanced_fields_config() {
		return array();
	}

	// Example 2: Include Max Width Field using a custom configuartion
	public function get_advanced_fields_config() {
		return array(
			'max_width' => array(
				'css' => array(
					'module_alignment' => "{$this->main_css_element}.simp-custom-class",
				),
			),
		);
	}
	
	// Example 3: Do not include Max Width Field
	public function get_advanced_fields_config() {
		return array(
			'max_width' => false,
		);
	}
}

All Advanced Fields Configuration Examples

<?php

class SIMP_SimpleHeader extends ET_Builder_Module {

	// Example 1: Include all advanced fields using their default configuartion
	public function get_advanced_fields_config() {
		return array();
	}

	// Example 2: Include all advanced fields using custom configuartions
	public function get_advanced_fields_config() {
		return array(
			'background'     => array(
				'options' => array(
					'background_color' => array(
						'default'          => et_builder_accent_color(),
					),
				),
			),
			'borders'        => array(
				'default' => array(
					'css'      => array(
						'main' => array(
							'border_styles' => "{$this->main_css_element}.simp-custom-class",
						),
					),
					'defaults' => array(
						'border_radii' => 'on|3px|3px|3px|3px',
					),
				),
			),
			'box_shadow'     => array(
				'default' => array(
					'css' => array(
						'main' => "{$this->main_css_element}.simp-custom-class",
					),
				),
			),
			'button'         => array(
				'primary_button' => array(
					'box_shadow'    => array(
						'css' => array(
							'main' => "{$this->main_css_element} .simp-button--primary",
						),
					),
					'css'           => array(
						'plugin_main' => "{$this->main_css_element} .simp-button--primary",
						'alignment'   => "{$this->main_css_element} .simp-button-wrapper",
					),
					'label'         => esc_html__( 'Primary Button', 'simp-simple' ),
					'use_alignment' => true,
				),
			),
			'filters'        => array(
				'child_filters_target' => array(
					'tab_slug'    => 'advanced',
					'toggle_slug' => 'image',
				),
				'css'                  => array(
					'main' => '%%order_class%%',
				),
			),
			'fonts'          => array(
				'body'   => array(
					'css'   => array(
						'line_height' => "{$this->main_css_element} p",
						'plugin_main' => "{$this->main_css_element} p",
						'text_shadow' => "{$this->main_css_element} p",
					),
					'label' => esc_html__( 'Body', 'simp-simple' ),
				),
				'header' => array(
					'css'          => array(
						'main'      => "{$this->main_css_element} h2, {$this->main_css_element} h1, {$this->main_css_element} h3, {$this->main_css_element} h4, {$this->main_css_element} h5, {$this->main_css_element} h6",
						'important' => 'all',
					),
					'header_level' => array(
						'default' => 'h2',
					),
					'label'        => esc_html__( 'Title', 'simp-simple' ),
				),
			),
			'margin_padding' => array(
				'css' => array(
					'important' => 'all',
				),
			),
			'max_width'      => array(
				'css' => array(
					'module_alignment' => "{$this->main_css_element}.simp-custom-class",
				),
			),
		);
	}
	
	// Example 3: Do not include any advanced fields
	public function get_advanced_fields_config() {
		return array(
			'background'     => false,
			'borders'        => false,
			'box_shadow'     => false,
			'button'         => false,
			'filters'        => false,
			'fonts'          => false,
			'margin_padding' => false,
			'max_width'      => false,
		);
	}
}

How To Create A Divi Builder Module

Defining Module Settings

Defining Custom CSS Fields For Modules

Settings Field Visibility

How To Create a Custom Field For a Divi Builder Module

Background (background)