How to Extend Visual Composer With Custom Content Elements

In the previous tutorial we looked at Visual Composer for theme developers; licensing and technical setup. In this tutorial we’ll take things further, extending Visual Composer and setting it up to build pages. 

Visual Composer Default Functionality

Before we look at actually building a page, let’s run through some of the default features.

Content Elements

Visual Composer comes with a vast array of built-in content elements. Besides this, Visual Composer offers over 200 add-ons, both free and paid. 

By default Visual Composer is enabled only for pages, but you can also enable it for posts and even custom post types. These and more options can be managed from within the Visual Composer Role Manager. There you can also control who can use Visual Composer in your admin.

The Shortcode Manager allows you to add custom elements with parameters. In some ways the user-centric equivalent of developer method of mapping new elements.

Advanced Grid Builder

One of the most appealing tools for users is the grid builder. With it, users can create any kind of grid, with images, text, buttons, posts and so on, without touching code. Masonry-type grids are also available.

Template Library

The Template Library gives users access to professional templates for page structure. Typical examples include article layouts, landing page layouts, parallax pages, portfolios, you name it. As a developer you can even create your own, and include them with your theme’s demo content.

Drumroll Please..

And, finally, we reach what’s arguably the most important part of Visual Composer: the editor. This is a back-end and a front-end editor, and with it users can build pages without coding knowledge.

With the front-end editor you edit exactly what you see. It’s certainly more What You See Is What You Get than the default WordPress WYSIWYG editor!

Page builder works with a row and columns system. Each element added to the page is wrapped inside a row container. Multiple elements can be added to the same row, in columns, or further nested rows. The screenshot below highlights how elements, rows, columns, can be added, edited, and removed.

Having covered the basic features available, let’s no turn our attention to some development. We’re going to extend Visual Composer’s default functionality and add new custom elements.

Extending Visual Composer

To override any element in Visual Composer you first need to copy the template file from the Visual Composer plugin folder (js_composer) > include > templates to the yourtheme > vc_templates folder. From the previous tutorial you might remember that in our Focuson theme we have four files:

1. vc_column.php


2. vc_column_text.php


3. vc_row.php


4. vc_video.php

And as we discussed, naming is very important here. These templates should be named exactly as they are in default VC plugin folder.

Having duplicated the template file you are ready to overwrite it. Let’s see, for example, what’s in the first file vc_columns.php. If you are familiar with shortcode creation there’ll be nothing new for you here.

The file structure can be split into three parts:

1. Extract shortcode attributes


2. Prepare settings for output


3. Output the shortcode structure

But what if you want to add or remove existing shortcode attributes, how would you deal with that? Meet three new functions:

vc_remove_param();

This function removes the shortcode parameter from an existing or custom element. To remove the attribute, target the specific shortcode with the name, for example vc_column and the attribute name, for example el_class.

vc_remove_param( "vc_column", "el_class" );

vc_add_param();

This function adds new parameters to an existing or custom element. As with the vc_remove_param() function, target the specific shortcode with its name, for example vc_column and include the parameter array:

vc_add_param('vc_column', array(
    "type"       => "dropdown",
    "class"      => "",
    "heading"    => "Animate",
    "param_name" => "animate",
    "value"      => array(
    "False"  => 'false',
    "True"   => 'true'
    )
));

vc_add_params();

This function is similar to vc_add_param(), but it allows you to add multiple parameters to one element. You can find a list of all the parameter types here.

To add or remove new params, as well as add new elements, you need to edit the integration file, which in our case is ninzio_vc.php.

1. We start by disabling the front-end editor. The front-end editor is a really cool feature, but our custom elements do not support it. It’s up to you, as a theme developer, whether you want to support the front-end and/or back-end editors.


2. Remove all the unnecessary or unsupported parameters from targeted elements with vc_remove_param();
   


3. Add new parameters to existing elements with the vc_add_param(); or vc_add_params(); functions.


4. Then add new elements..

How to Add Custom Elements

Adding new content elements to Visual Composer comes about when a shortcodes file is present in your theme or theme add-on, like in our case, so first we need to check with the function whether our ninzio-addons plugin is installed and active:

if (defined( 'NINZIO_ADDONS' ) && file_exists( get_template_directory() . '/plugins/ninzio-addons.zip' ) ) {
    … new elements code goes here...
}

How does Visual Composer understand that new elements have been added? With add_action();.

add_action( 'init', 'focuson_ninzio_integrateVC');

function focuson_ninzio_integrateVC() {... new elements}

We will use the action init, giving us this:

if (defined( 'NINZIO_ADDONS' ) && file_exists( get_template_directory() . '/plugins/ninzio-addons.zip' ) ) {

    add_action( 'init', 'focuson_ninzio_integrateVC');

    function focuson_ninzio_integrateVC() {... new elements}

}

Now we are ready to add our new elements, for which we need another new function: 

vc_map();

This function requires one parameter: an array of special attributes describing your shortcode. As an example we will add a custom separator element:

<?php 

/*  SEPARATOR            (CONTENT)
/*-------------------------------*/

    vc_map(array(
'name'                    => "Separator",
'base'                    => "nz_sep",
'class'                   => 'nz-sep',
'show_settings_on_create' => false,
'category'                => esc_html__("Ninzio",'focuson'),
'icon'                    => 'icon-separator',
'description'             => 'Use this element to separate content',
'js_view'                 => '',
'params'                  => array(
            
            ...

That’s a lot of attributes! Let’s highlight the most important:

• 
  name gives a unique descriptive name to your custom element. Users will see it in the Visual Composer tab.


• 
  base, no less important than name, is the shortcode tag name. If you are familiar with custom shortcode creation, you’ll know that all custom shortcodes have tags. For example, our custom separator has a nz_sep tag. The element base should be unique and it should be named exactly as the shortcode name is in your shortcodes.php file (like we have in our Focuson theme):

<?php 

/*  SEPARATOR SHORTCODE
/*===================*/
    
function nz_sep($atts, $content = null) {

extract(shortcode_atts(
array(
'top'    => '20',
'bottom' => '20',
'type'   => 'solid',
'color'  => '#eeeeee',
'align'  => 'left',
'width'  => '',
'height' => ''
), $atts)
);

$styles = "";

if (isset($color) && !empty($color)) {
$styles .= 'border-bottom-color:'.$color.';';
}

if (isset($width) && !empty($width)) {
$styles .= 'width:'.absint($width).'px;';
} else {
$styles .= 'width:100%;';
}

if (isset($height) && !empty($height)) {
$styles .= 'border-bottom-width:'.absint($height).'px;';
}

if (isset($type) && !empty($type)) {
$styles .= 'border-bottom-style:'.$type.';';
}

if (isset($top) && !empty($top)) {
$styles .= 'margin-top:'.absint($top).'px;';
}

if (isset($bottom) && !empty($bottom)) {
$styles .= 'margin-bottom:'.absint($bottom).'px;';
}

$output = '<div class="sep-wrap '.sanitize_html_class($align).' nz-clearfix"><div class="nz-separator '.sanitize_html_class($type).'" style="'.esc_attr($styles).'">&nbsp;</div></div>';
return $output;
}
add_shortcode('nz_sep', 'nz_sep');

?>

• 
  class is not critical, but an important option, serving as a non-unique identifier. The naming should be descriptive and without spaces, use dashes or underscores.


• 
  show_settings_on_create is a boolean parameter and self-descriptive.


• 
  category is very important. If you want to group your custom elements within one custom menu tab in the Visual Composer elements menu, you should add a custom category. If you want to include elements in an existing category use the name of that existing menu tab: 

• 
  icon is similar to class. We add an icon name so we can style the shortcode in the Visual Composer menu. For example:

i.icon-separator,.nz-sep .vc_element-icon {background-image:url(../images/shortcodes/sep.png)!important;}

• 
  description adds a small description to your custom element. Users will see this.


• 
  js_view is a very important parameter. When you have elements which comprise parent and child components (for example content boxes, which have a main container parent and child box elements, where parent and child elements have separate attributes) this attribute should have the value VcColumnView. We will examine the more complex details in a moment.


• 
  params is the array of parameters to be added to your custom element. It behaves similarly to the vc_add_params() function, but nested in the vc_map() function.

Parent and Child Elements

Container elements with child elements require some specific configuration before adding. In the vc_map() function we need to add a couple more parameters to make our elements either a container, or the child of another element.

For example, say we want to add a new element “Content boxes”. Our content box element comprises two parts: 

1. the parent element with its attributes 


2. and the child box elements, each with their attributes. 

One content box can have unlimited child box elements. So we have two issues to solve:

1. Somehow we need to tell Visual Composer that the content box is a child/parent element,


2. then that a box is the only possible child of a parent content box element, and that a content box element is the only possible parent for box child elements. 

Parent Element Code

To avoid confusion as much as possible, let’s take a look at an existing element. In our Focuson theme we have a “Content boxes” element, with two extra parameters of particular interest:

"as_parent" => array('only' => 'nz_box')

Remember the base parameter of our vc_map() function? Here, with as_parent, we’re registering the nz_content_box element as a parent only for a nz_box child element.

"js_view" => 'VcColumnView'

When js_view is set to VcColumnView Visual Composer adds additional UI functionality to the element in the editor, so we can add a new child element.

Child Element Code

In the same vein, our nz_box element code has an additional parameter:

"as_child" => array('only' => 'nz_content_box'),

With as_child we’re registering the nz_box element as a child, but only for a nz_content_box parent element.

Extend Classes

If you now visit the Visual Composer menu and click on the newly added Content box element, you will see… it is not working. No parent/child functionality has been added, because there’s still one thing we need to do–we need to extend to classes:

• WPBakeryShortCodesContainer


• WPBakeryShortCode

The first class is responsible for parent elements, the second one is responsible for child elements. So, right after the action function add:

if ( class_exists( 'WPBakeryShortCodesContainer' ) ) {
    class WPBakeryShortCode_nz_Content_Box extends WPBakeryShortCodesContainer {}
}

As you remember, the base of content box parent element was nz_content_box, this name should also be present in the class name that extends the WPBakeryShortCodesContainer class. In our case the new class name is WPBakeryShortCode_nz_Content_Box.

if ( class_exists( 'WPBakeryShortCode' ) ) {

    class WPBakeryShortCode_nz_Box extends WPBakeryShortCode {}

}

The same is true for the child element. The base name was nz_box and the new class name will be WPBakeryShortCode_nz_Box.

Whatever you name your element base it should be present in the new class name.

Now, if you take a look at the page editor one more time, you will see that the new content box element has child/parent functionality.

Building Pages With Visual Composer

After hard work we can reap the fruits of our labor. Take a look at Focuson Theme main homepage. Let’s build that homepage with Visual Composer.

The structure can be split into several sections:

• Presentation Slider


• Content boxes


• Featured projects


• Counters


• Additional info, like “Why choose us” which consists of two columns


• Banner


• Team members


• One more block of additional information with two columns


• Clients testimonials


• Sponsor logos

Recreating this is but the work of a moment with Visual Composer.

We will wrap each block inside the separate “Row” element with at least one “Column” element. As we discussed, this is the required and minimum structure of Visual Composer pages.

Presentation Slider

Focuson theme has integrated the Revolution Slider. The slider is not added with Visual Composer, however, once you install Revolution Slider and Visual Composer, you’ll notice a new element “Revolution slider”. This is a free add-on from Revolution slider, and with that element you can place a slider into the page, even if your theme is not integrated with Visual Composer.

Content Boxes

Remember the example “Content boxes” element? We can build amazing content boxes with our custom element:

Featured Projects

In this section we use 

1. a text_column


2. a gap element, to add space


3. a centered single image (which serves as a nice line divider) 


4. another gap 


5. and the “Recent projects” element

Almost all elements here are custom added.

Counters

For the counters we used row background options (image, and color) for aesthetics. All these options are custom added from Ninzio. We put the counter custom element inside that styled row. 

“Why choose us” Info Block

With Visual Composer columns we can add dual-column content:

Almost all these elements are custom added, only the “Custom Heading” element comes as default with Visual Composer. In the back-end editor it appears asymmetrical, but on the front-end you’ll see a nice-looking structure. Content management is not about simply filling pages, it is also a logical and creative process.You have to take account the dimensions of pictures and text, and consider how they look on different devices. Sometimes responsive corrections are also needed. Fortunately, Visual Composer has the required tools. In columns edit options you can find the Responsive Options tab where you can adjust the column size depending on device groups.

Banner

This is nothing more than a row with a background image and parallax effect, a small amount of content in it with a tooltip, title and buttons.

Team Members

This is an additional element from Ninzio; a carousel of team members. 

“Creative Solutions” Info Block

Again there’s nothing unusual here; an ordinary row element with two columns, each containing content. 

But here the trick is that the image to the right is not located inside the second column, it is actually set as row background image, so the right column here is empty.

Client Testimonials

We have also created a custom element to add testimonials. Again, nothing unusual at play here.

Sponsor Logos

And the last section is sponsor logos. It’s a carousel of logos inside a row with a gray background color. This element is also custom added.

Conclusion

That's it! Now you know everything that is needed to integrate Visual Composer with your Theme and create pages quickly and easily. As a resource for further study, I suggest that you take a look at the official wiki page for Visual Composer. If you have any questions, please feel free to leave a comment below!