I love and hate shortcodes. They are both amazing and awful at the same time. On the one hand, they allow for the inclusion of virtually anything you can imagine within a post’s content. We can go beyond the limits of TinyMCE and basic HTML to include dynamic, sophisticated, elaborate, always-up-to-date, concise elements anywhere we choose.

On the other hand, shortcodes are still code. They are hard to use and difficult to learn for non-coders. Before I learned to code, I found shortcodes extremely challenging and often frustrating. And I can’t begin to count the times I’ve had a page inadvertently destroyed by a client who also found shortcodes confusing. And I’m not at all the only person who feels this way:

https://twitter.com/rob_neu/status/562697755760799744

And those are just a few…

In the end, shortcodes are simply a means to an end. The end being something awesome, but the means…not so much. As a developer, I highly value what shortcodes enable me to do. Things  like:

  • Take complex scripts and make them incredibly concise
  • Execute PHP and Javascript functions in content
  • Easily reuse scripts as many times as I like across a site
  • Update every instance of a script from one place
  • Convert complicated code into relatively simple code

And yet, therein lies the problem. It is relatively simple, but not actually simple. I look at the code required for displaying a contact form on a page and compare it to a Gravity Forms shortcode and find the latter is one thousand times simpler. But it isn’t simple enough when coming from the other direction.

Shortcodes are code

Shortcodes are definitely still code. They prescribe to a very specific syntax and will do nothing other than make you look like an idiot unless you get that syntax exactly correct. And there is no middle ground. Just like with more complex scripting, it is either correct and returns something, or incorrect and returns nothing (or worse, an error).

When I first started working with shortcodes, I found them difficult but they were the only way I could find to achieve my goals. I recall getting really hung up on little things like the order of the parameters, when to use quotation marks, when to use spaces and many other subtle points I now take for granted. I eventually powered through and learned about opening and closing shortcode tags, attributes, nested shortcodes and all the other nuances to the practice. But it wasn’t easy.

Shortcodes defy the WYSIWYG

WordPress has an amazing visual editor which has come such a long way and is hands down the best thing available for creating and publishing content online. Everything written within the TinyMCE interface is rendered basically as it will be on the front end. Well, everything except shortcodes. Those just look like ugly, cryptic phrases wrapped in square brackets. They remind me of when I was younger and watching my mother cook, I’d see her putting nasty things like cottage cheese, onions, mushrooms, peas and the like into dinner and telling me that it would turn out alright in the end. She was usually right. So it goes with shortcodes. Usually, everything turns out alright, for those that know what they’re doing. But what you see is not what you get. What you see is a nasty mess in your editor and to find out if a shortcode is doing what you intend it to do, you must preview the post.

Just look at what WordPress core has been doing in recent major releases with the handling of images and galleries. Beautiful. Dealing with media in the editor is getting more and more intuitive and more closely reflecting the actual output.

Shortcodes can be quirky

Ever tried wrapping them around lots of content? How about nesting shortcodes inside of other shortcodes? Yeah, enough said. This is the reality we are faced with today that those of us who’ve been using shortcodes for a while recognize that they are not perfect and you don’t always get exactly what you expect, even with well made shortcodes.

Worth noting I think that there are over 800 active tickets in WordPress core trac relating to shortcodes. They have a long way to go before they’ll be completely user friendly and quirk-free.

Shortcodes can only be used inside the editor

And what happens if you want to use them outside of the editor? You have to turn on some special plugins or write some code or make a blood sacrifice to some strange deity. It’s annoying. So many times I’ve wanted to toss a shortcode into the sidebar but to do so I need to turn on a plugin or write some code. And if you think using a shortcode inside the editor is tricky, just try using it in your theme. Easy for me now, extremely hard when I got started.

Shortcodes disrupt the composition flow

In this crazy search engine controlled, content focused world, anything that slows down or complicates the process of creating new site content is a problem and shortcodes do just that. When ordinary users are doing what they should be (creating compelling content), too often they find their focus and flow interrupted by the complex implementation of something like a button, box or call to action. I imagine how amazing it would be if authors who wanted to present a part of their article in a two column layout could simply do so with a few clicks and move on rather than what they are currently required to do in most situations which is install some shortcode plugin and refer to the documentation in order to learn where to place those square bracketed statements. Or worse, learn HTML and CSS and use the text view as opposed to visual. This process is easy for those of us with experience but even something simple like that can be depressingly time consuming for beginners. They shouldn’t be required spend so much time learning and previewing to achieve their desired results. They should be spending their time doing what they’re good at and their audience desires which is making more content.

 Shortcodes require us to reference documentation

When I’m working with a shortcode, let’s say a shortcode for displaying posts from a custom post type, and I don’t want the results to link to their respective pages, what do I do? I could guess…maybe there’s an attribute called link…and I could give it a value of “false”….or “no”….or “0”. Or I could hunt down the developer’s documentation and hope against hope that they’ve written up the available parameters for their shortcodes and described all of their accepted values. I can tell you, that is a rare find.

This point really gets to me. There are not many other common elements in a WordPress plugin which traditionally require us to reference the docs in order to make use of the feature. Most plugins have fairly intuitive settings pages and widgets. The shortcodes however, cannot simply be figured out. They lack a UI in most cases. So called “WordPress power users” have grown accustomed to referring to documentation and copying and pasting the shortcode configuration they require.

Compare this to other components in WordPress such as the widgets. Developers create new widgets (a little harder than registering a shortcode, mind you but still not very difficult) and that widget is incorporated instantly into the widget UI and is handled the same way that all other widgets are. Basic users are able to use the widget with little to no learning curve. Shortcodes on the other hand have a similar objective (letting a basic user add a complex element to their content) but no simple interface for using them is provided. And certainly nothing as beautiful as the customizer with drag and drop and live previews.

 Changing shortcodes can be difficult for developers

Imagine you’re Pippin Williamson and you decide that one of your EDD shortcodes would be better off if the receipt shortcode’s parameters accepted boolean values instead of 1s and 0s (just an example). Since there is no UI for adding shortcode (currently), an update to the plugin will not completely transition users to the new method going forward. They will continue using the method they learned, copying and pasting from the docs or their old posts. In instances where a UI is used for pointing-and-clicking to insert the shortcodes and their attribute values, details like this can be changed easily behind the scenes so that users don’t even know they are using the shortcode differently.

Note: we recently finished up an integration with Easy Digital Downloads. Check it out!

Shortcodes leave a mess behind

When shortcodes from a theme or plugin are used and the source theme or plugin is subsequently deactivated, generally the site’s content gets messed up. Instead of nice column layouts with tabs, buttons, lists of related posts, tweet buttons and the like, visitors to the site are presented with broken layouts containing cryptic statements wrapped in square brackets.

This is quite problematic for many users and is a major problem for the platform. Anything that could “lock” a site owner into using a theme or plugin indefinitely is a dangerous issue. Users should have the freedom to use and stop using the software powering their websites. The fact that shortcodes leave a mess behind creates a barrier for users who would like to experiment with alternatives, try out a new design or most importantly, abandon software with security vulnerabilities.

Conclusion

That certainly isn’t all that can be said on the matter of shortcodes. In fact, it is probably just scratching the surface. In general, I’m very passionate about and a huge proponent of better admin UX for WordPress. It is an area where I do not think too much effort can be invested as it is the lifeblood of any long lasting software. Usability is as important, or at this point possibly more important, than functionality.

The work we’ve been doing with Render represents a small part of where I think we should be going. Live previews of shortcodes, the ability to use them anywhere and an intuitive UI are positive steps for usability. Exciting steps indeed and steps I’m quite proud of. However, it is my belief, hope and intention that these steps are only the beginning.