The Basics of a WordPress Theme

In the first part of my article on child themes I explained a little about the history of WordPress themes and child themes, what they are and why you should use them. After sharing the post in a couple of online groups I am a part of, I received a fairly good positive response to the topic and my thoughts on it. One thing that also stood out from some of the comments was that a lot of Divi users don’t necessarily know how a WordPress theme works in the first place.

Everything I am writing about is (pretty much) included in the WordPress Theme Handbook, specifically the articles on the Template Files, Template Hierarchy and Child Themes. If you can afford the time to read through the handbook I highly recommend it. However it can sometimes be a little technical, so it’s often easier to get a ‘primer’ on the topic, to give you the relevant information you need in a manageable size. So, based on the responses to my first article I’ve chosen to first write this article to explain a little about how WordPress themes work.

Understanding the basics

To be able to understand child themes, first we need to understand WordPress themes. This means we need to talk a little about the Template Files and the Template Hierarchy. I’m not going to go into too much detail, but in short it’s the way in which WordPress looks for and loads the various template files in your theme to render content.

Template Files

Any WordPress theme has a base set of template files that is uses to render content for different sections of your WordPress site. If you take a look at the files inside a ‘standard’ WordPress themes (like those found on WordPress.org) you will see that, at their base level, all themes are made up of of two things, a style sheet and a bunch of php files, also known as templates. Theses templates include, but are not limited to, files like the header.php, footer.php, archive.php, single.php page.php and sidebar.php. Each of these templates performs a different type of task within your WordPress theme. The templates themselves are also divided into different template types, depending on what they do.

Template partials are template files that will be included inside another template file. For example the header and footer template files are partials. They will be included (and reused) inside other template files to render specific sections of a page, in this case the header and the footer of the site.

Examples:

  • header.php – contains all code to render the header
  • footer.php – contains all code to render the footer
  • sidebar.php – contains all code to render the sidebar

The common WordPress template files are the templates that will render the specific content of your site they related to. They can be very specific (rendering a specific category of posts, or a specific page) or very generic (for example the index.php file which will be used whenever a specific template file doesnt exist for the content being rendered)

Examples

  • page.php – contains the code to render a page
  • archive.php – contains the code to render any blog post archive (or list)
  • single.php – contains the code to render any individual post

If you read up in the Template Files section of the theme developer handbook you can learn what each one does.

Template Hierarchy.

The next thing to understand is the template hierarchy. This is the way in which WordPress will look for a series of template files to render the specific piece of content. If the first template in the list doesn’t exist it will keep going down the list until it finds a template it can use. The easiest way to explain this is to take a look at a WordPress blog.

On a standard WordPress blog, you usually have a ‘list view’ (list of blog items, a thumbnail image, an excerpt and some form of link to the full article) and then an ‘article view’ (the actual article itself, including any content for that article). So, that means that you would need at least two templates, one to render the list view and one to render the article view. This means that the WordPress engine will look for a template for each view and use it to render the content. For the list view, WordPress will look for a ‘archive.php’ file in your template folder to render the list view and a ‘single.php’ file in your template folder for the article view.
So your archive.php would contain some HTML to display the list view as well as a WordPress Loop to render the list of blog posts, and the single.php would contain HTML specific to the article view, as well as some PHP to get the relevant article content for display.

Now, if you are a theme developer you are probably swearing at me right now, and that’s fine. That last statement is not 100% correct but I am simplifying it a bit, bear with me.

So great, there is a template for list views and a template for article views, what now? Well, lets say that you want to have links to a list of blog posts per category and you want a different display for each category list view. Whenever a user views blogs under a certain category you want to include a description of that category above the list view. Well you could do this in two ways. Either you would add some code to your archive.php to check if the user is browsing a list of blog posts per category and show that description or you can use the category specific templates in the template hierarchy and create a different template per category. For example, if you had a category with the slug ‘products’ and you created a template in your theme called category-products.php, whenever the user browses to the products blog category, WordPress would use that template file to render the products category blog items. This is useful because it means you don’t have to add extra processing to your archive.php template file and you can just service products category specific content to the user, just by adding a template file.

The other important thing to understand is that for each level of WordPress, from pages to posts, categories to tags, there is a hierarchy in place as to what gets loaded. So for example, when WordPress renders a list of blog posts, it first looks for a category specific template (either by slug or by id) then a general category template, then the archive template and then finally the index template. So in our products category example above (lets say the product category id was 5) WordPress would look for the following template files, in this order, to use to render the list:

  • category-products.php
  • category-5.php
  • category.php
  • archive.php
  • index.php

That’s 6 levels of template hierarchy that you could use to render things differently for different points of just your blog!

The same goes for blog posts, you have the following set of templates at your disposal when developing a theme. Lets say I was rendering a page with the slug (or name) ‘my-page’ which has an id of 7. WordPress would look for the following templates, in this order, to render the page content:

  • a custom template file – (The page template assigned to the page in WP admin).
  • page-my-page.php
  • page-7.php
  • page.php
  • singular.php
  • index.php

Each template is the fallback to the previous template, with index.php being the final template for pretty much all sections of a WordPress site. You can probably see now why any theme developers reading this article were a little annoyed at my oversimplification of the theme hierarchy earlier ;-).

To get a better understanding of the different levels of template types available to you, as well the order in which WordPress loads them, I highly suggest you read Hierarchy in Detail section of the Theme developers handbook.

So what does this mean in terms of Divi. Well the base of the Divi theme is a small subset of the template partials and common template files. Divi doesnt have (for example) category based templates or even an archive template in its template file list. Because Divi has modules which render the blog lists and pages. Divi tends to use the templates towards the end of the hierarchy (single.php page.php and index.php) to render all content, because the modules are handling all the grunt work. However we need to have an understanding of what these template files do and how they can be ‘overridden’ using the hierarchy to be able to build our child theme.

A peek inside the Atlantic Wave workshop

It’s not every day that I get really excited about a plugin I am working on. Don’t get me wrong, every plugin I develop is exciting, but more so from a ‘solving a puzzle’ or ‘fulfilling someone else’s requirement’ point of view. Granted, this is the reason I got into plugin development and it is a great feeling to know that people out there are using my plugins to make their lives easier.

What I’m talking about is the excitement I get about the fact that I am busy developing a plugin that not only will make others lives easier but also the fact that I it has scope to become so much more than the current sum of its parts. It’s one of the first plugins I’ve written that has the potential for so much more than what I am aware of and I am more excited about the future feature requests I’m going to get from the Divi community than anything else.

Allow me to introduce you then, to Atlantic Wave’s Elegant Forms plugin.

Building on the base of the Divi theme Contact Form module, with Elegant Forms I hope to fill a gap that, up to now, has required to the installation of other third party plugins like Gravity Forms or Contact Form 7. By baking Elegant Forms right into the Divi Page Builder I hope to bring the same extended functionality to your Divi site builder experience.

I’m about halfway through development of version 1 and I’m already planning the features to be added to future versions. I’ve included some ‘sneak peek’ screenshots of some of the functionality below. If this excites you as much as it does me, comment below and let me know what you think. I’d also love to hear your requests for features to be added to this plugin.

As an added bonus, if you comment with your thoughts or a feature request below, when the plugin releases I’ll randomly select a winner from the comments to receive a 100% discount coupon on Elegant Marketplace, effectively giving you a free copy of the plugin at launch.

Remove the sidebar in your Divi category view.

So, I’m in the process of putting the final touches on part two of my child themes series when I get a request from another Divi developer, Patricia. She is building a site for a client and she wants the post category list view to not show the sidebar. What a perfect way to showcase the power of a child theme.

Step 1 – Prepare the template

Patricia was already working in a child theme (experienced developer that she is), so I didnt need to create one for her. As Patricia wants to manipulate the category list view, all I have to do is create an archive.php file inside her child theme, copy all the code inside the index.php file from the Divi theme to the child theme archive.php file and make some changes.

This is the contents of /themes/Divi/index.php

The two things we need to remove are the ‘left-area’ div article list wrapper, and the get_sidebar(); function call. (You could also just leave the left-area div there if you want and style it to be wider but I prefer to remove it entirely)

So our new /themes/child-theme/archive.php file looks like this:

Step 2 – add some style

If you just implement the archive.php as is you will see that the borderline between the content and the sidebar still appears. This is because Elegant Themes have implmented this border on the before psuedo class of the ‘content-area’ div. So we need to add a little CSS to our child theme style.css file to effectively ‘hide’ the border.

And that’s it. One template, remove a couple of lines of code, a small css snippet and all your article archive/category pages will now no longer have the default sidebar. I’ve created a GitHub repository if you want to download the files to use in your next project.

Happy Diviing.

Child themes – what are they and why you should use them

Since joining the Divi community late last year I think the one topic I’ve seen asked about or discussed the most is the concept of child themes, mostly when it comes to editing the footer credits in a Divi built website.

In this article I hope to give you a thorough understand of what a child theme is and why you should consider using one.

In the begining there was WordPress.

When WordPress was first released, it didn’t support themes as we know them today. If you wanted the front end to look a certain way you would edit the default templates with your own HTML and CSS. It also meant you had to have a pretty good grasp of PHP to ensure you integrated the correct function calls into your theme to ensure that the info from the database appeared to your user.

Later on the ability to create and install separate themes was added. At its core this was done to allow more flexibility to the WordPress user when it came to creating a front end for their WordPress powered site. It still meant that you needed some level of understand of HTML/CSS and PHP but it also brought about a shift in the adoption and usage of WordPress. Enterprising designers and developers realised that there was a market for selling premium themes to non technical end users who just wanted a good looking site. Fast forward a couple of years and themes are now not only able to render your data in a clean, well designed way, you’re even able to use page builder frameworks to design your page templates yourself, with the Divi theme being one of the most popular.

However, the big thing that a lot of people miss, don’t understand ( or don’t even know about ) is that WordPress also supports child themes. This was added a few years after the theme system was added and its important to understand what a child theme is to be able to understand its power.

In simple terms, a child theme inherits all the functionality of it’s parent theme, with the ability to override or customise how the parent theme works, without making changes to the parent theme files. To explain it a bit easier let me use a more real world analogy.

Lets say you buy a car. Two of the important aspects of a car are it’s underlying engine and drive train components, and the body. Now, if you want to change how the car looks, you can do things like repaint it. However, you can also modify it by doing things like adding a front or rear spoilers. Both options will change how the car looks but the respray is a permanent change, whereas the spoilers are temporary, they could easily be switched out with other parts.

Now I’m really extending the metaphor here, but the engine and drive train of your website are WordPress. This gets tweaked and upgraded from time to time (servicing and parts repair) but the core engine remains mostly the same for the life of the site. The installed theme (or parent theme) is the body work. Once you’ve chosen your theme you don’t really want to make changes to it (well get to why later). A child theme is like adding spoilers, making small changes to the main theme that are discardable or interchangeable (more or less).

Hopefully this makes things a little clearer for you. So lets talk about things like why you wouldn’t make changes to the installed theme and why its better to do it in a child theme.

To theme or not to theme.

If you have purchased a premium theme, either from a theme marketplace or a theme vendor (like Elegant Themes) you don’t really want to be making changes to any of the theme files. The reason for this is that if the theme every gets updated, you will have to either make copies of the changes to made to those files, update the theme manually and then make those changes again. If you choose to update the theme manually, then you’ll automatically loose any changes you’ve made and have to remake them.

So the first reason to use a child theme is if you have to make changes to theme files. Putting those changes in a child theme means that when update time happens you won’t loose any changes. It also means that if there are any structural changes to the parent theme that could break the site with any customisations you’ve made in your child theme, you can simply deactivate your child theme and activate the parent theme. Your customisations won’t be present until you fix them, but at least you’ll still be able to use the parent theme and keep most of the general look and feel of your site the same.

The second reason is speed. While themes like Divi allow you areas in your ePanel for custom CSS or JavaScript, its not ideal to use this for large chunks of either CSS or JavaScript code. The main reason for this is that these code snippets are stored in the database. So every time a page on your site loads, the script loading that page has to do extra queries to the database to fetch that code to render it on your page. If you use a custom header.php or footer.php in a child theme, WordPress will simply load your child theme template file instead of the parent theme template file, causing less overhead in the rendering of a page.

Finally child theme customisations are reusable on multiple sites. For example, lets say you are a web designer and you want the Divi footer credits (designed by) to be replaced by your own name. If you used a plugin to achieve this, every time you create a new site you would need to install that plugin and enter the relevant data for it to display as you want it. If you had a ready made child theme, with the correct data in the footer.php, all you would have to do is install the child theme to your client’s site and the footer credit would be correct. ( and by the way, this is not me bashing plugins, I’m a plugin developer after all, I just believe in using the right tool for the job ).

So hopefully that’s given you a good understanding of what a child theme is and why you should use it. In the next article in this series on child themes, I’ll explain how to create your child theme ( specifically for the Divi theme ) and some of the cool things you can do with it.

 

Using anchor links to open accordions and tabs in Divi

Once of the more useful things about web design is the ability to use anchor tags (those things that create links to other pages or websites) to link to sections within the same page. Once clicked the page will jump to (or you can animate it) the content it is linked to.  This is achieved by linking the anchor to the id of the element you want to link to, using a # and the id of the element in the anchor href.

So if I created an anchor tag like this:

<a href="#element-identifier">Link Text Here</a>

and a div like this

<div id="#element-identifier">Div Content Here</div>

if a user to my site clicked on the link, the browser would immediately jump to the that div, instead of opening a new page.

Now Divi has these great modules called Accordions and Tabs. These are useful for presenting large pieces of information in a more manageable layout and not requiring your visitor to have to scroll through pages of information to find the specific piece of data they are looking for. However, sometimes it’s useful to be able to open a specific accordion item or tab with the click of a button, using a similar method as the anchor links above.

This can be achieved by using some custom jQuery. While its not as easy as creating an anchor link, once you know how to do it, it becomes quite simple.

The demo page : you can view this demo on the Anchor links open demo page. You will see that I have created 2 links, some text, and accordion and a tabbed section.

The important thing to note is that I have set a CSS id to the parent element of both anchors as well as the accordion and tabs modules. This is done in the Custom CSS section for each module.

Now for the jQuery:

jQuery(function ($) {
    //accordion
    $('#open-accordion-dance a').on('click', function(event){
        $('#my-accordian .et_pb_accordion_item_1 .et_pb_toggle_title').click();
        $("html, body").animate({ scrollTop: $('#my-accordian').offset().top }, 1000);
    });
    //tab
    $('#open-tab-dance a').on('click', function(event){
        $('#my-tabs .et_pb_tabs_controls .et_pb_tab_1 a').click();
        $("html, body").animate({ scrollTop: $('#my-tabs').offset().top }, 1000);
    });
});

The two blocks of jQuery code do roughly the same thing, except the first is for the accordion and the second is for the tabs.

Effectively, each block binds to the click event of the selected anchor, (in this case selecting the anchor based on the id of the parent element) and then triggers the default click event handler of the relevant accordion or tab item. It then animates the page to scroll to the same position as either the accordion or tabbed element, based on that element’s id.

The actual selectors I’m using are irrelevant, you could use whatever selectors are generated by the Divi page. The important thing to note is how I specify which accordion item or tab item (by number) to trigger the click for. Divi doesn’t allow you to give the accordion or tab elements their own CSS id’s, so you have to inspect the page to determine which one you need to open.

If you want to try this out yourself, you can download the Anchor Links Demo code and install it yourself. Simply add the load the Page Layout to any new page, via the Divi Builder portability feature, and add the jQuery to either your child theme or integrate it into your Divi Theme Options under Integrations (remember to put it between script tags).

Opening your Divi Header and Footer icons in a new window.

A few weeks ago I released the Atlantic Wave Social Media plugin for Divi. The plugin extends the built in Divi header and footer social media icon set by adding up to 13 additional social media icons.

A customer recently asked me how it would be possible to open the social media links in a new window. Now I will probably release an update to the plugin to add this functionality, but for now I thought it would be a good idea to share a simple way of being able to do this. Even if you don’t use my plugin, being able to set your social media icons to open in a new window is a good practice.

By adding a little piece of JavaScript to your Integration tab in the Divi Theme Options, you can set the social media icons to open in a new window.

  1. In your WP admin, select Theme Options from the Divi menu
  2. Click on the Integration tab
  3. Make sure ‘Enable body code’ is enabled.
  4. Scroll down to the section where it says ‘Add code to the <body> (good for tracking codes such as google analytics)’
  5. Add the JavaScript code snippet below. If you already have some JavaScript there, you can just put this inside the existing <script> tags. If there is nothing there then make sure to wrap the JavaScript with <script> tags.
jQuery(document).ready(function($){
    $('.et-social-icon .icon').each(function(){
        $(this).attr('target', 'blank');
    });
});

And there you go, all your social media icons should now open in a new window!

Make your Divi Page Builder go large.

FullScreenDiviPageBuilder

I tend to prefer to use the full extent of whatever screen I am on to it’s fullest effect. Typically I have two screens, my 23inch widescreen monitor and my 17inch laptop screen. The monitor is for coding and all coding related things and the laptop screen is for testing in browsers as well as the odd VLC or YouTube window.

One thing I hate is when I am working inside a modal view that doesn’t take full advantage of whatever screen I am on. This is a special pain point whenever I am using the Divi Builder, which makes extensive use of modals.

So I took a quick look under the hood and it turns out setting the modal to fill the screen isn’t that hard to do. A few lines of CSS code later and viola, Divi Full Width Page Builder plugin.

I haven’t tested this with every instance of every modal, but I’m looking forward to trying it out.

If you want to install it as a plugin, you can do so from the Git Hub repo. Alternatively copy and past the PHP code from the full_screen_page_builder.php file into your functions.php.

Happy Diviing.

Adding CSS to your Custom Divi Modules

Recently I posted on the topic of Building your own Divi Builder Modules. As a PHP developer first, in that article I focused lightly on the PHP side of things, how to setup the module code etc.

Michelle Nunan from DiviSoup pointed out that it might be handy to know how to add custom CSS to your new custom module. So here we go.

I am going to use the Image Overlay Module that I sell on Elegant Market Place as an example.

1) Know the code

So whatever your custom module is, when it renders on the front end it’s going to display a bunch of HTML. You could go into the module code to determine what html is being created (or perhaps you coded the HTML yourself and you already know), but the simplest way to check is to add the module to a page, preview it and inspect the HTML.

My Image Overlay module creates the following html:


<div class="et_pb_module et-waypoint et_pb_image et_pb_animation_off et_pb_image_overlay_0 et_always_center_on_mobile et_pb_image_overlay et-animated"><img class="main" src="https://elegantmarketplace.com/wp-content/uploads/2016/04/overly2AW.jpg" alt="" /> <img class="overlay" src="https://elegantmarketplace.com/wp-content/uploads/2016/04/overly1AW.jpg" alt="" /></div>

As you can see the main container has quite a few classes attached to it, but the important one is the et_pb_image_overlay class. You will notice that this is the same as the slug created in the previous article. So this means we can apply css to any instances of the et_pb_image_overlay class, or any elements inside that class (in this case the images).

For this example I’m just going to use the following CSS snippet. (it’s nonsense really, just used for an example).

.et_pb_image_overlay {
    position: relative;
}
.et_pb_image_overlay img.overlay {
    display: block;
    position:absolute;
}

I’m going to place this code inside a .css file inside my child theme under a directory called css.

/pathtochildtheme/css/image_overlay_css.css

The names and directory locations are just my choosing, you could use anything you like really.

1) Load the code

Now I need to tell WordPress to load my CSS. In my child theme I will probably already have something like this (if you don’t have a child theme, time to read up on how to create one)

function theme_enqueue_styles() {
    wp_enqueue_style( 'parent-style', get_template_directory_uri() . '/style.css' );
}
add_action( 'wp_enqueue_scripts', 'theme_enqueue_styles' );

So all I need to do is add a line to enqueue my new custom css

function theme_enqueue_styles() {
    wp_enqueue_style( 'parent-style', get_template_directory_uri() . '/style.css' );
    wp_enqueue_style( 'custom-image-overlay-style', get_stylesheet_directory_uri() . '/css/image_overlay_css.css' );
}
add_action( 'wp_enqueue_scripts', 'theme_enqueue_styles' );

The second line added to the theme_equeue_styles function tells WordPress to load a file located in the current theme (my child themes) css directory called image_overlay_css.css, the file we created earlier.

And that’s it, style created and loaded.

Building your own Divi Builder Modules

divi-modules

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?:

  1. Adds a hook to the et_builder_ready action, to call the ex_divi_child_theme_setup function.
  2. 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.

Divi Page Builder Cache

The latest versions of the Divi Page Builder includes very smart caching. This can sometimes lead to problems where users find they can’t add or delete rows or modules or use custom modules.

Disclaimer: I’ve only really experienced this issue when developing module customisations. So this may not work for your specific Page Builder caching situation. Results may vary.

LocalStorage

Divi’s Page Builder uses the JavaScript LocalStorage API. Basically this allows the Builder to store the Page Builder cache on your computer instead of in your browser, meaning that even clearing your browser cache does not clear the Page Builder cache.

You can see the LocalStorage elements from your browser’s inspector window. In Chrome it is found under Resources (see image below)

Inspector

To clear the LocalStorage items you need to run a line of javascript in your inspector window’s Console tab.

for(var prop in localStorage)localStorage.removeItem(prop);

I’ll expand this below so you can see what its doing.

for (var prop in localStorage) {
    localStorage.removeItem(prop);
}

What this does is loop through each property in LocalStorage and remove it from LocalStorage. Simple!

UPDATE 05/11/2016 As John kindly pointed out in the comments below an even quicker way to clear the local storage would be to just clear the local storage object.

window.localStorage.clear()

Once you’ve done this you’ll need to refresh the page to see if it has worked.

It’s worth noting that any other web apps you use that may use LocalStorage will also be cleared out, so it’s perhaps best to check if there are any other LocalStorage properties that aren’t Divi specific.

For those who aren’t as tech savvy to know where their inspector window is or how to use it, I’ve created a simple plugin that will clear all localStorage while using the WordPress admin interface if activated. I don’t recommend you leave it activated at all times. You can download the plugin here. Please note that this runs some JavaScript in your admin view, so once you activate it, refresh your admin view and leave it for a few seconds, before trying the Page Builder again.

I’d love to hear if this solved your specific Page Builder caching issues, so please leave a comment below if this helped you.