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.
$params Associative array which holds instructions for Visual Composer and is used in "mapping" process.
|name||String||Name of your shortcode for human reading inside element list|
|base||String||Shortcode tag. For [my_shortcode] shortcode base is my_shortcode|
|description||String||Short description of your element, it will be visible in "Add element" window|
|class||String||CSS 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_create||Boolean||Set it to false if content element's settings page shouldn't open automatically after adding it to the stage|
|weight||Integer||Content elements with greater weight will be rendered first in "Content Elements" grid (Available from 3.7 version)|
|category||String||Category 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|
|group||String||Group your params in groups, they will be divided in tabs in the edit element window (Available from Visual Composer 4.1)|
|admin_enqueue_css||String|Array||Absolute url to css file if you need to add custom css for element block in js_composer constructor mode|
|front_enqueue_css||String|Array||Absolute url to css file if you need to load custom css file in the frontend editing mode. (Available from Visual Composer 4.2.2)|
|icon||String||URL or CSS class with icon image. More info here|
|custom_markup||String||Custom html markup for representing shortcode in visual composer editor|
|js_view||String||Set custom backbone.js view controller for this content element|
|html_template||String||Path 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|
|deprecated||String||Enter 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_element||Boolean||If 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)|
|params||Array||List of shortcode attributes. Array which holds your shortcode params, these params will be editable in shortcode settings page|
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:
Parameters of params Array
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.
|textarea_html||Text area with default WordPress WYSIWYG Editor. Important: only one html textarea is permitted per shortcode and it should have "content" as a param_name|
|textfield||Simple input field|
|textarea||Simple textarea field|
|dropdown||Dropdown input field with set of available options. Array containing the drop down values (either should be a normal array, or an associative array)|
|attach_image||Single image selection|
|attach_images||Multiple images selection|
|posttypes||Checkboxes with available post types|
|exploded_textarea||Text area, where each line will be imploded with comma (,)|
|widgetised_sidebars||Dropdown element with set of available widget regions, that are registered in the active wp theme|
|textarea_raw_html||Text area, its content will be coded into base64 (this allows you to store raw js or raw html code)|
|vc_link||Link selection. Then in shortcodes html output, use $href = vc_build_link( $href ); to parse link attribute|
|checkbox||Creates checkboxes, can have 1 or multiple checkboxes within one attribute|
|loop||Loop builder. Lets your users to construct loop which can later be used during the shortcode's output|
|css||Basic 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|
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.
|element||String||Param name (linked field) which will be observed for changes. Must be the same as param_name param for shortcode attribute|
|value||Array||List of linked element's values which will allow to display param|
|not_empty||Boolean||Display field if value of linked field is not empty|
Nested Content Elements
If you are looking for a way to create content elements with "nested" structure, have a look at this 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.
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.
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".
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.
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!
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.
Now update vc_map() function call, and add new attribute to the params array. vc_map() now should look like this:
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.