Page tree
Skip to end of metadata
Go to start of metadata

To add your shortcode to the Visual Composer content elements list, vc_map() function should be called with an array of special attributes describing your shortcode.

<?php vc_map( $params ); ?>

Contents

Parameters

$params Associative array which holds instructions for Visual Composer and is used in "mapping" process.

Param nameTypeDescription
nameStringName of your shortcode for human reading inside element list
baseStringShortcode tag. For [my_shortcode] shortcode base is my_shortcode
descriptionStringShort description of your element, it will be visible in "Add element" window
classStringCSS class which will be added to the shortcode's content element in the page edit screen in Visual Composer backend edit mode
show_settings_on_createBooleanSet it to false if content element's settings page shouldn't open automatically after adding it to the stage
weightIntegerContent elements with greater weight will be rendered first in "Content Elements" grid (Available from 3.7 version)
categoryStringCategory which best suites to describe functionality of this shortcode. Default categories: Content, Social, Structure. You can add your own category, simply enter new category title here
groupStringGroup your params in groups, they will be divided in tabs in the edit element window (Available from Visual Composer 4.1)
admin_enqueue_jsString|ArrayAbsolute url to javascript file, this js will be loaded in the js_composer edit mode (it allows you to add more functionality to your shortcode in js_composer edit mode)
admin_enqueue_cssString|ArrayAbsolute url to css file if you need to add custom css for element block in js_composer constructor mode
front_enqueue_jsString|ArrayAbsolute url to javascript file (useful for storing your custom backbone.js views), this js will be loaded in the js_composer frontend edit mode (it allows you to add more functionality to your shortcode in js_composer frontend edit mode). (Available from Visual Composer 4.2.2)
front_enqueue_cssString|ArrayAbsolute url to css file if you need to load custom css file in the frontend editing mode. (Available from Visual Composer 4.2.2)
iconStringURL or CSS class with icon image. More info here
custom_markupStringCustom html markup for representing shortcode in visual composer editor
js_viewStringSet custom backbone.js view controller for this content element
html_templateStringPath to shortcode template. This is useful if you want to reassign path of existing content elements through your plugin. Another way to change html markup
deprecatedStringEnter version number from which content element will be deprecated. It will be moved to the "Deprecated" tab in "Add element" window and notification message will be shown on elements edit page. To hide element from "Add element" all together use 'content_element'=>false (Available from Visual Composer 4.5)
content_elementBooleanIf set to false, content element will be hidden from "Add element" window. It is handy to use this param in pair with 'deprecated' param (Available from Visual Composer 4.5)
paramsArrayList of shortcode attributes. Array which holds your shortcode params, these params will be editable in shortcode settings page

params Array

Here you should describe all you shortcode's attributes that should be editable with Visual Composer interface. Each shortcode's attribute should be described in separate array element.

Defining "Text" attribute:

array(
  "type" => "textfield",
  "holder" => "div",
  "class" => "",
  "heading" => __( "Text", "my-text-domain" ),
  "param_name" => "foo",
  "value" => __( "This is test param for creating new project", "my-text-domain" ),
  "description" => __( "Enter foo.", "my-text-domain" )
)

Parameters of params Array

Param nameTypeDescription
typeStringAttribute type. In the "Available type values" table you can see all available variations
holderStringHTML tag name where Visual Composer will store attribute value in Visual Composer edit mode. Default: hidden input
classStringClass name that will be added to the "holder" HTML tag. Useful if you want to target some CSS rules to specific items in the backend edit interface
headingStringHuman friendly title of your param. Will be visible in shortcode's edit screen
param_nameStringMust be the same as your parameter name
valueArray or StringDefault attribute's value
descriptionStringHuman friendly description of your param. Will be visible in shortcode's edit screen
admin_labelBooleanShow value of param in Visual Composer editor
dependencyArrayDefine param visibility depending on other field value. Please read Param Dependencies
edit_field_classStringSet param container width in content element edit window. According to Bootstrap logic eg. col-md-4. (Available from Visual Composer 4.0)
weightIntegerParams with greater weight will be rendered first. (Available from Visual Composer 4.4)
groupStringUse it to divide your params within groups (tabs)

Available type values

There are multiple attribute types available, this field is used to "tell" Visual Composer how to handle your attribute in content element edit screen.

ValueDescription
textarea_htmlText area with default WordPress WYSIWYG Editor. Important: only one html textarea is permitted per shortcode and it should have "content" as a param_name
textfieldSimple input field
textareaSimple textarea field
dropdownDropdown input field with set of available options. Array containing the drop down values (either should be a normal array, or an associative array)
attach_imageSingle image selection
attach_imagesMultiple images selection
posttypesCheckboxes with available post types
colorpickerColor picker
exploded_textareaText area, where each line will be imploded with comma (,)
widgetised_sidebarsDropdown element with set of available widget regions, that are registered in the active wp theme
textarea_raw_htmlText area, its content will be coded into base64 (this allows you to store raw js or raw html code)
vc_linkLink selection. Then in shortcodes html output, use $href = vc_build_link( $href ); to parse link attribute
checkboxCreates checkboxes, can have 1 or multiple checkboxes within one attribute
loopLoop builder. Lets your users to construct loop which can later be used during the shortcode's output
cssBasic CSS style editor for your content element. Check "Add "Design Options" Tab with CSS Editor to Your Element" page for more details
...attribute types can be extended with new custom types. Tutorial: Create new param type

Param Dependencies

It is possible to link param with another param by defining dependency param. Dependency param is array with defined param name and values which will allow to display this linked param. Also it is possible to show param field if linked field is not empty and define callback function which will be called when value of linked element is changed. Next table contains field list and explanation of dependency param array keys.

Key nameTypeDescription
elementStringParam name (linked field) which will be observed for changes. Must be the same as param_name param for shortcode attribute
valueArrayList of linked element's values which will allow to display param
not_emptyBooleanDisplay field if value of linked field is not empty
callbackStringjavascript function name. Function will be called when value of linked field is changed

Nested Content Elements

If you are looking for a way to create content elements with "nested" structure, have a look at this example.

Example

In this example you will be guided throw the whole process of adding your own shortcode to the Visual Composer editor. We also prepared a nice and clean "starter" for you, feel free to use it as a starting point for your own Visual Composer shortcode.

Add existing shortcode

For example you have your own shortcode bartag with 2 attributes: foo and bar. More about Shortcode API read in WordPress Codex.

<?php
// [bartag foo="foo-value"]
add_shortcode( 'bartag', 'bartag_func' );
function bartag_func( $atts ) {
   extract( shortcode_atts( array(
      'foo' => 'something'
   ), $atts ) );
 
   return "foo = {$foo}";
}
?>

Now lets call vc_map() function from our functions.php file with an array of special attributes to describe attributes of our shortcode. Important: vc_map() call should be hooked on Visual Composer vc_before_init action.

<?php
add_action( 'vc_before_init', 'your_name_integrateWithVC' );
function your_name_integrateWithVC() {
   vc_map( array(
      "name" => __( "Bar tag test", "my-text-domain" ),
      "base" => "bartag",
      "class" => "",
      "category" => __( "Content", "my-text-domain"),
      'admin_enqueue_js' => array(get_template_directory_uri().'/vc_extend/bartag.js'),
      'admin_enqueue_css' => array(get_template_directory_uri().'/vc_extend/bartag.css'),
      "params" => array(
         array(
            "type" => "textfield",
            "holder" => "div",
            "class" => "",
            "heading" => __( "Text", "my-text-domain" ),
            "param_name" => "foo",
            "value" => __( "Default param value", "my-text-domain" ),
            "description" => __( "Description for foo param.", "my-text-domain" )
         )
      )
   ) );
}
?>

As you can see it has an array of params. This list represents shortcode tag as base and params list which will be editable with settings form inside Visual Composer editor. In params array we have only one element as array with list of params. param_name must be the same as your parameter name. Next most important attribute of params is type. There are a lot of predefined types (all of them you can see here). For foo attribute we'll use "textfield" which is simple input field. Add "heading" and "description" attributes for human friendly title and description of your param. Default attribute value can be added in param attribute "value".

After adding "mapping", you will see your shortcode inside content elements list in Visual Composer editing mode and ability to control access to this shortcode in Visual Composer settings.

More advanced example: Lets say you want to add new special param to your shortcode: lets call it color. First of all, modify your shortcode hook function.

<?php 
add_shortcode( 'bartag', 'bartag_func' );
function bartag_func( $atts ) {
   extract( shortcode_atts( array(
      'foo' => 'something',
      'color' => '#FFF'
   ), $atts ) );
 
   return "<div style='color:{$color};'>foo = {$foo}</div>";
}
?>

Now our shortcode has color param, which it will use as a style for our div on the site's front end. Now we can call this shortcode with [bartag foo="foo-value" color="#000000"]. To make color attribute editable in Visual Composer editing mode we should change mapping settings by adding new param in params list with param_name - 'color' and type - colorpicker. Easy as that!

<?php
add_action( 'vc_before_init', 'your_name_integrateWithVC' );
function your_name_integrateWithVC() {
   vc_map( array(
      "name" => __( "Bar tag test", "my-text-domain" ),
      "base" => "bartag",
      "class" => "",
      "category" => __( "Content", "my-text-domain"),
      'admin_enqueue_js' => array(get_template_directory_uri().'/vc_extend/bartag.js'),
      'admin_enqueue_css' => array(get_template_directory_uri().'/vc_extend/bartag.css'),
      "params" => array(
         array(
            "type" => "textfield",
            "holder" => "div",
            "class" => "",
            "heading" => __( "Text", "my-text-domain" ),
            "param_name" => "foo",
            "value" => __( "Default param value", "my-text-domain" ),
            "description" => __( "Description for foo param.", "my-text-domain" )
         ),
         array(
            "type" => "colorpicker",
            "class" => "",
            "heading" => __( "Text color", "my-text-domain" ),
            "param_name" => "color",
            "value" => '#FF0000', //Default Red color
            "description" => __( "Choose text color", "my-text-domain" )
         )
      )
   ) );
}
?> 

Now you should see new color picker field in Visual Composer edit screen for our [bartag] shortcode.

Some shortcodes has content block. For example: [bartag foo="foo-value" color="#000000"]Here goes content[/bartag]. You can create wysiwyg editor field or simple plain textarea field inside settings form of your shortcode.

Important: Only one wysiwyg editor per content element is allowed and it should have param_name equal to "content".

Lets change your shortcode registration hook.

<?php
add_shortcode( 'bartag', 'bartag_func' );
function bartag_func( $atts, $content = null ) { // New function parameter $content is added!
   extract( shortcode_atts( array(
      'foo' => 'something',
      'color' => '#FFF'
   ), $atts ) );
 
   $content = wpb_js_remove_wpautop($content, true); // fix unclosed/unwanted paragraph tags in $content
 
   return "<div style='color:{$color};' data-foo='${foo}'>{$content}</div>";
}
?>

Now update vc_map() function call, and add new attribute to the params array. vc_map() now should look like this:

<?php
add_action( 'vc_before_init', 'your_name_integrateWithVC' );
function your_name_integrateWithVC() {
   vc_map( array(
      "name" => __( "Bar tag test", "my-text-domain" ),
      "base" => "bartag",
      "class" => "",
      "category" => __( "Content", "my-text-domain"),
      'admin_enqueue_js' => array(get_template_directory_uri().'/vc_extend/bartag.js'),
      'admin_enqueue_css' => array(get_template_directory_uri().'/vc_extend/bartag.css'),
      "params" => array(
         array(
            "type" => "textfield",
            "holder" => "div",
            "class" => "",
            "heading" => __( "Text", "my-text-domain" ),
            "param_name" => "foo",
            "value" => __( "Default param value", "my-text-domain" ),
            "description" => __( "Description for foo param.", "my-text-domain" )
         ),
         array(
            "type" => "colorpicker",
            "class" => "",
            "heading" => __( "Text color", "my-text-domain" ),
            "param_name" => "color",
            "value" => '#FF0000', //Default Red color
            "description" => __( "Choose text color", "my-text-domain" )
         ),
         array(
            "type" => "textarea_html",
            "holder" => "div",
            "class" => "",
            "heading" => __( "Content", "my-text-domain" ),
            "param_name" => "content", // Important: Only one textarea_html param per content element allowed and it should have "content" as a "param_name"
            "value" => __( "<p>I am test text block. Click edit button to change this text.</p>", "my-text-domain" ),
            "description" => __( "Enter your content.", "my-text-domain" )
         )
      )
   ) );
}
?>

This will add new attribute to our [bartag] shortcode and on the edit screen you will see TinyMCE WYSIWYG editor. So with few incremental steps we have taken our simple [bartag] shortcode to the whole new level.