Directory structure¶

{shortcode-name}
├───class-fw-shortcode-{shortcode-name}.php # optional
├───config.php # optional
├───options.php # optional
├───static.php # optional
├───static # optional
│   ├───css # you can put your css files here
│   ├───img
│   │   └───page_builder.png # used as the page builder icon
│   └───js # you can put your js files here
└───views
    └───view.php

Config File¶

The shortcode configuration is a file named config.php placed inside the root directory of the shortcode. It contains an array that must be stored in a $cfg variable and is typically used to provide configurations for the visual page builder.

$cfg = array(
    'page_builder' => array(
        'title'         => __('Demo Shortcode', '{domain}'),
        'description'   => __('Demo shortcode description', '{domain}'),
        'tab'           => __('Demo Elements', '{domain}'),
        'popup_size'    => 'small', // can be large, medium or small

        /*
        // Icon examples
        // Note: By default is loaded {your-shortcode}/static/img/page_builder.png
        'icon' => 'http://.../image-16x16.png', // background color should be #8c8c8c
        'icon' => 'dashicons dashicons-admin-site',
        'icon' => 'unycon unycon-crown',
        'icon' => 'fa fa-btc',
        */

        /*
        // Title Template examples
        //
        // Syntax:
        // * {{- variable }} - Output with html escape
        // * {{= variable }} - Output raw (without html escape)
        // * {{ if (execute.any(javascript, code)) { console.log('Hi'); } }}
        //
        // Available variables:
        // * title - shortcode title (from config)
        // * o - an object with all shortcode options values
        'title_template' => '{{- title }} Lorem {{- o.option_id }} ipsum {{= o["option-id"] }}',
        'title_template' => '{{- title }}: {{- o.label }}{{ if (o.target == "_blank") { }} <span class="dashicons dashicons-external"></span>{{ } }}',
        */
    )
);

For the shortcode to appear in the page builder the config array contains a special page_builder key that holds an array with the following data:

• title - the title that will appear in the shortcode box.

• description - the text that will be shown in a tooltip when hovering the shortcode box.

• tab - the builder tab in which the shortcode box will appear.

• popup_size - the size of the popup in which the shortcode options will be displayed.

  Allowed values are large | medium | small. This parameter is optional and the default is set to small.

Builder icon¶

To set an icon for the shortcode box, put an image named page_builder.png inside {your-shortcode}/static/img/ directory. The image should have the size of 16x16 px.

Options file¶

The shortcode directory can contain a file named options.php with correctly formed options:

$options = array(
    'demo_text'   => array(
        'label'   => __('Demo text label', '{domain}'),
        'desc'    => __('Demo text description', '{domain}'),
        'help'    => __('Demo text help', '{domain}'),
        'type'    => 'text'
    ),
    'demo_select' => array(
        'label'   => __('Demo select label', '{domain}'),
        'desc'    => __('Demo select description', '{domain}'),
        'type'    => 'select',
        'choices' => array(
            'c1'  => __('Choice 1', '{domain}'),
            'c2'  => __('Choice 2', '{domain}'),
            'c3'  => __('Choice 3', '{domain}')
        ),
        'value'   => 'c2'
    )
);

If it does, then it will have an icon when dragged into the builder’s canvas area, indicating that the shortcode can be edited:

When clicking either the edit icon or the shortcode itself, a modal window will open containing the declared options:

The saved options values will be passed into the view file.

Default view file¶

By default, when WordPress wants to render a shortcode built into the framework, it will serve the html from the default view file located in {your-shortcode}/views/view.php. 3 variables are passes into the view file : $atts, $content and $tag.

Static file¶

A shortcode can have a static.php file that is included when the shortcode is rendered. It is meant for enqueuing static files. Here is an example of a basic static.php file:

<?php if (!defined('FW')) die('Forbidden');

// find the uri to the shortcode folder
$uri = fw_get_template_customizations_directory_uri('/extensions/shortcodes/shortcodes/demo-shortcode');
wp_enqueue_style(
    'fw-shortcode-demo-shortcode',
    $uri . '/static/css/styles.css'
);
wp_enqueue_script(
    'fw-shortcode-demo-shortcode',
    $uri . '/static/js/scripts.js'
);

If you want to include custom styles and scripts for a existing shortcode, overwrite the static.php file by creating framework-customizations/extensions/shortcodes/shortcodes/demo-shortcode/static.php.

Class file¶

When creating a shortcode folder with all the required files, the framework makes an instance of FW_Shortcode to ensure the correct default functionality, some of which default functionality can be overwritten by creating a class in the shortcode directory that extends FW_Shortcode.

So in order to create a class for the [demo_shortcode] shortcode, we need to create a file demo-shortcode/class-fw-shortcode-demo-shortcode.php and within the file create a class that extends FW_Shortcode:

class FW_Shortcode_Demo_Shortcode extends FW_Shortcode
{
    // ...
}

The new class inherits some usefull methods like:

• get_tag() - returns the shortcode’s tag.
• get_declared_path($rel_path = '') - returns the path to where the shortcode folder was declared.
• get_declared_URI($rel_path = '') - returns the uri to where shortcode folder was declared.
• locate_path($rel_path = '') - searches a rel path given as an argument first in child theme then in parent theme and last in framework. Returns the found path or false if not found. See overwriting for more details.
• locate_URI($rel_path = '') - does the same as locate_path with uris.
• get_config($key = null) - returns the shortcode’s whole overwritten config array, or just a particular key of it’s given as an argument.
• get_options() - returns the shortcode’s overwritten options array, if there is any.

The methods that are most prone to be overwritten are:

• _init() - is called when the FW_Shortcode instance for the shortcode is created. Useful for loading other php files (custom option types, libraries, etc.).
• _render($atts, $content, $tag) - returns the html that will be displayed when the shortcode will be executed by WordPress. Useful for changing the default behavior with a custom one.

Creating a simple shortcode¶

This example will go through creating the [hr] (horizontal ruler) shortcode in a few simple steps:

1. Create a hr folder in framework-customizations/extensions/shortcodes/shortcodes/.

2. Create a config file inside that folder:

   <?php if (!defined('FW')) die('Forbidden');
   
   $cfg = array(
       'page_builder' => array(
           'title'       => __('Horizontal Ruler', '{domain}'),
           'description' => __('Creates a \'hr\' html tag', '{domain}'),
           'tab'         => __('Demo Elements', '{domain}'),
       )
   );
   

   Note

   At this point the shortcode should appear in the Demo Elements tab of the layout builder as shown below:

   

   Tip

   To add an icon to the shortcode see the icon section.

3. Create a views folder and the view file inside it:

   <?php if (!defined('FW')) die('Forbidden'); ?>
   
   <hr>
   

The [hr] shorcode is completed! The directory structure of the shortcode is as shown below:

framework-customizations/
└─theme/
  └─shortcodes/
    └─hr/
      ├─config.php
      └─views/
        └─view.php

Creating a shortcode with options¶

This example will go through creating the [button] shortcode.

1. Create a button folder in framework-customizations/extensions/shortcodes/shortcodes/

2. Create a config file inside that folder:

   <?php if (!defined('FW')) die('Forbidden');
   
   $cfg = array(
       'page_builder' => array(
           'title'         => __('Button', '{domain}'),
           'description'   => __('Creates a button with choosable label, size and style', '{domain}'),
           'tab'           => __('Demo Elements', '{domain}'),
       )
   );
   

   Note

   At this point the shortcode should appear in the Demo Elements tab of the layout builder as shown below:

   

   Tip

   To add an icon to the shortcode see the icon section.

3. Create an options file with the options for label, size and style:

   <?php if (!defined('FW')) die('Forbidden');
   
   $options = array(
       'label' => array(
           'label'   => __('Label', '{domain}'),
           'desc'    => __('The button label', '{domain}'),
           'type'    => 'text',
           'value'   => __('Click me!', '{domain}')
       ),
       'size' => array(
           'label'   => __('Size', '{domain}'),
           'desc'    => __('The button size', '{domain}'),
           'type'    => 'select',
           'choices' => array(
               'big'    => __('Big', '{domain}'),
               'medium' => __('Medium', '{domain}'),
               'small'  => __('Small', '{domain}')
           ),
           'value'   => 'medium'
       ),
       'style' => array(
           'label'   => __('Style', '{domain}'),
           'desc'    => __('The button style', '{domain}'),
           'type'    => 'select',
           'choices' => array(
               'primary'   => __('Primary', '{domain}'),
               'secondary' => __('Secondary', '{domain}')
           )
       )
   );
   

   Now, when clicking the shortcode inside the canvas area of the layout builder a pop-up window containting the options will appear:

   

4. Create a views folder and the view file inside it. Make use of the $atts variable that is avaialble inside the view, it contains all the options values that the user has selected in the pop-up:

   <?php if (!defined('FW')) die('Forbidden'); ?>
   
   <button class="button button-<?php echo $atts['size']; ?> button-<?php echo $atts['style']; ?>">
       <?php echo $atts['label']; ?>
   </button>
   

   Tip

   For more information about the view variables check out the default view section.

The [button] shorcode is completed! The directory structure of the shortcode is as shown below:

framework-customizations/
└─theme/
  └─shortcodes/
    └─button/
      ├─config.php
      ├─options.php
      └─views/
        └─view.php

Creating a shortcode with related shortcodes¶

This example will go through creating the [icon_box] shortcode. This shortcode will use other shortcodes (aka related shortcodes) to reuse available components and speed up development time.

1. Create a icon_box folder in framework-customizations/extensions/shortcodes/shortcodes/

2. Create a config file inside that folder:

   <?php if (!defined('FW')) die('Forbidden');
   
   $cfg = array(
       'page_builder' => array(
           'title'         => __('Button', '{domain}'),
           'description'   => __('Creates a button with choosable label, size and style', '{domain}'),
           'tab'           => __('Demo Elements', '{domain}'),
       )
   );
   

   Note

   At this point the shortcode should appear in the Demo Elements tab of the layout builder as shown below:

   

   Tip

   To add an icon to the shortcode see the icon section.

3. Create an options file with the options for header, content, icon and button:

   <?php if (!defined('FW')) die('Forbidden');
   
   $options = array(
       'header' => array(
           'label'   => __('Header', '{domain}'),
           'desc'    => __('The box header', '{domain}'),
           'type'    => 'text',
       ),
       'content' => array(
           'label'   => __('Box content', '{domain}'),
           'type'    => 'textarea',
       ),
       'my_icon' => array(
           'label'     => __('Icon', '{domain}'),
           'type'      => 'shortcode',
           'shortcode' => 'ct_icon'
           'tab'       => 'Icon tab label'
       ),
       'my_button' => array(
           'label'     => __('Button', '{domain}'),
           'type'      => 'shortcode',
           'shortcode' => 'button'
           'tab'       => 'More button'
       ),
   );
   

   Please note that we used special param type shortcode. This allows us to render related shortcode params inside a tab with specified label.

   Now, when clicking the shortcode inside the canvas area of the layout builder a pop-up window containting the options will appear:

   

4. Create a views folder and the view file inside it. Make use of the $atts variable that is avaialble inside the view, it contains all the options values that the user has selected in the pop-up:

   <?php if (!defined('FW')) die('Forbidden'); ?>
   
   <div class="ct-icon-box">
       <h1><?php echo $atts['header']?></h1>
   
       <?php echo bee_shortcode_embed('my_icon',$atts, $tag, $content)?>
   
       <div class="content">
           <?php echo $content ?>
       </div>
   
       <?php echo bee_shortcode_embed('my_button',$atts, $tag, $content)?>
   
   </div>
   

   Tip

   bee_shortcode_embed is a Bee extension. For more information about the view variables check out the default view section.

The [button] shorcode is completed! The directory structure of the shortcode is as shown below:

framework-customizations/
└─theme/
  └─shortcodes/
    └─button/
      ├─config.php
      ├─options.php
      └─views/
        └─view.php

Creating an advanced shortcode with a custom class¶

This ex will go through creating a [table_builder] shortcode, it will make use of it’s own custom option type:

1. Create a table-builder folder in framework-customizations/extensions/shortcodes/shortcodes/.

2. Create a config file inside that folder:

   <?php if (!defined('FW')) die('Forbidden');
   
   $cfg = array(
       'page_builder' => array(
           'title'       => __('Table Builder', '{domain}'),
           'description' => __('Creates custom tables', '{domain}'),
           'tab'         => __('Demo Elements', '{domain}'),
           'popup_size'  => 'large'
       )
   );
   

   Note

   At this point the shortcode should appear in the Demo Elements tab of the layout builder as shown below:

   

   Tip

   To add an icon to the shortcode see the icon section

3. A custom option type is needed for the shortcode to be created, because the ones that exist in the framework do not suit our needs.

   1. Create an includes folder and a table-builder option type inside it.

   2. Create a custom class for the shortcode and override the _init() method, to load the custom option type class file.

      <?php if (!defined('FW')) die('Forbidden');
      
      class FW_Shortcode_Table_Builder extends FW_Shortcode
      {
          /**
           * @internal
           */
          public function _init()
          {
              if (is_admin()) {
                  $this->load_option_type();
              }
          }
      
          private function load_option_type()
          {
              require $this->locate_path('/includes/fw-option-type-table-builder/class-fw-option-type-table-builder.php');
          }
      
          // ...
      
      }
      

   3. Create an options file with the custom option type:

      <?php if (!defined('FW')) die('Forbidden');
      
      $options = array(
          'table' => array(
              'type'  => 'table-builder',
              'label' => false,
              'desc'  => false,
          )
      );
      

   Note

   At this point, when clicking the shortcode inside the canvas area of the layout builder a pop-up window containting the options will appear:

   

4. Create the view file and make use of the custom option type’s value.

The [table_builder] shorcode is completed! The directory structure of the shortcode is as shown below:

framework-customizations/
└─theme/
  └─shortcodes/
    └─table-builder/
      ├─class-fw-shortcode-table-builder.php
      ├─config.php
      ├─options.php
      ├─views/
      │ └─view.php
      └─includes/
        └─fw-option-type-table-builder/
          ├─class-fw-option-type-table-builder.php
          ├─static/
          └─views/

Enqueue shortcode dynamic css in page head¶

When the shortcode has options that affect its css, you can populate the style="..." attribute in view.php:

// file:: {theme}/framework-customizations/extensions/shortcodes/shortcodes/{name}/views/view.php

<p style="color: <?php echo esc_attr($atts['color']) ?>;" >Hello, World!</p>

A better solution would be to assign shortcode an unique id and enqueue in head css for that id.

1. Add a hidden option that will generate an unique id

   // file: {theme}/framework-customizations/extensions/shortcodes/shortcodes/{name}/options.php
   
   $options = array(
       'id'    => array( 'type' => 'unique' ),
       'color' => array( 'type' => 'color-picker' ),
       ...
   );
   

2. Output the id in view

   // file: {theme}/framework-customizations/extensions/shortcodes/shortcodes/{name}/views/view.php
   
   <p id="shortcode-<?php echo esc_attr($atts['id']); ?>" >Hello, World!</p>
   

3. Enqueue the main style

   // file: {theme}/framework-customizations/extensions/shortcodes/shortcodes/{name}/static.php
   
   wp_enqueue_style(
       'theme-shortcode-{name}',
       fw_ext('shortcodes')->locate_URI('/shortcodes/{name}/static/css/styles.css')
   );
   

4. Enqueue the dynamic style

   // file: {theme}/framework-customizations/extensions/shortcodes/shortcodes/{name}/static.php
   
   ...
   
   if (!function_exists('_action_theme_shortcode_{name}_enqueue_dynamic_css')):
   
   /**
    * @internal
    * @param array $data
    */
   function _action_theme_shortcode_{name}_enqueue_dynamic_css($data) {
       $shortcode = '{name}';
       $atts = shortcode_parse_atts( $data['atts_string'] );
       $atts = fw_ext_shortcodes_decode_attr($atts, $shortcode, $data['post']->ID);
   
       wp_add_inline_style(
           'theme-shortcode-'. $shortcode,
           '#shortcode-'. $atts['id'] .' { '.
               'color: '. $atts['color'] .';'.
           ' } '
       );
   }
   add_action(
       'fw_ext_shortcodes_enqueue_static:{name}',
       '_action_theme_shortcode_{name}_enqueue_dynamic_css'
   );
   
   endif;
   

Option specific settings¶

Option specific settings are set in options.php shortcode file.

• dependency

You can easily define dependency between options as in example below:

// independent option, no dependency here
    'icons_number' => array(
            'type'    => 'select',
            'choices' => array(
                    '1' => '1',
                    '2' => '2',
                    '3' => '3',
                    '4' => '4',
            ),
            'value'   => '4',
            'label'   => __( 'Number of icons' ),
            'tab'     => __( 'General', 'ct_theme' ),
    ),

// dependent option
    'column_2_title' => array(
            'label'      => __( 'Title:', 'ct_theme' ),
            'default'    => '',
            'type'       => 'text',
            'tab'        => __( "Column 2", 'ct_theme' ),
            'dependency' => array(
                    'element' => 'icons_number',
                    'value'   => array( '2', '3', '4' ),
            )
    ),

Tip

Dependency element name can also be used in connection with ‘shortcode’ option type as well as in widget context.

Tip

Read more about VC dependency here

• Hide an option in widget

When you mapped a shortcode to a widget using Bee_Widget class and you want selected options not to be visible in widget options, just set ‘hide_in_widget’ field to true as in the example below:

$options[] = array(
        'type'           => 'checkbox',
        'hide_in_widget' => true,
);

• Hide an option in VC shortcode

When you want selected options not to be visible in Visual Composer shortcode options editor, just set ‘hide_in_vc’ field to true as in the example below. This is useful when you have a large shortcode mapped to a widget using Bee_Widget class and you wish some options to be visible only in widgets.

$options[] = array(
        'type'       => 'checkbox',
        'hide_in_vc' => true,
);

• Weight / Position

There is an easy way to set option position among other options

$options[] = array(
        'type'       => 'checkbox',
        'position'   => 0,
);

Shortcode specific settings¶

Shortcode specific settings are set in config.php shortcode file.

• custom_markup, js_view, admin_enqueue_js

In Bumblebee you can use helper functions to call default table view in VC backend editor, see example:

$cfg = array(
  'page_builder' => array(
    'title'            => __( 'Team display', 'unyson' ),
    'description'      => __( 'Team display', 'unyson' ),
    'tab'              => __( 'Disrupt', 'fw' ),
    'icon'             => 'fa fa-question-circle-o fa-2x',
    'js_view'          => fw_ext_shortcodes_get_custom_vc_view_name(),
    'custom_markup'    => fw_ext_shortcodes_get_custom_vc_view_markup(),
    'admin_enqueue_js' => fw_ext_shortcodes_get_custom_vc_view_js_uri(),
  )
);

Which should result in something like this:

• show_settings_on_create

Set it to false if content element’s settings page shouldn’t open automatically after adding it to the stage

$cfg = array(
  'page_builder' => array(
    'title'                   => __( 'Single Property', 'ct_theme' ),
    'description'             => __( 'Display a property page', 'ct_theme' ),
    'tab'                     => __( 'Estato', 'ct_theme' ),
    'icon'                    => 'fa fa-building-o fa-2x',
    'show_settings_on_create' => false,
  )
);