Practical example – How to add a new Block and Module

Available on: Newsmag V1.8+, Newspaper V6+

I) The code

This section contains an example on how to add a new block and a new module using the theme API plugin method. First create a folder and name it for example “td-api-plugin”, inside the folder create a php file and name it “td-api-plugin.php”, edit the file and add the following code:

<?php
/*
Plugin Name: td-api-plugin
Plugin URI: http://tagdiv.com
Description: tagDiv API plugin
Author: tagDiv
Version: 1.0
Author URI: http://tagdiv.com
*/
class td_api_plugin {
    var $plugin_url = '';
    var $plugin_path = '';

    function __construct() {
        $this->plugin_url = plugins_url('', __FILE__); // path used for elements like images, css, etc which are available on end user
        $this->plugin_path = dirname(__FILE__); // used for internal (server side) files

        add_action('td_global_after', array($this, 'hook_td_global_after')); // hook used to add or modify items via Api
        add_action('admin_enqueue_scripts', array('td_api_plugin', 'td_plugin_wpadmin_css')); // hook used to add custom css for wp-admin area
        add_action('wp_enqueue_scripts', array('td_api_plugin', 'td_plugin_frontend_css')); // hook used to add custom css used on frontend area
    }

    static function td_plugin_wpadmin_css() {
        wp_enqueue_style('td-plugin-framework', plugins_url('', __FILE__) . '/wp-admin/style.css'); // backend css (admin_enqueue_scripts)
    }

    static function td_plugin_frontend_css() {
        wp_enqueue_style('td-plugin-framework', plugins_url('', __FILE__) . '/css/style.css'); // frontend css (wp_enqueue_scripts)
    }

    function hook_td_global_after()    { //add the api code inside this function
// Add a new module
        td_api_module::add('td_module_77',
            array(
                'file' => $this->plugin_path . "/modules/td_module_77.php",
                'text' => 'Module 77',
                'img' => $this->plugin_url . '/images/modules/td_module_77.png',
                'used_on_blocks' => array('td_block_77'),
                'excerpt_title' => 12,
                'excerpt_content' => 25,
                'enabled_on_more_articles_box' => true,
                'enabled_on_loops' => true,
                'uses_columns' => true, // if the module uses columns on the page template + loop
                'category_label' => true,
                'class' => 'td_module_wrap td-animation-stack',
            )
        );

// Add a new block
        td_api_block::add('td_block_77',
            array(
                'map_in_visual_composer' => true,
                "name" => 'Block 77',
                "base" => 'td_block_77',
                "class" => 'td_block_77',
                "controls" => "full",
                "category" => 'Blocks',
                'icon' => 'icon-pagebuilder-td_block_77',
                'file' => $this->plugin_path . '/shortcodes/td_block_77.php',
                "params" => array_merge(
                    td_config::get_map_block_general_array(),
                    td_config::get_map_filter_array(),
                    td_config::get_map_block_ajax_filter_array(),
                    td_config::get_map_block_pagination_array()
                )
            )
        );
    }

}
new td_api_plugin();

The array keys (file, name, class, etc.) are explained on td_api_block and td_api_module sections, we will not go into details about their functionality in this section.

II) The files

The plugin from this example adds a new block and module (77) and as you can see it requires some files, so you have to open the plugin folder and create the corresponding folders and files:

/wp-admin/style.css

/css/style.css

/modules/td_module_77.php

/images/modules/td_module_77.png

/shortcodes/td_block_77.php

td-api-plugin.php

As a start you can copy the file(s) of a theme existing block or module and modify the code inside it to create a new element. For example copy the files for block 3 which uses module 1 and modify their name and the name inside the file (ex. on module 1 rename td-header-style-1 to td-header-style-77, look for similar elements).

The theme modules are located inside ..\Newsmag\includes\modules and the theme blocks files are located inside ..\Newsmag\includes\shortcodes .

The icons used on wp-admin area (visual composer, theme settings, styles, etc) can be found in the theme images folder, ex. for the modules icons can be found in ..\Newsmag\images\panel\modules – and for blocks in ..\Newsmag\images\pagebuilder

When you create a new block or module you also need the css, as you can see in the code we added two static functions: td_plugin_wpadmin_css and td_plugin_frontend_css , they load the css used on the new custom elements. In this case the files contain following css:

/css/style.css

/***************
* Block 77 css *
****************/
.td_block_77 {
    position: relative;
    padding-top: 20px;
}
@media (min-width: 768px) and (max-width: 1023px) {
    .td_block_77{
        padding-top: 17px;
    }
}
@media (max-width: 767px) {
    .td_block_77{
        padding-top: 17px;
    }
}
.td_block_77 .block-title {
    margin: 0px 0px 20px 20px;
}
@media (min-width: 768px) and (max-width: 1023px) {
    .td_block_77 .block-title{
        margin: 0px 0px 17px 17px;
    }
}
@media (max-width: 767px) {
    .td_block_77 .block-title{
        margin: 0px 0px 17px 10px;
    }
}
.td_block_77 .td_block_inner {
    clear: right;
}
.td_block_77 .td-block-row:last-child .td_module_77 {
    margin-bottom: 0px !important;
}
.td_block_77 .td-block-span12:last-child .td_module_77 {
    margin-bottom: 0px !important;
}

/****************
* Module 77 css *
****************/
.td_module_77 .entry-title {
    font-size: 18px;
    font-weight: bold;
    line-height: 24px !important;
    margin: 0px 0px 12px 0px;
}
@media (min-width: 768px) and (max-width: 1023px) {
    .td_module_77 .entry-title {
        font-size: 15px;
        line-height: 21px;
        margin-bottom: 8px;
    }
}
@media (max-width: 767px) {
    .td_module_77 .entry-title {
        font-size: 18px;
        line-height: 26px;
        font-weight: 700;
        margin-bottom: 8px;
    }
}
.td_module_77 .td-module-thumb {
    margin-bottom: 12px;
}
@media (min-width: 768px) and (max-width: 1023px) {
    .td_module_77 .td-module-thumb {
        margin-bottom: 8px;
    }
}
@media (max-width: 767px) {
    .td_module_77 .td-module-thumb {
        margin-bottom: 9px;
    }
}
.td_module_77 .td-post-author-name {
    margin-bottom: 6px;
}
.td_module_77 .td-post-date {
    margin-bottom: 6px;
}
.td_module_77 .meta-info {
    margin-bottom: 5px;
    line-height: 11px;
}
.td_module_77 {
    padding-bottom: 36px;
}
@media (min-width: 768px) and (max-width: 1023px) {
    .td_module_77 {
        padding-bottom: 32px;
    }
}
.td_module_77 .entry-title {
    margin: 0px 0px 11px 0px;
}
@media (min-width: 768px) and (max-width: 1023px) {
    .td_module_77 .entry-title {
        margin-bottom: 7px;
    }
}
@media (max-width: 767px) {
    .td_module_77 .entry-title {
        margin-bottom: 7px;
    }
}
.td_module_77 .td-module-image .td-module-thumb {
    margin-bottom: 12px;
}
@media (min-width: 768px) and (max-width: 1023px) {
    .td_module_77 .td-module-image .td-module-thumb {
        margin-bottom: 9px;
    }
}
@media (max-width: 767px) {
    .td_module_77 .td-module-image .td-module-thumb {
        margin-bottom: 9px;
    }
}
@media (min-width: 1024px) {
    .td_module_77 .entry-thumb {
        min-height: 160px;
    }
}
@media (min-width: 768px) and (max-width: 1023px) {
    .td_module_77 .entry-thumb {
        min-height: 116px;
    }
}

/wp-admin/style.css

.icon-pagebuilder-td_block_77 {
   background-image: url('../images/pagebuilder/block77.png') !important;
    position: relative;
    width: 60px !important;
    height: 44px !important;
    margin-bottom: 0 !important;
    top: 12px !important;
}
.wpb_element_title .icon-pagebuilder-td_block_77 {
    top: -5px !important;
}
.vc_modal-content #td_block_77, .vc_ui-panel-content-container #td_block_77 {
    padding-left: 75px;
}
.td_block_77 .wpb_element_wrapper div {
    display: none;
}
.td_block_77 .wpb_element_wrapper .custom_title {
    display: block;
    font-size: 11px;
}

Details and download:

The css was copied from the theme style.css and it’s the css used by block_3 and module_1, i had to copy it because all classes were changed inside the block and module files, ex. from td_block_1 to td_block_77.

v1.0.2 – Latest version  – download

Older versions:

v1.0.1 – for Newpaper v7.3 or older and Newsmag v3.1 and older – download

v1.0 – for Newspaper v6.5.1 or older and Newsmag v2.2.1 or older – download

Known issues:

Q: I’ve installed the plugin but the new block doesn’t show up in Visual Composer

A: The block must be activated from wp-admin -> Visual Composer -> Role Manager

enable_block77