Developing Your Own Custom Visual Composer Grid Module

The Total theme includes many great “Grid” modules in the Visual Composer (Blog Grid, Portfolio Grid, Staff Grid…etc.) these by default have many settings to enable/disabling things but sometimes you may need to create something completely custom for your project. You could use the Visual Composer grid builder module – but developing your own custom grid module completely can be much more optimized and allow you to add any code you need and have complete control over all the available settings.

This guide will essentially show you how you can duplicate one of the included modules in your child theme so you can add your own custom grid module in the Visual Composer for use.

But before moving forward, we recommend you check out our Starter Class for adding custom Visual Composer modules. Maybe you just want to start with this instead because it is barebones or maybe you will want to have a look to get a good idea on how things work before duplicating content from the parent theme so you may be less confused.

Important: This is a very advanced modification beyond the scope of support. If you want to take on this challenge you should be familiar with PHP/HTML and core WordPress functions and if not you may want to direct this guide to a freelance developer for assistance.

Step 1: Have a child theme

First you’ll need to make sure you have a child theme setup for your custom code. You can of course create a custom plugin as well for this, but in this guide we’ll be explananing how to do things via a theme – if you have the experience to make a plugin you can probably figure out how to do it as well based on the guide below.

Step 2: Locate The Module To Duplicate

Figure out which module you want to duplicate and edit to fit your needs. While this guide focuses on the Grid modules this can of course be done for any Total Visual Composer Module.

Step 3: Copy The Files From the Total Theme to Your Child theme & Rename

Now you want to copy the files that you will be altering for your own custom module.

  • Total/framework/visual-composer/shortcodes/  – Shortcode registration & settings file
  • Total/vcex_templates/ – Output file

Browse to the folders mentioned above and locate the name of the module you wish to duplicate and modify. Paste these files into your child theme (preferably inside their own folder such as “vc_templates” or something else that makes sense to you) or custom plugin.

For example if you are going to start with the Blog Grid module the files you need to copy are the following:

  • Total/vcex_templates/vcex_blog_grid.php
  • Total/framework/visual-composer/shortcodes/blog_grid.php

Step 4: Include The Registration & Settings File (class)

You’ll need to now include the registration and settings file (Class) which is the file that you copied from total/framework/visual-composer/shortcodes/ and contains the Class that registers the shortcode with WordPress via the add_shortcode function and registers the Visual Composer settings via the vc_lean_map() function. Before doing so I recommend renaming it to something else that makes more sense (this will depend on the module you are creating) in this example we’ll just say you named it my_custom_grid_class.php.

So you’ll need to “include” this function via your child theme’s functions.php file. Example:

require_once( get_stylesheet_directory() .'/vc_templates/my_custom_grid_class.php' );

Of course be sure to edit the location based on where you placed this file.

Step 5: Change Classname & Search and Replace Prefix & Base

Now open up the included file (my_custom_grid_class.php) and first change the classname so it’s unique and won’t override the core theme grid. So if you were using the blog_grid.php file search and replace “VCEX_Blog_Grid_Shortcode”.

Now you want to search and replace the theme prefixes which is “vcex_”. Once you do that you should now have a new module registered.

Next you will want to alter the “base” string which is the shortcode name. Using the blog_grid.php example again this would be “vcex_blog_grid” string which is the shortcode for the Blog Grid module. You can change this to anything you want, just be sure it still has a unique prefix to prevent conflicts with other plugins or theme updates. For this example lets say we named it “my_custom_grid”. The base is added in a few places so be sure to change accordingly.

Step 6: Alter The Include Template File (output function)

Now before you start editing your module options in the registration class (my_custom_grid_class.php) lets rename the output file which was the one you copied from the Total parent theme in the Total/vcex_templates file in this example that would be called vcex_blog_grid.php. For consistency we recommend you name this the same as you named your “Base” shortcode in the previous step so the name of the file is the name of your new module (my_custom_grid.php).

Once renamed go back and edit the registration/settings class (my_custom_grid_class.php) and edit the output function that should look like this:

/**
 * Shortcode output => Get template file and display shortcode
 *
 * @since 3.5.0
 */
 public static function output( $atts, $content = null ) {
 ob_start();
 include( locate_template( 'vcex_templates/vcex_blog_grid.php' ) );
 return ob_get_clean();
 }

You will need to change where it says “vcex_templates/vcex_blog_grid.php” to the location of your output file in your child theme “vc_templates/my_custom_grid.php”. Now your new module is registered to grab the correct output for your custom shortcode.

Also be sure to edit that file and locate the original “base” name (vcex_blog_grid) and change it to your new modules base name:

vc_map_get_attributes( 'my_custom_grid.php', $atts )

This function int he output file parses your shortcode attributes ($atts) based on the settings from vc_lean_map() in the registration/settings class (my_custom_grid_class.php) so that your attributes will fallback to the default values of your settings. It’s important that the base matches your shortcode base.

Step 7: Make your Edits to the various options and output

Now when you log into WordPress and use the Visual Composer you should see your newly registered module. The next step is to simply edit those 2 files to fit your needs. This isn’t something we can guide you on because it all depends on your needs. It should be fairly obvious from the code what things do, but here are some useful links:

  • add_shortcode – https://codex.wordpress.org/Function_Reference/add_shortcode
  • vc_lean_map – https://wpbakery.atlassian.net/wiki/pages/viewpage.action?pageId=38993922