I’ve recently been spending some time extending modules in the Divi Page Builder.
I had a few requests from clients to either make changes to an existing module or create a new module with custom functionality. As always my first port of call was a Google Search. The results, while not abundant, did eventually lead me down the right path.
The limited set of articles I did find didn’t really explain the complete process of setting up a new module or they used slightly incorrect ways of adding a new module to the page builder. So I decided to write a post that detailed the entire process from start to finish. For the sake of this article, we are going to take the Image module and make a new one based on it.
This article won’t go into the details of actually customising the module, as that will be dependant on your specific needs. Also it would probably take up a whole heap of additional articles explaining all the sections in a Page Builder Module Class.
1) Preparation
First off you a basic understanding of PHP and WordPress hooks. For the sake of this article I’m going to assume you are working with a child theme. All the PHP code will be added to one of two files in your child theme. The first is the child theme’s functions.php file (create it if there isn’t one) . The second file will contain all the module related code. You can call the file anything you want, for this article I will call mine custom-pb-image-module.php.
So in the root of my child theme I will have
functions.php custom-pb-image-module.php
Inside the functions.php file, include the module file, typically at the top of the functions.php
/* include custom image module file*/ include(get_stylesheet_directory() . '/custom-pb-image-module.php');
The get_stylesheet_directory() function will return the path to the child theme folder.
Everything else we do will be inside the custom module file.
2) Prepare your custom module file
Inside the module file add this code:
function ex_divi_child_theme_setup() {
if ( class_exists('ET_Builder_Module')) {
// this is where your new module class will go
}
}
add_action('et_builder_ready', 'ex_divi_child_theme_setup');
What does this code do?:
- Adds a hook to the et_builder_ready action, to call the ex_divi_child_theme_setup function.
- The ex_divi_child_theme_setup function then checks if the Builder Module class exists and if true, runs the new module class.
2) Copy an existing module.
The ET Builder Module Classes are quite big, so you don’t really want to write the entire thing yourself. (You’d probably need to be a developer at Elegant Themes to be able to do so anyway). So choose an existing module that is closest to what you need, and then go and find it’s Class in the following Divi file:
//path-to-Divi-theme-folder/includes/builder/main-modules.php
I’m going to use the Image module, it looks like this:
class ET_Builder_Module_Image extends ET_Builder_Module {
function init() {
$this->name = __( 'Image', 'et_builder' );
$this->slug = 'et_pb_image';
// a whole bunch of PHP code that defines how the class functions
}
}
new ET_Builder_Module_Image;
Copy the entire class of the module you want to use including that last ‘new ET_Builder’ line and paste it inside your module file, replacing the comment of ‘this is where your new module class will go’.
3) Time to do some hacking.
Firstly you need to rename the Class Name of the new module and the slug. The default Image Module class looks like this
class ET_Builder_Module_Image extends ET_Builder_Module {
function init() {
$this->name = esc_html__( 'Image', 'et_builder' );
$this->slug = 'et_pb_image';
For our new module we would do something like this
class ET_Builder_Module_Image2 extends ET_Builder_Module {
function init() {
$this->name = esc_html__( 'Image 2', 'et_builder' );
$this->slug = 'et_pb_image2';
Note that it is very important to keep the et_pb_ prefix for the module slug, otherwise the Divi Builder won’t load the module.
Then we need to change how the instance of the new class is called, as well as add the shortcode for it (so that WordPress can render your module on the website). At the moment it says this:
new ET_Builder_Module_Image;
We need to change it to this
$et_builder_module_image2 = new ET_Builder_Module_Image2(); add_shortcode( 'et_pb_image2', array($et_builder_module_image2, '_shortcode_callback') );
using the new class name and the new slug.
NOTE: if you want to override an existing module with a customised version (not add a new one), you only need to change the class name of the module, not the slug. Also you need to replace the shortcode for that module.
class ET_Builder_Module_Image2 extends ET_Builder_Module {
function init() {
$this->name = esc_html__( 'Image', 'et_builder' );
$this->slug = 'et_pb_image';
and
$et_builder_module_image2 = new ET_Builder_Module_Image2(); remove_shortcode( 'et_pb_image' ); add_shortcode( 'et_pb_image', array($et_builder_module_image2, '_shortcode_callback') );
Anyway, we’re building a new module, so your final custom module file looks something like this:
function ex_divi_child_theme_setup() {
if ( class_exists('ET_Builder_Module')) {
class ET_Builder_Module_Image2 extends ET_Builder_Module {
function init() {
$this->name = __( 'Image', 'et_builder' );
$this->slug = 'et_pb_image2';
// a whole bunch of php code that defines how the class functions
}
}
$et_builder_module_image2 = new ET_Builder_Module_Image2();
add_shortcode( 'et_pb_image2', array($et_builder_module_image2, '_shortcode_callback') );
}
}
add_action('et_builder_ready', 'ex_divi_child_theme_setup');
Now you are ready to start making changes to the module’s code and build your custom module functionality.
Happy hacking…
UPDATE: During preparation of this article I discovered that my custom modules weren’t always loading into the Page Builder. I couldnt figure out why until I found out how the Divi Page Builder caching works. So make sure you check that as well.
