Blog

WordPress Shortcodes have become a standard in any premium theme or plugin, just as they should. They allow users to design and organize posts or pages, add functionality and insert elements without learning web development languages and programming techniques.

Even though they are easy to use, there are just a few things that are still difficult with shortcodes:

• Shortcode tags – When you have many shortcodes, it gets tough remembering the name of the shortcode tag you want to use.
• Shortcode attributes – Shortcodes can have many attributes and remembering the name or what each one does is impossible, and you are likely to get some wrong.
• Shortcode editing – When you have use many shortcodes in your content editor, the editing of the content gets messy and it’s hard to understand and follow the content flow.

So, in this tutorial we are going to solve all of these!

The Plan

We are going to create a simple plugin with a shortcode,  then we are going to add a TinyMCE editor button to insert that shortcode trough a popup which will collect all of the user input for the shortcode attributes. Then, we are going to replace the shortcode in the TinyMCE editor with a placeholder image, much like the native gallery of WordPress (which is actually a shortcode, in case you didn’t know), and last – we are going to allow editing of the shortcode and its attributes by double clicking on the placeholder image. For demonstration sake, we are going to create a shortcode for a Twitter Bootstrap panel.

Bootstrap is the most popular HTML, CSS, and JS framework for developing responsive, mobile-first projects on the web. One of its many components is a panel, which is a style box block element and a perfect example to how shortcodes make your job easier. Instead of typing the needed markup each time in your editor you need to type the content of the panel in a shortcode that will output the markup for you.

Demonstration

Sorry for not having voice-over.

The whole plugin is available for download at GitHub

Coding the plugin

We start by creating a plugin directory and structure the files in sub directories that should look like this:

To start coding our plugin, we create a new file named GWP_bs3_panel_shortcode.php in the root directory of our plugin and we load it up with Standard WordPress Plugin Information header.

<?php
/*
Plugin Name: BS3 panel shortcode
Plugin URI:
Description: A plugin to add Bootstrap 3 panel shortcode as a part to the GWP tutorial
Version: 1.0
Author: Ohad Raz
Author URI: https://generatewp.com
*/

Then, we add the main plugin class with the methods we want to implement:

/**
* GWP_bs3_panel_shortcode
*/
class GWP_bs3_panel_shortcode{
	/**
	 * $shortcode_tag
	 * holds the name of the shortcode tag
	 * @var string
	 */
	public $shortcode_tag = 'bs3_panel';

	/**
	 * __construct
	 * class constructor will set the needed filter and action hooks
	 *
	 * @param array $args
	 */
	function __construct($args = array()){}

	/**
	 * shortcode_handler
	 * @param  array  $atts shortcode attributes
	 * @param  string $content shortcode content
	 * @return string
	 */
	function shortcode_handler($atts , $content = null){}

	/**
	 * admin_head
	 * calls your functions into the correct filters
	 * @return [type] [description]
	 */
	function admin_head() {}

	/**
	 * mce_external_plugins
	 * Adds our tinymce plugin
	 * @param  array $plugin_array
	 * @return array
	 */
	function mce_external_plugins( $plugin_array ) {}

	/**
	 * mce_buttons
	 * Adds our tinymce button
	 * @param  array $buttons
	 * @return array
	 */
	function mce_buttons( $buttons ) {}

	/**
	 * admin_enqueue_scripts
	 * Used to enqueue custom styles
	 * @return void
	 */
	function admin_enqueue_scripts(){}
}//end class

Next, we start with the easy part, which is adding the shortcode (implementing our shortcode_handler method) that will accept 3 attributes with content and return our panel markup. The attributes will be:

• Header – Used for panel header/title. If left blank, this part will be excluded from the markup.
• Footer – Used for panel footer. If left blank, this part will be excluded from the markup.
• Type – Used to easily create a panel more meaningful to a particular context by adding any of the contextual state.

Once we have our plan, we can head up to our handy Shortcodes Generator to create a new shortcode with these attributes. A few click later, we get:

// Add Shortcode
function shortcode_handler( $atts , $content = null ) {

	// Attributes
	extract( shortcode_atts(
		array(
			'header' => 'no',
			'footer' => 'no',
			'type' => 'default',
		), $atts )
	);

	// Code
	//make sure the panel type is a valid styled type if not revert to default
	$panel_types = array('primary','success','info','warning','danger','default');
	$type = in_array($type, $panel_types)? $type: 'default';

	//start panel markup
	$output = '
<div class="panel panel-'.$type.'">';

	//check if panel has a header
	if ('no' != $header)
		$output .= '
<div class="panel-heading">'.$header.'</div>

';

	//add panel body content and allow shortcode in it
	$output .= '
<div class="panel-body">'.trim(do_shortcode( $content )).'</div>

';

	//check if panel has a footer
	if ('no' != $footer)
		$output .= '
<div class="panel-footer">'.$footer.'</div>

';

	//add closing div tag
	$output .= '</div>

';

	//return shortcode output
	return $output;
}
add_shortcode( 'bs3_panel', 'shortcode_handler' );

View snippet Clone snippet Download snippet

We are not going to go through this code because its not the point of this tutorial, yet the code is self explanatory and is documented with comments at almost every line.

Next, we are going to add our TinyMCE button by first checking if the user can edit with rich editing. Thus, we implement our admin_head method:

	/**
	 * admin_head
	 * calls your functions into the correct filters
	 * @return void
	 */
	function admin_head() {
		// check user permissions
		if ( !current_user_can( 'edit_posts' ) && !current_user_can( 'edit_pages' ) ) {
			return;
		}

		// check if WYSIWYG is enabled
		if ( 'true' == get_user_option( 'rich_editing' ) ) {
			add_filter( 'mce_external_plugins', array( $this ,'mce_external_plugins' ) );
			add_filter( 'mce_buttons', array($this, 'mce_buttons' ) );
		}
	}

We can now implement our mce_external_plugins and mce_buttons methods:

	 /**
	 * mce_external_plugins
	 * Adds our tinymce plugin
	 * @param  array $plugin_array
	 * @return array
	 */
	function mce_external_plugins( $plugin_array ) {
		$plugin_array[$this->shortcode_tag] = plugins_url( 'js/mce-button.js' , __FILE__ );
		return $plugin_array;
	}

	/**
	 * mce_buttons
	 * Adds our tinymce button
	 * @param  array $buttons
	 * @return array
	 */
	function mce_buttons( $buttons ) {
		array_push( $buttons, $this->shortcode_tag );
		return $buttons;
	}

Last, to finish up our class, we just need to implement admin_enqueue_scripts which we will use to include a CSS file with the button icon style (we are using DashIcons), so:

	 /**
	 * admin_enqueue_scripts
	 * Used to enqueue custom styles
	 * @return void
	 */
	function admin_enqueue_scripts(){
		 wp_enqueue_style('bs3_panel_shortcode', plugins_url( 'css/mce-button.css' , __FILE__ ) );
	}

The constructor should look like this:

	/**
	 * __construct
	 * class constructor will set the needed filter and action hooks
	 *
	 * @param array $args
	 */
	function __construct($args = array()){
		//add shortcode
		add_shortcode( $this->shortcode_tag, array( $this, 'shortcode_handler' ) );

		if ( is_admin() ){
			add_action('admin_head', array( $this, 'admin_head') );
			add_action( 'admin_enqueue_scripts', array($this , 'admin_enqueue_scripts' ) );
		}
	}

One last time, the complete plugin file should looks like this:

<?php /* Plugin Name: BS3 panel shortcode Plugin URI: Description: A plugin to add Bootstrap 3 panel shortcode as a part to the GWP tutorial Version: 1.0 Author: Ohad Raz Author URI: https://generatewp.com */ class GWP_bs3_panel_shortcode{ 	/** 	 * $shortcode_tag 	 * holds the name of the shortcode tag 	 * @var string 	 */ 	public $shortcode_tag = 'bs3_panel'; 	/** 	 * __construct 	 * class constructor will set the needed filter and action hooks 	 * 	 * @param array $args 	 */ 	function __construct($args = array()){ 		//add shortcode 		add_shortcode( $this->shortcode_tag, array( $this, 'shortcode_handler' ) );

		if ( is_admin() ){
			add_action('admin_head', array( $this, 'admin_head') );
			add_action( 'admin_enqueue_scripts', array($this , 'admin_enqueue_scripts' ) );
		}
	}

	/**
	 * shortcode_handler
	 * @param  array  $atts shortcode attributes
	 * @param  string $content shortcode content
	 * @return string
	 */
	function shortcode_handler($atts , $content = null){
		// Attributes
		extract( shortcode_atts(
			array(
				'header' => 'no',
				'footer' => 'no',
				'type' => 'default',
			), $atts )
		);

		//make sure the panel type is a valid styled type if not revert to default
		$panel_types = array('primary','success','info','warning','danger','default');
		$type = in_array($type, $panel_types)? $type: 'default';

		//start panel markup
		$output = '
<div class="panel panel-'.$type.'">';

		//check if panel has a header
		if ('no' != $header)
			$output .= '
<div class="panel-heading">'.$header.'</div>

';

		//add panel body content and allow shortcode in it
		$output .= '
<div class="panel-body">'.trim(do_shortcode( $content )).'</div>

';

		//check if panel has a footer
		if ('no' != $footer)
			$output .= '
<div class="panel-footer">'.$footer.'</div>

';

		//add closing div tag
		$output .= '</div>

';

		//return shortcode output
		return $output;
	}

	/**
	 * admin_head
	 * calls your functions into the correct filters
	 * @return void
	 */
	function admin_head() {
		// check user permissions
		if ( !current_user_can( 'edit_posts' ) && !current_user_can( 'edit_pages' ) ) {
			return;
		}

		// check if WYSIWYG is enabled
		if ( 'true' == get_user_option( 'rich_editing' ) ) {
			add_filter( 'mce_external_plugins', array( $this ,'mce_external_plugins' ) );
			add_filter( 'mce_buttons', array($this, 'mce_buttons' ) );
		}
	}

	/**
	 * mce_external_plugins
	 * Adds our tinymce plugin
	 * @param  array $plugin_array
	 * @return array
	 */
	function mce_external_plugins( $plugin_array ) {
		$plugin_array[$this->shortcode_tag] = plugins_url( 'js/mce-button.js' , __FILE__ );
		return $plugin_array;
	}

	/**
	 * mce_buttons
	 * Adds our tinymce button
	 * @param  array $buttons
	 * @return array
	 */
	function mce_buttons( $buttons ) {
		array_push( $buttons, $this->shortcode_tag );
		return $buttons;
	}

	/**
	 * admin_enqueue_scripts
	 * Used to enqueue custom styles
	 * @return void
	 */
	function admin_enqueue_scripts(){
		 wp_enqueue_style('bs3_panel_shortcode', plugins_url( 'css/mce-button.css' , __FILE__ ) );
	}
}//end class

new GWP_bs3_panel_shortcode();

Moving on. We create our mce-button.css file inside the css directory, which will show the button icon.

i.mce-i-bs3_panel:before {
    font-family: "dashicons";
    content: "\f116";
}

Now we get to the action – we are creating the TinyMCE plugin! Create the mce-button.js file inside the js directory, and start with a standard TinyMCE plugin wrapper.

(function() {
	tinymce.PluginManager.add('bs3_panel', function( editor, url ) {
		var sh_tag = 'bs3_panel';
	});
})();

Following that, we add our popup as a TinyMCE command and the button that will execute that command:

		//add popup
		editor.addCommand('bs3_panel_popup', function(ui, v) {
			//setup defaults
			var header = '';
			if (v.header)
				header = v.header;
			var footer = '';
			if (v.footer)
				footer = v.footer;
			var type = 'default';
			if (v.type)
				type = v.type;
			var content = '';
			if (v.content)
				content = v.content;
			//open the popup
			editor.windowManager.open( {
				title: 'Bootstrap Panel Shortcode',
				body: [
					{//add header input
						type: 'textbox',
						name: 'header',
						label: 'Panel Header',
						value: header,
						tooltip: 'Leave blank for none'
					},
					{//add footer input
						type: 'textbox',
						name: 'footer',
						label: 'Panel Footer',
						value: footer,
						tooltip: 'Leave blank for none'
					},
					{//add type select
						type: 'listbox',
						name: 'type',
						label: 'Panel Type',
						value: type,
						'values': [
							{text: 'Default', value: 'default'},
							{text: 'Info', value: 'info'},
							{text: 'Primary', value: 'primary'},
							{text: 'Success', value: 'success'},
							{text: 'Warning', value: 'warning'},
							{text: 'Danger', value: 'danger'}
						],
						tooltip: 'Select the type of panel you want'
					},
					{//add content textarea
						type: 'textbox',
						name: 'content',
						label: 'Panel Content',
						value: content,
						multiline: true,
						minWidth: 300,
						minHeight: 100
					}
				],
				onsubmit: function( e ) { //when the ok button is clicked
					//start the shortcode tag
					var shortcode_str = '[' + sh_tag + ' type="'+e.data.type+'"';

					//check for header
					if (typeof e.data.header != 'undefined' && e.data.header.length)
						shortcode_str += ' header="' + e.data.header + '"';
					//check for footer
					if (typeof e.data.footer != 'undefined' && e.data.footer.length)
						shortcode_str += ' footer="' + e.data.footer + '"';

					//add panel content
					shortcode_str += ']' + e.data.content + '[/' + sh_tag + ']';

					//insert shortcode to TinyMCE
					editor.insertContent( shortcode_str);
				}
			});
		});

		//add button
		editor.addButton('bs3_panel', {
			icon: 'bs3_panel',
			tooltip: 'BootStrap Panel',
			onclick: function() {
				editor.execCommand('bs3_panel_popup','',{
					header : '',
					footer : '',
					type   : 'default',
					content: ''
				});
			}
		});

This alone will make our button functional and will insert the shortcode. Still, we want too see a placeholder instead of the shortcode, so we are going to use two TinyMCE events: the first is BeforeSetcontent, which is triggered when you set the content or go from the HTML editor to the visual editor. The second is GetContent, which is triggered when you go from the visual editor to the HTML editor. So we add:

		//replace from shortcode to an placeholder image
		editor.on('BeforeSetcontent', function(event){
			event.content = replaceShortcodes( event.content );
		});

		//replace from placeholder image to shortcode
		editor.on('GetContent', function(event){
			event.content = restoreShortcodes(event.content);
		});

Now, let’s define the replaceShortcodes and restoreShortcodes functions with a few little helpers functions:

		//helper functions
		function getAttr(s, n) {
			n = new RegExp(n + '=\"([^\"]+)\"', 'g').exec(s);
			return n ?  window.decodeURIComponent(n[1]) : '';
		};

		function html( cls, data ,con) {
			var placeholder = url + '/img/' + getAttr(data,'type') + '.jpg';
			data = window.encodeURIComponent( data );
			content = window.encodeURIComponent( con );

			return '<img src="' + placeholder + '" class="mceItem ' + cls + '" ' + 'data-sh-attr="' + data + '" data-sh-content="'+ con+'" data-mce-resize="false" data-mce-placeholder="1" />';
		}

		function replaceShortcodes( content ) {
			//match [bs3_panel(attr)](con)[/bs3_panel]
			return content.replace( /\[bs3_panel([^\]]*)\]([^\]]*)\[\/bs3_panel\]/g, function( all,attr,con) {
				return html( 'wp-bs3_panel', attr , con);
			});
		}

		function restoreShortcodes( content ) {
			//match any image tag with our class and replace it with the shortcode's content and attributes
			return content.replace( /(?:<p(?: [^>]+)?>)*(<img [^>]+>)(?:<\/p>)*/g, function( match, image ) {
				var data = getAttr( image, 'data-sh-attr' );
				var con = getAttr( image, 'data-sh-content' );

				if ( data ) {
					return '

[' + sh_tag + data + ']' + con + '[/'+sh_tag+']

';
				}
				return match;
			});
		}

Then, we need to tell our TinyMCE plugin to listen to a double click event on our placeholder image and call the popup with the current values, so we could edit the shortcode:

		//open popup on placeholder double click
		editor.on('DblClick',function(e) {
			var cls  = e.target.className.indexOf('wp-bs3_panel');
			if ( e.target.nodeName == 'IMG' && e.target.className.indexOf('wp-bs3_panel') > -1 ) {
				var title = e.target.attributes['data-sh-attr'].value;
				title = window.decodeURIComponent(title);
				console.log(title);
				var content = e.target.attributes['data-sh-content'].value;
				editor.execCommand('bs3_panel_popup','',{
					header : getAttr(title,'header'),
					footer : getAttr(title,'footer'),
					type   : getAttr(title,'type'),
					content: content
				});
			}
		});

…and once again, the complete mce-buttons.js file contents should look something like this:

(function() {
	tinymce.PluginManager.add('bs3_panel', function( editor, url ) {
		var sh_tag = 'bs3_panel';

		//helper functions
		function getAttr(s, n) {
			n = new RegExp(n + '=\"([^\"]+)\"', 'g').exec(s);
			return n ?  window.decodeURIComponent(n[1]) : '';
		};

		function html( cls, data ,con) {
			var placeholder = url + '/img/' + getAttr(data,'type') + '.jpg';
			data = window.encodeURIComponent( data );
			content = window.encodeURIComponent( con );

			return '<img src="' + placeholder + '" class="mceItem ' + cls + '" ' + 'data-sh-attr="' + data + '" data-sh-content="'+ con+'" data-mce-resize="false" data-mce-placeholder="1" />';
		}

		function replaceShortcodes( content ) {
			//match [bs3_panel(attr)](con)[/bs3_panel]
			return content.replace( /\[bs3_panel([^\]]*)\]([^\]]*)\[\/bs3_panel\]/g, function( all,attr,con) {
				return html( 'wp-bs3_panel', attr , con);
			});
		}

		function restoreShortcodes( content ) {
			//match any image tag with our class and replace it with the shortcode's content and attributes
			return content.replace( /(?:<p(?: [^>]+)?>)*(<img [^>]+>)(?:<\/p>)*/g, function( match, image ) {
				var data = getAttr( image, 'data-sh-attr' );
				var con = getAttr( image, 'data-sh-content' );

				if ( data ) {
					return '

[' + sh_tag + data + ']' + con + '[/'+sh_tag+']

';
				}
				return match;
			});
		}

		//add popup
		editor.addCommand('bs3_panel_popup', function(ui, v) {
			//setup defaults
			var header = '';
			if (v.header)
				header = v.header;
			var footer = '';
			if (v.footer)
				footer = v.footer;
			var type = 'default';
			if (v.type)
				type = v.type;
			var content = '';
			if (v.content)
				content = v.content;
			//open the popup
			editor.windowManager.open( {
				title: 'Bootstrap Panel Shortcode',
				body: [
					{//add header input
						type: 'textbox',
						name: 'header',
						label: 'Panel Header',
						value: header,
						tooltip: 'Leave blank for none'
					},
					{//add footer input
						type: 'textbox',
						name: 'footer',
						label: 'Panel Footer',
						value: footer,
						tooltip: 'Leave blank for none'
					},
					{//add type select
						type: 'listbox',
						name: 'type',
						label: 'Panel Type',
						value: type,
						'values': [
							{text: 'Default', value: 'default'},
							{text: 'Info', value: 'info'},
							{text: 'Primary', value: 'primary'},
							{text: 'Success', value: 'success'},
							{text: 'Warning', value: 'warning'},
							{text: 'Danger', value: 'danger'}
						],
						tooltip: 'Select the type of panel you want'
					},
					{//add content textarea
						type: 'textbox',
						name: 'content',
						label: 'Panel Content',
						value: content,
						multiline: true,
						minWidth: 300,
						minHeight: 100
					}
				],
				onsubmit: function( e ) { //when the ok button is clicked
					//start the shortcode tag
					var shortcode_str = '[' + sh_tag + ' type="'+e.data.type+'"';

					//check for header
					if (typeof e.data.header != 'undefined' && e.data.header.length)
						shortcode_str += ' header="' + e.data.header + '"';
					//check for footer
					if (typeof e.data.footer != 'undefined' && e.data.footer.length)
						shortcode_str += ' footer="' + e.data.footer + '"';

					//add panel content
					shortcode_str += ']' + e.data.content + '[/' + sh_tag + ']';

					//insert shortcode to tinymce
					editor.insertContent( shortcode_str);
				}
			});
		});

		//add button
		editor.addButton('bs3_panel', {
			icon: 'bs3_panel',
			tooltip: 'BootStrap Panel',
			onclick: function() {
				editor.execCommand('bs3_panel_popup','',{
					header : '',
					footer : '',
					type   : 'default',
					content: ''
				});
			}
		});

		//replace from shortcode to an image placeholder
		editor.on('BeforeSetcontent', function(event){
			event.content = replaceShortcodes( event.content );
		});

		//replace from image placeholder to shortcode
		editor.on('GetContent', function(event){
			event.content = restoreShortcodes(event.content);
		});

		//open popup on placeholder double click
		editor.on('DblClick',function(e) {
			var cls  = e.target.className.indexOf('wp-bs3_panel');
			if ( e.target.nodeName == 'IMG' && e.target.className.indexOf('wp-bs3_panel') > -1 ) {
				var title = e.target.attributes['data-sh-attr'].value;
				title = window.decodeURIComponent(title);
				console.log(title);
				var content = e.target.attributes['data-sh-content'].value;
				editor.execCommand('bs3_panel_popup','',{
					header : getAttr(title,'header'),
					footer : getAttr(title,'footer'),
					type   : getAttr(title,'type'),
					content: content
				});
			}
		});
	});
})();

The placeholder images can be downloaded from here, or you could
download the whole plugin from GitHub

There you have it: a shortcode in the ultimate level.

Now, how many of you would like to see a generator for a TinyMCE button like this?..