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:

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:

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!

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:

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

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

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:

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.