How To Install Your Divi Builder WordPress Plugin

How To Install Your Divi Builder WordPress Plugin
Installing our plugins is a snap using the WordPress Dashboard plugin installer.

Download Your Plugin

To update your new plugin, you must first upload it to your WordPress website via the WordPress dashboard. When you download the Divi Builder from the Elegant Themes Member』s Area, you will be be given a file called divi-builder.zip. Some browsers (such as Safari on OSX) will automatically unzip that folder for you. In this case, you will need to re-size the divi-builder folder by right clicking the folder and compressing it. Once you have located your divi-builder.zip file, you are read to upload it to your WordPress website.
Log in to your WordPress Dashboard and click the Plugins > Add New link. This will bring you to the WordPress plugins page.
Upload Your Plugin

After the plugins page in your dashboard has loaded, locate the 「Upload Plugin」 button towards the top of the screen. Click this button to proceed to the next step.
Choose Your Plugin ZIP File

After clicking 「Upload Plugin,」 you will be taken to a new page where you can select the plugin that you would like to install. In this case, we will be installing the divi-builder.zip file that you downloaded earlier. Click the 「Choose File」 button to open a local browser window.
Upload And Activate

You will need to browse your local machine and find the divi-builder.zip file. You will often find it in your Downloads folder, but it depends on your browser settings. Once you have located the file, select it and click the Open button. Next click the 「Install」 button to install the divi-builder.zip folder that you have just selected. After the plugin has been uploaded you will be taken to a confirmation page where you can activate the plugin. Click the 「activate」 button and you are good to go!

How To Create a Custom Field For a Divi Builder Module

How To Create a Custom Field For a Divi Builder Module
Note: This tutorial series is intended for advanced users. At least a basic understanding of coding in PHP and JavaScript is required. Custom Fields for Divi Module Settings Creating a custom field for a Divi module is similar to creating a custom Divi module in the Divi Builder. Both methods require some Javascript, HTML, & […]

Note: This tutorial series is intended for advanced users. At least a basic understanding of coding in PHP and JavaScript is required.
Custom Fields for Divi Module Settings
Creating a custom field for a Divi module is similar to creating a custom Divi module in the Divi Builder. Both methods require some Javascript, HTML, & CSS code. However, to create a custom field for a module, there is no need for any PHP because you don』t need to write a PHP class to render the HTML output on the frontend. The main component needed is a ReactJS component class that handles rendering the field inside of the Divi Builder. Then you can define the custom field on your module definition.
In this tutorial, you』ll learn how to create custom fields for a Divi Builder module that will be fully functional in the builder.
Getting Started
Keep in mind. Custom Divi Builder fields must be implemented within a theme, child-theme, or Divi Extension. In this tutorial, we』re going to create a custom field for a custom module in a Divi Extension.
Also, this tutorial is a continuation of previous tutorials that have a specific setup already in place.
If you haven』t already done so, go ahead and do the following before you start this tutorial:

Create a Divi Extension
Create a Custom Module.

Once done, you are ready to continue.
Run Yarn
Before we can test our custom field later on in the Divi Builder we』ll need to compile the JSX code into regular JavaScript. To do that, we need to run yarn. To do this, simply run the following command inside your plugin』s directory:
yarn start
IMPORTANT: Be sure that yarn start is running in the root folder of your plugin. Furthermore, you should keep yarn start running as you develop so that the files continue to compile successfully.
Upgrading Divi Scripts
Custom Divi Builder Fields is a new feature and only available on divi-scripts version 1.0.2 above. So, if you want to add custom field on your existing extension, please upgrade your divi-scripts to version 1.0.2. You can do this by changing divi-scripts version on your package.json located at at the root of your extension directory.

Then run yarn install to update. You can also find a custom field example on this documentation here.
Update Field Directory and File Names
We』ll get to update the code in our files in a bit. But before we can do that, we need to change the default directory and file names for our new custom field.
Look inside your extension』s directory and locate the example custom field located at /includes/fields/Input/Input.jsx.

We』ll use this as a starting point to create a custom input field.
First, rename the Input directory to SimpleInput.
Inside the directory (now named SimpleInput), rename the file Input.jsx to SimpleInput.jsx.
The path to the file should now be includes/fields/SimpleInput/SimpleInput.jsx

Update the Field File
Open the SimpleInput.jsx file and edit it as follows:
Update the React Component Class
For our custom field to be available and fully functional inside the Divi Builder we must create a React Component class that handles the rendering of our custom field based on its props.
By default, the component class is named Input. Change the name of the class Input to SimpleInput.
Then change the name Input to SimpleInput at the bottom of the file to reflect the new name of our component class in order to be exported for use.
Also make sure to update the slug, input id, and input className to reflect the name of the new field.
(NOTE: Depending on the prefix id you chose when setting up your Divi Extension, you may see different names for the static slug, input id, input class, etc. This example has the prefix simp which was chosen when creating the Divi Extension.)

Here is an example of what the code should look like after the change has been made:
// External Dependencies
import React, { Component } from 'react';

// Internal Dependencies
import './style.css';

class SimpleInput extends Component {

static slug = 'simp_simple_input';

/**
* Handle input value change.
*
* @param {object} event
*/
_onChange = (event) => {
this.props._onChange(this.props.name, event.target.value);
}

render() {
return(

);
}
}

export default SimpleInput;

The _onChange() prop is a method handler to save or remove the field setting』s value. It passes 2 parameters.

The first parameter is the field setting』s name. You can use name prop here because it』s already supplied with the correct field name based on the current active tab mode. For example: when you are editing the Title option in Tablet tab mode, the field』s name generated is title_tablet. The second parameter is the field setting value that you want to save.
The field setting type is actually a third parameter that is automatically defined with the current field type prop. So we don』t have to include that parameter with the other 2.
Update the index.js file for the Custom Field
Next, let』s update the import and export statements in the index.js file located at /includes/fields/index.js. To do this, open to edit the index.js file.
Replace all instances of the name for the class and directory (which is Input by default) to the new name SimpleInput.

Here is an example of the final code:
import SimpleInput from './SimpleInput/SimpleInput';

export default [SimpleInput];

Custom Field CSS Styles
Styles for our custom field can be defined using the style.css file in its directory located at /includes/fields/SimpleInput/style.css.

Our custom field is only a basic input element that comes with default builder styling. For now, let』s change the default class selector to .simp-simple-input (rendered in SimpleInput.jsx) throughout the style.css file:
input.simp-simple-input {
background: #f1f5f9;
max-height: 30px;
border: 0;
border-radius: 3px;
padding: 7px 10px;
box-sizing: border-box;
transition: background 200ms ease;
color: #4C5866;
font-family: 'Open Sans', Helvetica, Roboto, Arial, sans-serif;
font-size: 13px;
font-weight: 600;
line-height: normal;
display: block;
width: 100%;
}

input.simp-simple-input:focus {
background: #e6ecf2;
}

input.simp-simple-input::-webkit-input-placeholder {
color: #98a7b8;
}

input.simp-simple-input:-moz-placeholder {
color: #98a7b8;
}

input.simp-simple-input::-moz-placeholder {
color: #98a7b8;
}

input.simp-simple-input:-ms-input-placeholder {
color: #98a7b8;
}

input.simp-simple-input[readonly] {
background: #ffffff !important;
border: 1px solid #eaedf0 !important;
cursor: not-allowed;
}

Field Definition
To use our custom field, we need to define it on the module definition of our intended module. For this example, let』s add it to the Simple Header module we created in the previous tutorial.
Open the SimpleHeader.php file located at /includes/modules/SimpleHeader/SimpleHeader.php.
Then add the code to define the custom field. Don』t forget to use simp_simple_input as the field type.

The final code will look like this:
class SIMP_SimpleHeader extends ET_Builder_Module {

public $slug = 'simp_simple_header';
public $vb_support = 'on';

public function init() {
$this->name = esc_html__( 'Simple Header', 'simp-simple-extension' );
}

public function get_fields() {
return array(
'heading' => array(
'label' => esc_html__( 'Heading', 'simp-simple-extension' ),
'type' => 'text',
'option_category' => 'basic_option',
'description' => esc_html__( 'Input your desired heading here.', 'simp-simple-extension' ),
'toggle_slug' => 'main_content',
),
'content' => array(
'label' => esc_html__( 'Content', 'simp-simple-extension' ),
'type' => 'tiny_mce',
'option_category' => 'basic_option',
'description' => esc_html__( 'Content entered here will appear below the heading text.', 'simp-simple-extension' ),
'toggle_slug' => 'main_content',
),
'field' => array(
'label' => esc_html__( 'Custom Field', 'simp-simple-extension' ),
'type' => 'simp_simple_input',
'option_category' => 'basic_option',
'description' => esc_html__( 'Text entered here will appear inside the module.', 'simp-simple-extension' ),
'toggle_slug' => 'main_content',
),
);
}

public function render( $unprocessed_props, $content = null, $render_slug ) {
return sprintf(
'

%1$s

%2$s

',
esc_html( $this->props['heading'] ),
$this->props['content']
);
}
}

new SIMP_SimpleHeader;

The properties that were added to the field are only the required properties you need to define. But you can add more properties to use on the custom field if you want. For instance, you can add both responsive and hover options for your custom field as well.
Divi Builder and Frontend Output
Our field definition is ready. We just need to update the render() method so that it will display the custom field value. Let』s start with the render() method on the module PHP class.
Open the SimpleHeader.php file and update the render() method as follows:

The final code should look like this:
class SIMP_SimpleHeader extends ET_Builder_Module {

public $slug = 'simp_simple_header';
public $vb_support = 'on';

public function init() {
$this->name = esc_html__( 'Simple Header', 'simp-simple-extension' );
}

public function render( $unprocessed_props, $content = null, $render_slug ) {
return sprintf(
'

%1$s

%2$s

%3$s

',
esc_html( $this->props['heading'] ),
$this->props['content'],
$this->props['field']
);
}
}

new SIMP_SimpleHeader;

Now, let』s edit the render() method of the React component and make it produce the same output that we defined in our PHP render() method.
Open the SimpleHeader.jsx file and update the render() method as follows:

The final code should look like this:
// External Dependencies
import React, { Component, Fragment } from 'react';

// Internal Dependencies
import './style.css';

class SimpleHeader extends Component {

static slug = 'simp_simple_header';

render() {
return (

{this.props.heading}

{this.props.content()}

{this.props.field}

);
}
}

export default SimpleHeader;

Here you can see how the output of the render() method of the php file corresponds to the output of the render() method of the php file which now includes the new field wrapped in a p tag.

Add Selectors if Needed
Wrapping the new field output with a p tag makes sense here because we are interested in simple text output. This also is a good opportunity to add your own custom selectors (CSS ID, CSS Class) to the p tag for your own needs. Just make sure you add the same selectors to the output of the render() method of the PHP file and the JSX file.
Testing Your Custom Fields
If you already have yarn start running as we suggested in the first step, you can now launch the Divi Builder and check out your Simple Input field!
If not, before we can test our custom field in the Divi Builder we need to compile the JSX code into regular JavaScript. To do that, simply run the following command inside your plugin』s directory:
yarn start
As a reminder, you should keep yarn start running as you continue to edit your files so that the files continue to compile successfully.
To test out the custom field, go to your Divi site and open the settings of the custom Simple Header Module. The new Custom Field will be under the content tab.

Wrapping up
When you are finished development, remember to stop yarn start from running in your terminal (hitting ctrl + c within the terminal usually does the trick).

Divi Template Hooks

Divi Template Hooks
Learn about the hooks that are available in Divi』s template files.

footer.php
et_after_main_content
Fires after the main content, before the footer is output.
Type: Action
Since: 3.1

header.php
et_head_meta
Fires in the head, before wp_head() is called. This action can be used to insert elements into the beginning of the head before any styles or scripts.
Type: Action
Since: 1.0
et_html_top_header
Filters the HTML output for the top header.
Type: Filter
Since: 3.1

Param
Type
Description

$top_header
string
HTML output for the top header

et_html_slide_header
Filters the HTML output for the slide header.
Type: Filter
Since: 3.1

Param
Type
Description

$slide_header
string
HTML output for the slide header

et_html_logo_container
Filters the HTML output for the logo container.
Type: Filter
Since: 3.1

Param
Type
Description

$logo_container
string
HTML output for the logo container

et_header_top
Fires at the end of the et-top-navigation element, just before its closing tag.
Type: Action
Since: 1.0
et_html_main_header
Filters the HTML output for the main header.
Type: Filter
Since: 3.1

Param
Type
Description

$main_header
string
HTML output for the main header

et_before_main_content
Fires after the header, before the main content is output.
Type: Action
Since: 3.1

index.php
et_pb_index_blog_image_width
Filters the width used to retrieve featured images via wp_get_attachment_image_src().
Type: Filter
Since: 1.0

Param
Type
Description

$width
string
Width value as a string

et_pb_index_blog_image_height
Filters the height used to retrieve featured images via wp_get_attachment_image_src().
Type: Filter
Since: 1.0

Param
Type
Description

$height
string
Height value as a string

page.php
et_pb_index_blog_image_width
See index.php above for definition.
et_pb_index_blog_image_height
See index.php above for definition.

single.php
et_before_content
Fires right before the_content() is called.
Type: Action
Since: 1.0
et_pb_index_blog_image_width
See index.php above for definition.
et_pb_index_blog_image_height
See index.php above for definition.

single-project.php
et_pb_portfolio_single_image_width
Filters the width used to retrieve featured images via wp_get_attachment_image_src().
Type: Filter
Since: 1.0

Param
Type
Description

$width
string
Width value as a string

et_pb_portfolio_single_image_height
Filters the height used to retrieve featured images via wp_get_attachment_image_src().
Type: Filter
Since: 1.0

Param
Type
Description

$height
string
Height value as a string

Settings Field Visibility

Settings Field Visibility
Learn how to show or hide a setting depending on the value of other settings.

Note: This tutorial series is intended for advanced users. At least a basic understanding of coding in PHP and JavaScript is required.
The visibility of a module setting can depend on the value of other settings by including one or both of the parameters described below in the setting definition.
Setting Visibility Parameters

show_if (array)

setting (string|string[]) — Setting value(s)

show_if_not (array)

setting (string|string[]) — Setting value(s)

Setting Visibility Examples
Only show setting_a when:

setting_b is on

array(

'label' => esc_html__( 'Setting A', 'myex-my-extension' ),

'type' => 'text',

'option_category' => 'basic_option',

'description' => esc_html__( 'Input something here.', 'myex-my-extension' ),

'toggle_slug' => 'main_content',

'show_if' => array(

'setting_b' => 'on',

'setting_b' => array(

...

);

}

...

view raw

module-setting-field-definition.php

hosted with by GitHub

Only show setting_c when:

setting_b is on
AND setting_a is not some_value

array(

...

'setting_b' => array(

...

'setting_c' => array(

'label' => esc_html__( 'Setting C', 'myex-my-extension' ),

'type' => 'text',

'option_category' => 'basic_option',

'description' => esc_html__( 'Input something else here.', 'myex-my-extension' ),

'toggle_slug' => 'main_content',

'show_if' => array(

'setting_b' => 'on',

'show_if_not' => array(

'setting_a' => 'some value',

);

}

...

view raw

module-settings-definition.php

hosted with by GitHub

Only show setting_a when:

setting_b is one of value_1, value_3, value_4
AND setting_c is not some_value
AND setting_d is not one of value_1, value_4

array(

'label' => esc_html__( 'Setting A', 'myex-my-extension' ),

'type' => 'text',

'option_category' => 'basic_option',

'description' => esc_html__( 'Input something here.', 'myex-my-extension' ),

'toggle_slug' => 'main_content',

'show_if' => array(

'setting_b' => array( 'value_1', 'value_3', 'value_4' ),

'show_if_not' => array(

'setting_c' => 'some_value',

'setting_d' => array( 'value_1', 'value_4' ),

'setting_b' => array(

...

'setting_c' => array(

...

'setting_d' => array(

...

);

}

...

view raw

pseudo-code.php

hosted with by GitHub

Module Settings Groups

Module Settings Groups
Learn how to configure the toggle groups in the module settings modal.

Note: This tutorial series is intended for advanced users. At least a basic understanding of coding in PHP and JavaScript is required.
When editing modules inside the Divi Builder, their settings appear in collapsable groups . You can assign a setting to a specific group using the toggle_slug parameter in the setting definition. You can use one of the builder』s predefined settings groups or you can use a custom group.
Predefined Settings Groups
The following groups are predefined and can be used by simply including one of their slugs as the toggle_slug parameter in a setting definition.

Display Name
Slug

Admin Label
admin_label

Alignment
alignment

Animation
animation

Arrows Color
arrows_color

Attributes
attributes

Audio
audio

Background
background

Bar Counter
bar

Body Text
body

Border
border

Box Shadow
box_shadow

Bullet
bullet

Button One
button_one

Button Two
button_two

Button
button

CSS ID & Classes
classes

Caption Text
caption

Categories
categories

Circle
circle

Color
color

Conditional Logic
conditional_logic

Content Text
content

Controls Colors
colors

Controls
controls

Currency & Frequency Text
currency_frequency

Custom CSS
custom_css

Dividers
dividers

Dropdown Menu
dropdown

Elements
elements

Email Account
provider

Email
email

Exceptions
exceptions

Excluded Item
excluded

Featured Image
featured_image

Field Options
field_options

Field Text
form_field

Fields
fields

Filter Criteria Text
filter

Filters
filters

Icon
icon

Image & Icon
icon_settings

Image & Video
image_video

Images
images

Image
image

Input Text
input

Label Text
label

Layout
layout

Links
links

Link
link

Map
child_filters

Map
map

Menu Text
menu

Meta Text
meta

Module Text
module

Navigation
navigation

Number Text
number

Numbers Text
numbers

Overlay
overlay

Pagination Text
pagination

Percentage Text
percent

Play Icon
play_icon

Player Pause
player_pause

Portfolio Title Text
portfolio_header

Price Text
price

Redirect
redirect

Result Message Text
result_message

Rotation
rotation

Sale Badge
badge

Scroll Down Icon
scroll_down

Search Field
field

Sizing
width

Spacing
margin_padding

State
state

Styles
styles

Subhead Text
subhead

Subheader Text
subheader

Success Action
success_action

Tab Text
tab

Text
main_content

Text
text

Title Text
header

Title Text
title

Toggle Text
toggle

Visibility
visibility

Custom Settings Groups
Settings can be assigned to a custom group in the same way that you would assign them to predefined groups. However, you must also define all custom groups in the get_settings_modal_toggles() method of your module』s PHP class.
Settings Group Definition

tab_slug (array)

toggles (array) — All settings group definitions for the tab

toggle_slug (array) — Settings group definition

priority (int) — Groups are sorted based on this number (from lowest to highest)
sub_toggles (array) — Sub groups for this group (optional)

sub_toggle_slug (array) — Sub group definition

icon (string) — The slug of a predefined icon (optional)
icon_svg (string) — Raw SVG icon (optional)
name (string) — Display Name (only shown when no icon is defined)

tabbed_subtoggles (bool) — Whether or not to display sub groups as tabs
title (string) — Display name (localized)

Custom Settings Groups Example

array(

'label' => esc_html__('Add Mushroom?', 'simp-simple-extension'),

'type' => 'yes_no_button',

'option_category' => 'basic_option',

'description' => esc_html__('Toggle whether mushroom will be added to the pizza.', 'simp-simple-extension'),

'toggle_slug' => 'pizza',

'options' => array(

'on' => esc_html__( 'Yes', 'simp-simple-extension'),

'off' => esc_html__( 'No', 'simp-simple-extension'),

'sub_toggle' => 'pizza_toppings_mushroom',

'quantity_toppings_mushroom' => array(

'label' => esc_html__('How Much Mushroom?', 'simp-simple-extension'),

'type' => 'range',

'option_category' => 'basic_option',

'description' => esc_html__('Dropdown menu with various options.', 'simp-simple-extension'),

'toggle_slug' => 'pizza',

'range_settings' => array(

'min' => '1',

'max' => '5',

'step' => '1',

'show_if' => array(

'toggle_toppings_mushroom' => 'on',

'sub_toggle' => 'pizza_toppings_mushroom',

'toggle_toppings_anchovy' => array(

'label' => esc_html__('Add Anchovies?', 'simp-simple-extension'),

'type' => 'yes_no_button',

'option_category' => 'basic_option',

'description' => esc_html__('Toggle whether anchovies will be added to the pizza.', 'simp-simple-extension'),

'toggle_slug' => 'pizza',

'options' => array(

'on' => esc_html__( 'Yes', 'simp-simple-extension'),

'off' => esc_html__( 'No', 'simp-simple-extension'),

'sub_toggle' => 'pizza_toppings_anchovy',

'quantity_toppings_anchovy' => array(

'label' => esc_html__('How Many Anchovies?', 'simp-simple-extension'),

'type' => 'range',

'option_category' => 'basic_option',

'description' => esc_html__('Dropdown menu with various options.', 'simp-simple-extension'),

'toggle_slug' => 'pizza',

'range_settings' => array(

'min' => '1',

'max' => '30',

'step' => '1',

'show_if' => array(

'toggle_toppings_anchovy' => 'on',

'sub_toggle' => 'pizza_toppings_anchovy',

'toggle_toppings_pineapple' => array(

'label' => esc_html__('Add Pineapple?', 'simp-simple-extension'),

'type' => 'yes_no_button',

'option_category' => 'basic_option',

'description' => esc_html__('Toggle whether pineapple will be added to the pizza.', 'simp-simple-extension'),

'toggle_slug' => 'pizza',

'options' => array(

'on' => esc_html__( 'Yes', 'simp-simple-extension'),

'off' => esc_html__( 'No', 'simp-simple-extension'),

'default' => 'on',

'sub_toggle' => 'pizza_toppings_pineapple',

'quantity_toppings_pineapple' => array(

'label' => esc_html__('How Much Pineapple?', 'simp-simple-extension'),

'type' => 'range',

'option_category' => 'basic_option',

'description' => esc_html__('Dropdown menu with various options.', 'simp-simple-extension'),

'toggle_slug' => 'pizza',

'range_settings' => array(

'min' => '1',

'max' => '9001',

'step' => '1',

'default' => '9001',

'show_if' => array(

'toggle_toppings_pineapple' => 'on',

'sub_toggle' => 'pizza_toppings_pineapple',

'toppings_other' => array(

'label' => esc_html__('Content', 'simp-simple-extension'),

'type' => 'text',

'option_category' => 'basic_option',

'description' => esc_html__('Add any special requests for toppings not in the list.', 'simp-simple-extension'),

'toggle_slug' => 'pizza',

'sub_toggle' => 'pizza_toppings_other',

);

}

public function get_settings_modal_toggles() {

return array(

'advanced' => array(

'toggles' => array(

'pizza' => array(

'priority' => 24,

'sub_toggles' => array(

'pizza_toppings_mushroom' => array(

'name' => 'Mushroom',

'icon_svg' => '',

'pizza_toppings_anchovy' => array(

'name' => 'Anchovies',

'icon_svg' => '',

'pizza_toppings_pineapple' => array(

'name' => 'Pineapple',

'icon_svg' => '',

'pizza_toppings_other' => array(

'name' => 'Other',

'icon' => 'text-quote',

'tabbed_subtoggles' => true,

'title' => 'Special Toppings',

);

}

...

view raw

settings-groups--custom-settings-groups.php

hosted with by GitHub

How To Create A Divi Builder Module

How To Create A Divi Builder Module
Learn how to create a custom module for the Divi Builder.

Note: This tutorial series is intended for advanced users. At least a basic understanding of coding in PHP and JavaScript is required.
Custom Divi Builder Modules
Divi Builder modules consist of PHP, JavaScript, HTML, & CSS code. Each module is defined using a PHP class. The class defines all of the module』s settings and is responsible for rendering the module』s HTML output on the frontend. Additionally, each module has a ReactJS component class (in JavaScript) that handles rendering the module inside of the Divi Builder. In this tutorial, you』ll learn how to create a custom header module. The module will be fully functional in the builder, both on the frontend and on the backend.
Custom Divi Builder modules must be implemented within a theme, child-theme, or Divi Extension. In this tutorial we』re going to implement a custom module in a Divi Extension. If you haven』t already done so, go ahead and create a Divi Extension.
Module Definition
Divi Builder modules are defined using a PHP class. Look inside your extension』s directory and find the example module located in includes/modules. We』ll use it as a starting point to create a custom header module. First, let』s rename the HelloWorld directory to SimpleHeader. Next, rename HelloWorld.php to SimpleHeader.php, open it, and then edit it as shown below:

name = esc_html__( 'Simple Header', 'simp-simple-extension' );

}

public function get_fields() {

return array();

}

public function render( $unprocessed_props, $content = null, $render_slug ) {

}

new SIMP_SimpleHeader;

view raw

SimpleHeader.php

hosted with by GitHub

Our module will include just a few basic settings that can be controlled from within the Divi Builder: heading, content, and background. Module settings are defined in the get_fields() method. Let』s go ahead and do that now:

name = esc_html__( 'Simple Header', 'simp-simple-extension' );

}

public function get_fields() {

return array(

'heading' => array(

'label' => esc_html__( 'Heading', 'simp-simple-extension' ),

'type' => 'text',

'option_category' => 'basic_option',

'description' => esc_html__( 'Input your desired heading here.', 'simp-simple-extension' ),

'toggle_slug' => 'main_content',

'content' => array(

'label' => esc_html__( 'Content', 'simp-simple-extension' ),

'type' => 'tiny_mce',

'option_category' => 'basic_option',

'description' => esc_html__( 'Content entered here will appear below the heading text.', 'simp-simple-extension' ),

'toggle_slug' => 'main_content',

);

}

public function render( $unprocessed_props, $content = null, $render_slug ) {

}

new SIMP_SimpleHeader;

view raw

SimpleHeader.php

hosted with by GitHub

You probably noticed that the background field is missing. We excluded it from the fields array because it』s one of several advanced fields that are added automatically by the builder to all modules unless they specifically opt-out. You』ll learn more about advanced fields a bit later in this tutorial series.
Our module definition is almost complete. We just need to finish the implementation of the render() method so that it will generate the module』s HTML output based on its props. Ready? Let』s do it!

name = esc_html__( 'Simple Header', 'simp-simple-extension' );

}

public function get_fields() {

return array(

'heading' => array(

'label' => esc_html__( 'Heading', 'simp-simple-extension' ),

'type' => 'text',

'option_category' => 'basic_option',

'description' => esc_html__( 'Input your desired heading here.', 'simp-simple-extension' ),

'toggle_slug' => 'main_content',

'content' => array(

'label' => esc_html__( 'Content', 'simp-simple-extension' ),

'type' => 'tiny_mce',

'option_category' => 'basic_option',

'description' => esc_html__( 'Content entered here will appear below the heading text.', 'simp-simple-extension' ),

'toggle_slug' => 'main_content',

);

}

public function render( $unprocessed_props, $content = null, $render_slug ) {

return sprintf(

%1$s

%2$s

esc_html( $this->props['heading'] ),

$this->props['content']

);

}

new SIMP_SimpleHeader;

view raw

SimpleHeader.php

hosted with by GitHub

React Component
In order for our module to be available and fully functional inside the Divi Builder we must create a React Component class that handles the rendering of our module based on its props. Look in your module』s directory for the file named HelloWorld.jsx.
Note: JSX is a syntax extension to JavaScript used in React to describe what the UI should look like.
Let』s rename HelloWorld.jsx to SimpleHeader.jsx, open it, and then edit it as follows:

// External Dependencies

import React, { Component, Fragment } from 'react';

// Internal Dependencies

import './style.css';

class SimpleHeader extends Component {

static slug = 'simp_simple_header';

render() {

return (

{this.props.content()}

);

}

export default SimpleHeader;

view raw

SimpleHeader.jsx

hosted with by GitHub

Next, let』s update the import and export statements in includes/modules/index.js:

// Internal Dependencies

import SimpleHeader from './SimpleHeader/SimpleHeader';

export default [

SimpleHeader,

];

view raw

index.js

hosted with by GitHub

Now, let』s edit the render() method and make it produce the same output that we defined in our PHP render() method.

// External Dependencies

import React, { Component, Fragment } from 'react';

// Internal Dependencies

import './style.css';

class SimpleHeader extends Component {

static slug = 'simp_simple_header';

render() {

return (

{this.props.heading}

{this.props.content()}

);

}

export default SimpleHeader;

view raw

SimpleHeader.jsx

hosted with by GitHub

There are two things in our render() method to take note of. First, note how the module』s content setting is handled. Module settings defined with field type tiny_mce (like the content setting in our module) require the use of a special React Component. The builder sets up the required component and then passes it down to the module as the setting value. Since the value is not a string or number and is actually a React Component, we need to use it as such in our JSX markup.
Also note how we wrapped our module』s output in a Fragment component. Fragments allow you to return multiple top-level elements from your render() method without actually adding an extra element to the page itself.
CSS Styles
Styles for our module can be defined using the style.css file in its directory. Our custom header module is pretty basic so it doesn』t require much styling. Though we should add some bottom margin for the heading so that there is some space between it and the content below it. Later, in our Divi Builder Module In-Depth tutorial series you』ll learn how to make margin and padding for the heading (or any element inside your module』s output) configurable from within the module』s settings.
For now, let』s go ahead and update our module』s style.css:

.simp-simple-header-heading {

margin-bottom: 20px;

}

view raw

style.css

hosted with by GitHub

Testing During Development
Before we can test our custom module in the Divi Builder we need to compile the JSX code into regular JavaScript. To do that, simply run the following command inside your plugin』s directory:
yarn start

Provided there are no syntax errors in your code you will see the following output:

Now you can launch the Divi Builder and check out your Simple Header module!

Note: You must keep the terminal window with yarn start running open while you are developing your module. As you make changes to the files, the JavaScript and CSS will be recompiled automatically.

Defining Module Settings

Defining Module Settings
Learn how to define module settings using the field types provided by Divi.

Note: This tutorial series is intended for advanced users. At least a basic understanding of coding in PHP and JavaScript is required.
Module settings are defined in the get_fields() method of the module』s PHP class. A setting definition is simply an associative array of parameters.
Required Parameters

type (string) — The field type used to render the setting in the module settings modal

Optional Parameters

default (string) — Default value
description (string) — Description (localized)
id (string) — CSS id for the setting』s field
label (string) — Display name (localized)
option_category (string) — Option category slug (for the Divi Role Editor)
show_if (array) — Only show the setting when certain settings have certain values
show_if_not (array) — Only show the setting when certain settings do not have certain values
tab_slug (string) — Modal tab slug
toggle_slug (string) — Modal tab settings group toggle slug

Field Types
The Divi Builder has a comprehensive selection of field types for module settings. Below you』ll find a list of available field types, each with a screenshot and a list of any additional parameters that must be included in the setting definition. The value to use for the type parameter of the setting definition is in parenthesis next to each field type name.
Text (text)

Select (select)

Select Field Parameters

options (array) — Option slugs mapped to their display names (localized)

Checkboxes (multiple_checkboxes)

Checkboxes Field Parameters

options (array) — Option slugs mapped to their display names (localized)

Toggle Button (yes_no_button)

Toggle Button Field Parameters

options (array)

off (string) — Display name for the 「off」 state (localized)
on (string) — Display name for the 「on」 state (localized)

Range Slider (range)

Range Slider Field Parameters

range_settings (array)

min (string) — Minimum value
max (string) — Maximum value
step (string) — Minimum distance between values when using the slider

validate_unit (bool) — Whether or not to validate unit

Defining Custom CSS Fields For Modules

Defining Custom CSS Fields For Modules
Learn how to define custom CSS fields for modules.

Note: This tutorial series is intended for advanced users. At least a basic understanding of coding in PHP and JavaScript is required.
Custom CSS fields appear in the Advanced tab of the module settings modal and allow users to set custom CSS properties for predefined target elements within the module』s HTML output. The fields are automatically generated based on the configuration defined in the module』s get_custom_css_fields_config() method.
Custom CSS Fields Configuration

element_one (array)

label (string) — Display name for the target element (localized)
selector (string) — CSS selector for the target element
no_space_before_selector (bool) — Don』t put a space before selector

element_two (array)

label (string) — Display name for the target element (localized)
selector (string) — CSS selector for the target element
no_space_before_selector (bool) — Don』t put a space before selector

Custom CSS Fields Configuration Example

Compatibility Levels

Compatibility Levels
Making existing custom modules compatible with the latest version of the Divi Builder.

Note: This tutorial series is intended for advanced users. At least a basic understanding of coding in PHP and JavaScript is required.
How a custom module looks and behaves inside the builder depends on its level of compatibility with the builder. There are three levels of compatibility available to custom modules: off (this is the default), partial, and on. Custom modules can declare their level of compatibility using the vb_support property in their PHP class definition.
No Compatibility
This is the default setting for all custom modules. Live previews are not shown for modules with no support for the latest version of the Divi Builder. Instead, a generic block will be shown. The module』s settings can still be edited and it can still be moved around on the page.

Partial Compatibility
The builder will attempt to render a live preview via AJAX for custom modules that declare partial support. AJAX rendering is not ideal as it』s much slower than normal rendering and it won』t be suitable in all cases. For that reason, its important that developers test their modules and only declare partial support for modules that can actually be successfully rendered via AJAX.
Declaring Partial Compatibility Example

Full Compatibility
Modules that are fully compatible with the Divi Builder behave just like official modules. They use the builder』s JavaScript API to handle their own rendering inside the builder. You can learn more about that here.
Declaring Full Compatibility Example

Advanced Field Types For Module Settings

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)

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