API – Blocks – Introduction

Available on: Newsmag V1.8+, Newspaper V5+
The td_api_block api call allows you to add or modify a block. Blocks are used to build pages, each block uses one or more modules as a base element. The blocks are accessible from Visual Composer and you can also use them on sidebars (Appearance -> Widgets). The theme comes with several predefined blocks, in the following image you can see how block 1 looks in the frontend:

td_api_block_1_content

 

If you use the API to add a new block it will appear on Visual Composer like this:

td_api_block_77_backend

 

The theme blocks are registered in td_config.php, the code looks like this:

td_api_block::add('td_block_1',
    array(
        'map_in_visual_composer' => true,
        'map_in_td_composer' => true,
        "name" => 'Block 1',
        "base" => 'td_block_1',
        "class" => 'td_block_1',
        "controls" => "full",
        "category" => 'Blocks',
        'tdc_category' => 'Blocks',
        'icon' => 'icon-pagebuilder-td_block_1',
        'file' => td_global::$get_template_directory . '/includes/shortcodes/td_block_1.php',
        "params" => array_merge(
              self::get_map_block_general_array(),
              self::get_map_filter_array(),
              self::get_map_block_ajax_filter_array(),
              self::get_map_block_pagination_array()
        ) 
    ) 
);

Parameters:

$id (string) (required)

  • the block id – if you add a new block the id has to be different from the ones used on the other blocks which are registered in theme, if you plan to modify one of the existing blocks the id has to match with the one you’re planing to modify.

$params_array (array) (required)

  • an array which contains the parameters of the block:
Key name
Type
Description
map_in_visual_composer boolean enable/disable the block appearance in Visual Composer
map_in_td_composer boolean enable/disable the block appearance in tagDiv Composer
name string the block title, it appears in Visual Composer
base string shortcode tag. For [my_shortcode] shortcode base is my_shortcode
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
controls string undocumented VC parameter. Default: “full”
category string category which best suites to describe functionality of this shortcode. Default category: Blocks. You can add your own category, simply enter new category title here
tdc_category string Blocks(tagDiv composer) …
icon string URL or CSS class with icon image, the icon is displayed in Visual Composer
file string the path for the block template file
params array the array of parameters received from the block settings panel

 

Important :

  • the block shortcodes being used by the Visual Composer plugin, the $params_array parameter is used by the plugin to customize the shortcode atts. To accomplish these the ‘base’ setting value (the wordpress shortcode name) must be the same like the $id parameter, and the file of the ‘file’ setting must contain a php class having its name like the $id parameter, all starting with the tagdiv prepend string ‘td’.
  • the ‘file’ setting is mandatory to be present into the $parameter_array, and it represents the file which defines the php class responsible of the shortcode content rendering.