Since WordPress 2.5, Shortcode has proven to be one of the most powerful features that allows lots of room for flexibility and customization. However, as anything that has the word “code” in it, shortcodes are not very user friendly. For people who are used to using WYSIWYG, shortcode usage can be confusing sometimes. This article shows you how to make shortcodes in your themes and plugins more accessible and user friendly.

Shortcode Usability Problems

Take the gallery shortcode for instance. It allows users to include a WordPress gallery in a post or page. Here’s its simplest form:

[ gallery ]

But if the user wants to set more advanced options, such as the number of columns, or the thumbnail size, they’ll have to type in some attributes, which look similar to HTML attributes

[ gallery columns="4" size="medium" ]

This is not user friendly, because of the following three reasons:

  1. To customize a shortcode, most of the time you have to look at the documentation. It’s hard to memorize all the available attributes and values.
  2. Not all users are familiar with HTML syntax, as a result they might get confused about specifying attributes.
  3. It’s easy to make a typo, or specify the wrong value for an attribute.


Shortcode is, after all, code. And code is not user friendly. The less end-users have to “code”, the better.

Therefore, it’s essential that WordPress developers provide a user interface for everything that’s supposed to be customized by users. Shortcode is no exception. The best solution to deal with shortcode, is to add a button to the visual editor’s toolbar, and display a nice GUI to configure all available shortcode attributes.

What we’re going to do next, is create a small plugin that provides such an interface for the gallery shortcode.

Note: WordPress already has an UI to customize the gallery shortcode, but it’s buried deep inside the Media Manager.

So, let’s start with the bare bones of a plugin file. I’ll assume that you already know how to develop your own plugin. Otherwise, here’s your bible.

I prefer the Object Oriented approach, so here’s what I’ve got:

Now, there are two WordPress filters that we’ll be using to add a button to the visual editor’s toolbar.

Go back to your WordPress admin panel, activate your plugin and hook our plugin up with these filters:

Here’s the hard part. Create a new javascript file in the same folder as your plugin file, and name it mygallery_plugin.js.

We’re using tinyMCE’s API to register our editor plugin, and create the button. If you don’t understand what the hell happened above, just close your eyes, and forget about it for a minute (seriously), then proceed with our next step. You can always come back and dig into tinyMCE’s documentation to get a grasp of what the snippet above means.

Now go to your WordPress admin panel, edit or create a new post (or page). You’ll see our tiny little button in the toolbar, preceded by a separator:

If you click the button, nothing happens because you haven’t written any code that handles that part yet. If I cover that part in this article too, it’s going to be too long. So Download the Sourcecode and take a look for yourself. The code is abundant with documentation, but if you have any questions, shoot me a comment!

Here’s a screenshot of the final results: