Informations

45338 views
Medium

Ingredients

  • WordPress v4.5+required
  • Visual Composer Plugin v4.11+required
  • Directly related tutorialadvised
  • Basic PHP/WP knowledge

STEPS

If you’ve used Visual Composer in developing of themes probably you’ve thought at least one time to edit, customize or redefine the default blocks.
Well, this tutorial will explain how to do it, but before to start I strongly suggest you read the basic tutorial to integrate Visual Composer in your themeadvised

1. Where to include your code

As I wrote in other similar tutorials, the code position is a personal choice. Most tutorials on the net recommend to place any function in the functions.php file in the theme folder. I believe instead that it’s better to create a separate file for the Visual Composer setup in which to place all features. In this tutorial, however, I do not take care to explain how to do a require_once in wordpress and then for convenience we start inserting the integration code in the functions.php file of the theme.

2. Link your VC elements’s folder

If you followed the related tutorial that I reported before you’ll have already linked your custom elements’s folder to Visual Composer but let me show you the code once again.
The following function is called BEFORE the Visual Composer initialization:
// Before VC Init
add_action( 'vc_before_init', 'vc_before_init_actions' );

function vc_before_init_actions() {
	
	// Link your VC elements's folder
	if( function_exists('vc_set_shortcodes_templates_dir') ){ 
	
		vc_set_shortcodes_templates_dir( get_template_directory() . '/vc-elements' );
		
	}
	
}

Code explanation

  • row 02: I added an action to the vc_before_init VC hook, so my function will be called before VC init
  • row 07: I used function_exists() to be sure the function that I’ll call exists.
  • row 09: I called vc_set_shortcodes_templates_dir() to include a custom folder to use to override the existing VC shortcodes. Indeed copying a VC shortcode file in this folder you can quickly override the existing shortcode and to add your personal shortcodes (elements) too.
    Please note also I passed as first parameter the function get_template_directory() to get the absolute path of my theme directory and I passed as second parameter the directory name (I had already created that folder into the theme root folder ).

3. Copy the default element to your custom folder

I decided to use standard text element for the tutorial because it isn’t complex to edit.
So, in your WordPress files reach the folder /wp-content/plugins/js_composer/include/templates/shortcodes/ and find the file called vc_column_text.php.
Copy and upload this file in your custom folder in the theme: /wp-content/themes/your-theme-name/vc-elements/.

4. Element “Remapping”

Now our new file is overriding the default file in Visual Composer plugin, so we can go ahead managing the params of the element. We’ll use vc_remove_param('shortcode_slug', 'param_name') and vc_add_params( 'shortcode_slug', $new_params ) to remove and add params to the element. A good way to call these functions is adding an action to the hook vc_after_init.
Before to start to remap the element we have to discover the shortcode slug. To to it I advise to put the element in a page using Visual Composer and to check the text of shortcode: customize-default-elements-visual-composer-3 In this example the shortcode slug is vc_column_text.

5. To REMOVE a Parameter

To remove an existing parameter you have now to discover its param_name. This isn’t easy to do in the plugin core so I suggest an alternative way. Add the element to a page using Visual Composer, then inspect the code of the element options to discover the "name" attribute od the input field you want to remove.
Considering our VC Text element we could decide to remove the CSS Animation and the Extra class name params: customize-default-elements-visual-composer-1 We have to inspect the select input and to check its "name" attribute so: customize-default-elements-visual-composer-2 Let’s do the same with the other field and we’ll know both the names: css_animation and el_class.
Now we can finally preceed to remove the params:
// After VC Init
add_action( 'vc_after_init', 'vc_after_init_actions' );

function vc_after_init_actions() {
	
    //*******************//
    // VC TEXT REMAPPING //
    //*******************//
	
    // Remove Params
    if( function_exists('vc_remove_param') ){ 
        vc_remove_param( 'vc_column_text', 'css_animation' ); 
        vc_remove_param( 'vc_column_text', 'el_class' ); 
    }
		
}

Code explanation

  • row 02: I added an action to the vc_after_init VC hook, so my function will be called after VC init
  • row 11: I used function_exists() to be sure the function that I’ll call exists.
  • row 12-13: I called vc_remove_param() passing as first parameter the shortcode slug and as second parameter the parameter name.
Trick: if you want to completely remove the tab “Design Options” that is present in the most of elements, you can use vc_remove_param so:
vc_remove_param( 'shortcode_slug', 'css' )

6. To ADD a Parameter

If you want to create a new parameter in the element you have to define an array for the options to pass to the vc_add_params() function.
So we’ll edit the previous function so:
// After VC Init
add_action( 'vc_after_init', 'vc_after_init_actions' );

function vc_after_init_actions() {
	
    //*******************//
    // VC TEXT REMAPPING //
    //*******************//
	
    // Remove Params
    if( function_exists('vc_remove_param') ){ 
        vc_remove_param( 'vc_column_text', 'css_animation' ); 
        vc_remove_param( 'vc_column_text', 'el_class' ); 
    }

    // Add Params
    $vc_column_text_new_params = array(
		
		// Example
		array(
			'type' => 'textfield',
			'holder' => 'h3',
			'class' => 'class-name',
			'heading' => __( 'Field Title', 'text-domain' ),
			'param_name' => 'example',
			'value' => __( 'Default value', 'text-domain' ),
			'description' => __( 'Field Description', 'text-domain' ),
			'admin_label' => true,
			'dependency' => '',
			'weight' => 0,
			'group' => 'Custom Group',
		),		
	
    );
	
    vc_add_params( 'vc_column_text', $vc_column_text_new_params ); 
		
}

Code explanation

  • row 17: I initialized an array of arrays because vc_add_params() allows to add multiple params by adding multiple arrays.
  • row 20: I initialized the array that will create my custom parameter.
  • row 21: The field type.
  • row 22: HTML tag name where Visual Composer will store attribute value in Visual Composer edit mode. Default: hidden input.
  • row 23: Class 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.
  • row 24: Human friendly title of your param. Will be visible in shortcode’s edit screen.
  • row 25: Will be the “name” attribute for your field. Use only _ for multiple words and try to add unique names because it will be used to save the data.
  • row 26: Default value
  • row 27: Human friendly description of your param. Will be visible in shortcode’s edit screen.
  • row 28: Show value of param in Visual Composer editor.
  • row 29: Define param visibility depending on other field value (I’ll do a tutorial about this feature).
  • row 30: Params with greater weight will be rendered first respect the other params.
  • row 31: Use it to divide your params within groups/tabs (the position of the tab is influenced by the previous option).
  • row 36: I called vc_add_params() passing as first parameter the shortcode slug and as second parameter the array I just initializated..
customize-default-elements-visual-composer-4

7. To EDIT an existing Parameter

After you have followed the steps 4. and 5. you could decide to edit an existing parameter instead of remove it. To do it you simply have to follow the step 6. using as 'param_name' (row 25) the existing param_name you found in the step .5 (in our example we could decide to edit el_class field adding a default value).
Doing this you’ll still have a el_class parameter but it will be different from the original version.

8. Customize the Shortcode

In the step .3 I cloned the vc_column_text.php file in our custom folder. Now opening this file we’ll see this original code:
if ( ! defined( 'ABSPATH' ) ) {
	die( '-1' );
}

/**
 * Shortcode attributes
 * @var $atts
 * @var $el_class
 * @var $css_animation
 * @var $css
 * @var $content - shortcode content
 * Shortcode class
 * @var $this WPBakeryShortCode_VC_Column_text
 */
$el_class = $css = $css_animation = '';
$atts = vc_map_get_attributes( $this->getShortcode(), $atts );
extract( $atts );

$class_to_filter = 'wpb_text_column wpb_content_element ' . $this->getCSSAnimation( $css_animation );
$class_to_filter .= vc_shortcode_custom_css_class( $css, ' ' ) . $this->getExtraClass( $el_class );
$css_class = apply_filters( VC_SHORTCODE_CUSTOM_CSS_FILTER_TAG, $class_to_filter, $this->settings['base'], $atts );

$output = '
	<div class="' . esc_attr( $css_class ) . '">
		<div class="wpb_wrapper">
			' . wpb_js_remove_wpautop( $content, true ) . '
		</div>
	</div>
';

echo $output;
I added some customizations to meet the remapping of element so you can compare it with the original code:
if ( ! defined( 'ABSPATH' ) ) {
	die( '-1' );
}

/**
 * Shortcode attributes
 * @var $atts
 * @var $el_class
 * @var $css_animation
 * @var $css
 * @var $content - shortcode content
 * Shortcode class
 * @var $this WPBakeryShortCode_VC_Column_text
 */
 
//$el_class = $css = $css_animation = '';
$atts = vc_map_get_attributes( $this->getShortcode(), $atts );
extract( $atts );

//$class_to_filter = 'wpb_text_column wpb_content_element ' . $this->getCSSAnimation( $css_animation );
//$class_to_filter .= vc_shortcode_custom_css_class( $css, ' ' ) . $this->getExtraClass( $el_class );
//$css_class = apply_filters( VC_SHORTCODE_CUSTOM_CSS_FILTER_TAG, $class_to_filter, $this->settings['base'], $atts );

$output = '
	<div class="">
		<div class="wpb_wrapper">
			<h1>' . $example . '</h1>
			' . wpb_js_remove_wpautop( $content, true ) . '
		</div>
	</div>
';

echo $output;

Code explanation

  • row 16 and 20-22: I commented theese rows because I removed those params in the remapping.
  • row 18-19: These 2 rows are commonly present in all VC elements and they basically initialize 1 $var every parameter in the element. Note: the $var_name will be exactly the same of param_name.
  • row 25: I also removed the classes’s variable in the output because after the remapping I have no more params for the css classes.
  • row 27: I added my custom field value saved in the var $example (param_name).
And this is finally our frontend result: customize-default-elements-visual-composer-5

Your Personal Notes