Justin Tadlock

Dealing with shortcode madness

At some point in the past year, a disturbing movement has been growing in the WordPress theme development community. If you’ve ever looked at a few themes from Theme Forest, you might have noticed this horrible trend. This isn’t just a Theme Forest issue though; it’s a problem that’s growing in the theme development community and must be eradicated.

Theme developers, please stop bundling shortcodes in your themes that replace basic HTML.

I seriously doubt the Shortcode API in WordPress was built to do things like this. I also propose that using shortcodes in this manner is hurting the theme development community, hindering users’ ability to learn, and creating long term issues that cannot be easily fixed.

An example shortcode

To provide a model in which to present my argument, I’ve created an example shortcode called [note]. There are many shortcodes like it, but I’ll use this as the basis of this discussion. Its purpose is to highlight some text to make it stand out from a post’s normal content.

To use this shortcode, I created some example text in my development install and wrapped it with opening [note] and closing [/note] shortcode tags. In the post editor, it looks like the following:

[note]Hong Kong Phooey, number one super guy. Hong Kong Phooey, quicker than the human eye. Hong Kong Phooey, number one super guy. Hong Kong Phooey, quicker than the human eye.[/note]

That looks eerily similar to something something else many other people use around the Web: HTML. I’ll get to that shortly though.

The following screenshot is what the content looks like when the post is viewed on the front end:

Note shortcode screenshot

This seems like a brilliant idea. Users wrap some text in a simple-to-use shortcode called [note] and magic happens! They have a cool new design for their text. What could possibly be wrong with that?

Problem #1: The “lock in” effect

Users, here’s what theme developers are not telling you: By using their theme’s shortcodes, they are essentially locking you into using their themes forever.

Let’s take a look at what happens when I switch to another theme that doesn’t have the [note] shortcode. The following screenshot is what the text will look like on the front end of the site.

An unrendered shortcode

As you can see, the pretty design for the text is gone and ugly shortcodes are left within the post content. It’s simple enough to delete those shortcodes in a handful of posts, but it’s a huge problem when users have 100s of posts that use this shortcode.

Users either have to figure out a solution to this problem or stick with using the theme. Niether of those options are user friendly.

Problem #2: Replacing basic HTML

HTML and CSS are not hard to learn, especially for something as basic as this. Rather than defining shortcodes, theme developers should define CSS classes for users to use within their posts. There are several benefits to doing this:

  • No “lock in” effect as described earlier.
  • Provide a way for users to learn some of the basic tools of the Web.
  • Allow various elements to use a class, making for more semantic markup.
  • No PHP required to create useless shortcodes.

Instead of the [note] shortcode, create a .note class and drop some simple CSS in your theme’s style.css file. The following is all the code it takes to create a “note” box:

.note {
    padding: 25px;
    font: normal normal bold 13px/25px Arial, Verdana, sans-serif;
    color: #0a5e7a;
    border-top: 1px solid #5ea6bd;
    border-bottom: 1px solid #5ea6bd;
    }

Here’s the great thing: you can use this with any HTML element your heart desires (e.g., paragraphs, lists, headers). The following is just a few example uses of the .note class within the post editor.

<p class="note">This is an example paragraph.</p>

<h2 class="note">This is an example header</h2>

<div class="note">This is an example box you can add several elements within.</div>

I have to believe that anyone smart enough to use WordPress has the capacity to learn how to use the class attribute within an HTML element. It’s possible that I’m wrong, but I have a lot of faith in my fellow WordPress users.

The counter-argument

The only possible argument I can think that theme developers can give is that it’s easier for users to figure out shortcodes than basic HTML. It’s a stretch, but I’ll allow the argument.

Let’s suppose [note] is easier to use than <p class="note">. Maybe there’s something inherently easier about using a [ and ] than < and >. Maybe the latter scares some folks off.

Assuming this argument has any validity, there’s still the problem of the “lock in” effect. The easiest solution to this problem is to create a plugin so that users can carry their shortcodes with them from theme to theme.

If you create a theme with custom shortcodes, do your users a favor and create a plugin that allows them to use their shortcodes even when they switch themes. Or, better yet, someone please create a massive plugin with all the known HTML-replacement shortcodes and end this madness.

Seeing an end to the problem

I previously wrote about this issue in the WPCandy’s 2011 theme predictions article. My fear is that this discussion will fall on many deaf ears and the trend will continue.

So, I have a promise to make. I will personally write the required CSS and fix this shortcode problem for any user that signs up for a support membership at Theme Hybrid. I will never lock you into using only my themes and will provide a way around problems like this. I encourage other theme developers to take similar steps.