Note: This tutorial series is intended for advanced users. An advanced 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 the module's settings and renders the module's HTML output on the front end.
Each module has a ReactJS component class (in JavaScript) that handles rendering the module inside 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 front and back end.
Custom Divi Builder modules must be implemented within a theme, child theme, or Divi Extension. This tutorial will 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.
Rename the
HelloWorlddirectory toSimpleHeader.Rename
HelloWorld.phptoSimpleHeader.php,Open it, and then edit it as shown below:
<?php
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();
}
public function render( $unprocessed_props, $content, $render_slug ) {
}
}
new SIMP_SimpleHeader;
Our module will include just a few basic settings that can be controlled from within the Divi Builder:
Heading
Content
Background
Module settings are defined in the get_fields() method.
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 later in this tutorial series. Our module definition is almost complete. We 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!
<?php
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',
),
);
}
public function render( $unprocessed_props, $content, $render_slug ) {
return sprintf(
'<h1 class="simp-simple-header-heading">%1$s</h1>
<p>%2$s</p>',
esc_html( $this->props['heading'] ),
$this->props['content']
);
}
}
new SIMP_SimpleHeader;
React Component
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 (
<div className="simp-simple-header">
{this.props.content()}
</div>
);
}
}
export default SimpleHeader;
Next, let’s update the import and export statements in includes/modules/index.js:
// Internal Dependencies
import SimpleHeader from './SimpleHeader/SimpleHeader';
export default [
SimpleHeader,
];
Now, let’s edit the render() method and make it produce the same output 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 (
<Fragment>
<h1 className="simp-simple-header-heading">{this.props.heading}</h1>
<p>
{this.props.content()}
</p>
</Fragment>
);
}
}
export default SimpleHeader;
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 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 adding an extra element to the page.
CSS Styles
Styles for our module can be defined using the style.css file in its directory. Our custom header module is pretty basic and doesn’t require much styling.
However, 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:
Testing During Development
Before testing our custom module in the Divi Builder, we must compile the JSX code into regular JavaScript. To do that, run the following command inside your plugin’s directory:
yarn start
You can launch the Divi Builder and check out your Simple Header module!
Note: You must keep the terminal window yarn start open while developing your module. The JavaScript and CSS will be recompiled automatically as you change the files.