WordPress Plugin Bootcamp Part 3 – Write Post Hacks, Shortcodes and TinyMCE

wpplugins

In parts 1 and 2 we explored API hooks, custom admin pages, custom widgets, saving plugin options and more. Today, I’m going to show you how to get your hands dirty with WordPress’s write post page, which is where a lot of plugins output their main functionality.

We’ll be exploring how to add custom panels, create shortcodes, and interact with TinyMCE to add buttons and insert data. It’s time to dig in!

Custom Panels

WordPress custom fields are an excellent invention, and they have a lot of potential, but sometimes we need something bigger and more versatile than a custom field. That’s where custom panels come in.

Custom panels are the collapsible sections of the Write Post screen that hold give you control over things like Discussion settings, Excerpt, Category, etc. The function we use to do that is add_meta_box(), not to be confused with add_post_meta(), the function that is used to add custom fields.
Add_meta_box accepts 6 arguments-

  • Id – allowing us to the panel later
  • Title – the display title of the panel
  • Callback – the function that outputs the panel’s content
  • Page – what type of page (post? page? link?) the panel should appear on
  • Context – the section of the screen it should appear in – normal (towards to the top) advanced (lower down) or side (to the right with Post Tags and Categories).
  • Priority – Can be ‘high’ or ‘low’, depending on how high it should appear within its page section

For example, your could code this:

add_meta_box(‘webitect’,’Webitect Options’,’print_webitect_panel’,’post’,’normal’,’low’);

function print_webitect_panel(){
	//Get the path to the plugin directory and add the filename onto it
	$panel_file = WP_PLUGIN_URL.'/'.str_replace(basename( __FILE__),"",plugin_basename(__FILE__)).’webitect-panel.php’;
	include($panel_file);
}

The panel file can now include anything you want and will be printed on the Write Post screen. Of course, you’ll have to be mindful of security in anything with the webitect-panel.php file. Tomorrow we’ll take a deeper look at plugin security, but in the mean time you’re welcome to check out WordPress’ example to see how they handled security for their example panel.

Shortcodes

 shortcodes

Next up is shortcodes – and these little guys are a lot of fun. In case you aren’t familiar with them, they are the little pieces of text enclosed in square brackets  used in many plugins which WordPress replaces with whatever the plugin tells it to.

One of the most famous shortcodes is [ngg-gallery], used by the NextGen Gallery plugin to output image galleries inside of posts. As you would expect, WordPress gives us a function called add_shortcode, which accepts a handle and a callback function, allowing us to use it like this:

add_shortcode(‘webitect-poll’,’print_webitect_poll’)

Of course, part of what makes shortcodes so appealing is that they can wrap content as well as contain attributes. An array of those attributes and a string containing the content of the shortcode are both passed to the callback function, so we’ll make sure to take that into account when we write the print_webitect_poll() function. WordPress provides another easy-to-use function (sometimes this plugin authoring seems too easy!) called shortcode_atts which allows us to define available attributes and provide defaults for any that aren’t provided. Using that, print_webitect_poll might look like this:

function print_webitect_poll ( $args, $content ){
extract(shortcode_atts(array(
	'title' => 'What do you say?',
	'success_msg' => 'Thank you for voting!',
), $args));
	return '

' .$title. '

' .$content. '' .$success_msg. ''; }

Now the only thing we need to do when writing a post is type:

[webitect-poll title=”Are You a Freelancer?”]   some content here [/webitect-poll]

Obviously this isn’t a fully functioning example, but it should give you a good idea of how shortcodes work. As usual, you can get the ‘official’ sccop in the WordPress Shortcode API Documentation. But are you going to expect your users to remember what shortcode to use and then type it in? Wouldn’t it be cool if you could just add a button to the visual editor that would insert the shortcode for you? The good news is, you can with a little bit of clever scripting. It’s time to learn how.

TinyMCE

tinymce

TinyMCE is a popular open-source RTE, and the one that the developers of WordPress have made their choice. TinyMCE is a very powerful application itself, which means that we can add some custom functionality in a cinch. In this case, we’ll be adding a button that inserts a shortcode into the editor.
Because TinyMCE is Javascript based, most of the action will happen in a .js file, but we’ll use php to register our script as a TinyMCE plugin:

add_action(‘admin_print_scripts_post_new.php’,’webitect_extend_tinyMCE’);
function webitect_extend_tinyMCE(){
if (current_user_can(‘edit_posts’) && get_user_option(‘rich_editing’) == true){
	add_filter( ‘mce_external_plugins’,’add_tinyMCE_script’);
	add_filter( ‘mce_buttons’,’add_tinyMCE_button’);
}
function add_tinyMCE_script( $plugins){
	$plugins[‘WebitectPoll’] = WP_PLUGIN_URL.'/'.str_replace(basename( __FILE__),"",plugin_basename(__FILE__)).’webitect-poll.js’
	return $plugins;
}
function add_tinyMCE_button( $buttons )
	//Add our button, plus a separator to distinguish it from native buttons
array_push($buttons, "separator", "Poll");
return $buttons;
}

You may have noticed that this section of code introduced several new techniques. First, you saw the action ‘admin_print_scripts_post_new.php’. What does this mean? That is a trick that lets us limit that callback to be executed during admin_print_scripts only on the New Post page. You can do that with any page by adding the filename after the action handle. Also, it used current_user_can() to ensure that nobody gets into anything they aren’t supposed to. We’ll talk about that function a lot more in tomorrow’s post on security. Last it introduced some new filters which you can read more about on WordPress’ Guide to Adding TinyMCE buttons.

So, we’ve registered all the necessary information with WordPress, it’s time to get into the .js file we referenced (webitect-poll.js, in your plugin directory) and work some scripting magic:

(function(){
tinymce.create(‘tinymce.plugins.WebitectPoll’,
{
	init : function(ed, url){
		ed.addCommand(‘insertPoll’,function(){
			var win = window.dialogArguments || opener || parent || top;
			win.send_to_editor(‘[webitect-poll]’);
});
		ed.addButton(‘Poll’, {title:’Add Poll’, cmd:’insertPoll’, image: url +’button.gif’});
	}
}
);
tinymce.PluginManager.add(‘WebitectPoll’, tinymce.plugins.WebitectPoll);
})();

That’s it! We just created a TinyMCE plugin, defined an init function that would add a button and assign a command to that button, and then registered the newly created plugin with TinyMCE’s plugin manager. For the demonstration the only thing that the button does is insert a plain shortcode into the editor, but even that it is incredibly useful, and your imagination is the limit on things you can do with the editor.

 gowordpress

Wrapping Up

You’re getting to be a regular WordPress Plugin expert now! Well, maybe there’s still more to learn but these are some skills that will definitely stand you in good stead. I hope you’ve enjoyed , and if you haven’t read them already, be sure to browse the previous two articles in this series on Getting Started and Custom Widgets, Admin Pages and Options.

Anything I’ve missed, or questions about something left unclear? I’ll be watching the comments!

Written By Nick Parsons

Nick is the editor of Webitect and a developer + designer from Houston TX.

4 Comments

  1. Zach

    July 24th, 2011 at 10:18 am

    Awesome, nice article, nice site.

  2. Ina

    October 18th, 2013 at 02:23 pm

    This is my first time pay a visit at here and i
    am really happy to read everthing at alone place.

  3. Nigel

    November 9th, 2013 at 06:27 am

    Nice post. I used to be checking continuously this blog and I’m inspired!
    Very useful information particularly the final phase :) I maintain such info much.
    I used to be looking for this certain information for a
    long time. Thanks and good luck.

  4. Johnf533

    May 23rd, 2014 at 05:18 am

    I like this weblog so considerably, saved to my bookmarks. kdekeaegkdae

What Do You Think?