In my work reviewing plugins for Tidy Repo and here at TorqueMag I come across shortcodes. A lot. If a plugin has some sort of front-end output, then you can bet that it will use a shortcode to accomplish this task. Shortcodes have made their way into theme development as well, and often times become almost proprietary in nature, chaining a user to a plugin or theme.
In the year 2014, I think it might be time to start looking outside the box, and using the WordPress API more extensively to accomplish our goals.
A Short History of the Shortcode
The Shortcode API was introduced in WordPress 2.5 back in 2008. The first shortcode bundled with core was gallery, which continues to exist in WordPress today, though it is being replaced by a new Media Workflow. In his post about the WordPress 2.5 release, Matt Mullenweg wrote about the benefits users would receive with the upgrade.
They give users a short, easy to type and copy/paste string they can move around their post without worrying about messing up complex HTML or embed codes.
Since then, shortcodes have become handy tools for developers looking to ease the use of complex HTML strings that can get unwieldy in the WYSIWYG. At their best, shortcodes are tied to the functionality of a plugin (and in rare cases, a theme) and handle complex output on any post or page. They offer ease of use and ubiquity, and would only need to be removed if the plugin itself is not necessary. At their worst, however, they try to cover everything and anything, or they pigeon hole users into the functionality of a single theme.
When Shortcodes Get Out of Hand
Unfortunately, there are times when shortcodes are used to try to do far too much. Plugins that contain 100 shortcodes, from layout columns to tabs to alert text. While this may appear to benefit the user, it’s hard for a plugin to be that extensive and well maintained. Chances are, users are coming to that plugin for only one or two of the options included, and the remaining 98 will go unused. And what happens if WordPress changes the implementation of one of those features? How quickly do you think that this will be updated? If a plugin deals with a single group of functionality, it can quickly address problems and expand features. When a plugin tries to do everything at once, it ends up doing none very well.
Another problem with shortcodes that we see is that they can make it very difficult for users to change themes. Justin Tadlock wrote about this a little while ago, voicing his concerns with the use of shortcodes in themes. Justin points to examples where a theme uses shortcodes to replace things like a simple CSS class. Though the effort of adding a shortcode versus adding a class to HTML markup is virtually the same, the shortcode example will fall apart when the user switches themes and they will be left with a WordPress install full of stray [[shortcodes]] to manually clean up.
Luckily, there are some good alternatives which are already in practice. The first that comes to mind is just a little bit of smart filtering. We can find the best example of this right in core, with oEmbed functionality. Previously, you could embed videos from a variety of different services (YouTube, Vimeo, etc.) by using the embed shortcode. Now, however, posts and pages are automatically filtered for single line instances of these URLs and then automatically replaced with embedded media. It’s easy and intuitive for the user, and has an excellent fallback in the form of a link.
Occasionally, I’ll see this practice in other plugins as well. Hammy, a plugin I use for responsive images, automatically filters through images that I have on each page, crops new sizes according to set breakpoints, and then automatically places the correct images according to viewport size. And I don’t have to do a thing. And the best part is, if I deactivate Hammy, my images will fall back to their original sizes until I find a new solution. I think this kind of smart filtering can absolutely replace complex shortcodes in cases where media is involved, or where content is explicitly being replaced. Instead of making the user insert shortcodes that may not be supported in the future, we should try to encourage this kind of seamless integration in plugins where applicable.
Another example I’ve seen out there is probably best handled by Tadlock in Whistles. The plugin aids in creating tabs, accordions and toggles on posts and pages. In order to include those toggle options on your pages, you need to use shortcodes, but content is separated out. What you do is create pieces of content in a separate custom post type, order them together into different “groups” and then output these groups using the shortcode. Decoupling content and output means that small changes can be made fairly easily, and if the content is changed, it will be automatically propagated across all instances simultaneously. Again, just thinking a little outside the box, and from the perspective of a user, we can come up with solutions that are more manageable, and ideally, get away from the robustness I see in some shortcode implementations.
My last example is a simple one. For any theme developers that believe that users can deal with shortcodes better then HTML, when adding a simple HTML class (alert, or mark maybe?), remember that WordPress features a way to add simple buttons to the WYSIWYG editor. Simply add a button for users to click to add whatever class you like. At least if a user switches theme, the markup will remain, even if the button disappears. This is not the duty of the Shortcode API.
As WordPress moves towards a more application-centric core, it will offer us more ways to engage users in terms of their behavior, context and content. Tools like the Hearbeat API, which enables two-way communication to the server. This will allow plugin developers to make choices for the user, without interrupting their workflow. To provide solutions that work when they are needed, and stay out of the way when their not. To leave the shortcode for what it’s good at, concrete representations of abstract functions. The tools are there, we just need to get working.
Jay Hoffmann is a WordPress developer hailing from NYC. In the strictest sense of the word, he is a WordPress enthusiast with an eye for front-end development and design. He has been working with WordPress since 2006 and currently works for a popular children’s media company. This year, Jay started Tidy Repo, a curated list of the best and most reliable plugins from around the web. You can also follow Jay on Twitter.