A Case Against WordPress Shortcodes

At my recent WordPress Developer Meetup, the topic of shortcodes came up as a point of discusion. When talking about it, I realized that I’ve never actually talked about them here on the blog, so I thought it might be worth bringing up for discussion.

For those of you who have seen any of my plugins, you see that none of them include shortcodes despite the fact that people have requested functionality offered by them.

For the most part, I dislike WordPress shortcodes. I think they are unintuitive, difficult to use for the average user, and go against much of what the core functionality of WordPress aims to offer.

But the challenge is that there’s not yet a suitable alternative.

On WordPress Shortcodes (It’s Just Higher Level Markup)

Shortcodes are essentially a higher level form of markup, right?

I mean, there’s very little difference between:

<input type="text" name="gallery" value="123" />

And:

[photo-gallery id='123'][/photo-gallery]

The reason that I take issue with this is that people use WordPress – or other CMS’s for that matter – specifically because they aren’t developers.

Much like developers use higher level languages because we don’t want to deal with the pains of, say, memory management, users use web applications for managing content because they don’t want to deal with the pain of writing markup, stylesheets, or JavaScript.

Yet, when there’s certain functionality that users want to accomplish that a user interface element doesn’t afford, we default to using shortcodes.

“Then Use an Alternative.”

For the most part, when you’re drafting a post with text, images, links, and so on, there’s a 1:1 to correspondence with what the user sees in the post editor and on the public-facing side of the site. We can even improve this using editor-style.css.

But this is the point of tension: Despite the fact that people have experimented with various ways of preventing users from having to enter shortcodes, we aren’t there yet.

On Using Galleries

Case in point: When you insert a gallery into a WordPress post, you’re essentially having WordPress generate a shortcode for you, but instead of displaying the shortcode, it displays a blue region in the post editor.

WordPress Galleries
An example of the result of the gallery shortcode

For anyone who has built products for others using WordPress that, then you recognize that this in and of itself requires a level of education because this breaks what the user sees in the post editor to what the users sees on the public-facing side of the site

On Custom Shortcodes

There are a number of plugins that I maintain that others have requested that I introduce the ability for them to place their features throughout the post rather than at the very beginning or at the very end.

In the context of WordPress development, this is obviously a problem that can be solved by shortcodes. The thing is, I don’t want to educate users on having to write meta-language to use the plugin. I’m not sold on the idea that people want to use a WYSIWYG editor that isn’t quite, y’know, WYSIWYG.

So when it comes for me to introduce these features, I end up feeling like I have to sacrifice some form of personal philosophy.

Well, What Are Our Alternatives?

One of the problems that I dislike about posts that criticize features of existing systems is that that they don’t often offer alternative solutions. I don’t want to be that guy, so I’ll try to share some ideas in hopes of at least getting the discussion going.

Back To The Gallery

I’ll admit, although the gallery functionality isn’t true WYSIWYG, I think it’s certainly a step closer – or an improvement – to using shortcodes.

  • It allows users to build their galleries using an interface
  • It drops a significant user interface element in the post editor that indicates to the author that something other than basic text, anchors, or images exists

The only thing is that there’s still a bit of a gap between what the user sees in the editor and what they see on the homepage, and despite the improvements in WordPress 3.5, some people still have a hard time grokking it.

TinyMCE Options

Another option that I’ve seen implemented (and that I’ve actually done in client work) is to introduce a new button in the TinyMCE toolbar that introduces a prompt or dialog for users to use an interface to select what they want to display or where they want to position something.

This, like the gallery functionality, dynamically builds the shortcodes then inserts it into the post.

I still see this as a bit of a half-baked solution. No, users aren’t having to write any shortcodes, but they are having to see it – or a placeholder – in the post editor that is still preventing them from seeing what their visitors will see.

Go Full-On WYSIWYG

This seems like the most obvious option, right?

With Text

For example, with Single Post Message I only give users the option to display the message above the post content or below the post content.

The truth is, I could give users the ability to place it anywhere within the post content that they like; however, I also believe that there’s something to be said about constraints, but I digress (that’s content for a whole other post).

So if I were to do that, I would need to provide an element that allowed users to edit the content of the message, place it in the content where they like, and make sure it displays exactly as it would on the front end.

With Images

With text, it’s not too bad, but something as complex as a gallery? It’s a bit more of a challenge.

First, we’re limited by the functionality of the TinyMCE editor. Secondly, we have to ask if it even makes sense that users should be able to interact with a gallery in their post editor. Perhaps there’s more middle ground of showing a shot of what they gallery would look like rather than a large blue box.

Even then, there’s the challenge with third-party add-ons. Take, for instance, JetPack – if you end up displaying a slideshow, a carousel, or a mosaic, then you’ve got to handle those cases in the post editor, as well.

As such, this results in an entirely new set of features developers must introduce when building their shortcode-enabled plugins.

But this raises the question: how “interactive” should something like galleries be within the post editor?

Should they work exactly like galleries do on the front end or should they be more-or-less a static screenshot?

If it’s the former, then you move into territory of completely managing galleries inline. If it’s the latter, you’re still leaving a gap of what the end user will see from what the editor is working on.

Where Do We Go From Here?

Obviously, I’m leaving this open ended – although I’ve tried to layout a few scenarios, I obviously don’t have a clear answer.

I imagine that if I did, I wouldn’t be the first come up with one. The fact is, if it were that simple, it would already be part of core.

But that doesn’t mean I don’t spend time thinking about it, and I don’t think developers should stop thinking about it, either. There’s clearly a need to improve the experience, but how we go about doing it is obviously up for debate.

There’s also the issue of whether or not we sacrifice our own philosophical stances on shortcodes if we opt to introduce them into our work despite our misgivings, but I’ll talk more about that later.

72 Replies to “A Case Against WordPress Shortcodes”

  1. Shortcodes are not content, they’re code.

    The point of a content management system is to manage content, not code. So by their very nature, shortcodes are not a solution, but a problem. And worse, they’re a hack.

    They offer an awful way of managing content and I really don’t have any idea how they became so popular. I imagine it’s only because there’s no other easy way of putting arbitrary non-text content into a post. When I build WP based sites for clients, I create lots of custom fields for content so that they never need to uses shortcodes.

    The shortcode nonsense reveals WordPress’s fundamental historical restriction: that it was only really designed to create simple text and image content. Now that it can do so much more, it’s time that the functionality of the the main post editor box was overhauled, or even replaced.

    I don’t think the question is “how do we handle shortcodes better”, I think the question is “How do we make WordPress a true CMS that’s unrestricted by its historical development?”

    The only way to make WordPress a truly flexible content management system is to start over. Radical I know, but It really needs a major rethink: perhaps instead of the single main content box, it should move to some sort of page layout builder using widget type content blocks and/or something like Advanced Custom Fields. An interface that anyone can use, not just developers. I know there are plenty of tools that try to offer that sort of functionality on-top of the normal WP edit screen, but to be honest they are all quite hacky.

    I firmly believe WP needs a core overhaul to offer a truly WYSIWYG drag-and-drop page-layout engine, or it’s simply gonna always feel like an incomplete, hacky CMS that needs work-arounds like shortcodes.

    1. They offer an awful way of managing content and I really don’t have any idea how they became so popular.

      I can’t speak to how they got started, but I think the reason that they become popular is because developers – especially open source developers – don’t often think about the end result in mind.

      Take any given problem, and a developer is likely to picture the available solution if it already exists. If shortcodes are that solution, then they are apt to use them, and I think that’s where it stops.

      We need to do a better job of inverting our approach to think of the user – like you mentioned – to using custom fields or something along those lines.

      I don’t think the question is “how do we handle shortcodes better”, I think the question is “How do we make WordPress a true CMS that’s unrestricted by its historical development?”

      These are dangerous waters to tread. You’re braver than me, Matt :). The reason that I’m hesitant to completely head into this is because of the amount of legacy support.

      I do believe in the nature of iterative development (not implying that you don’t, of course), and of maintaining compatibility for a while (though not too long; otherwise, see IE6), so focusing on improving this in terms of iterations so that the thousand of plugins that already use shortcodes are completely terminated is going to be key in this migration.

      That said, I think the UI team is headed in the right direction in terms of improving the editor, but rather than starting over from scratch, perhaps enhancing the API of the TinyMCE editor?

      Again, just throwing out additional suggestions, but something‘s gotta give.

      1. He he, well I wouldn’t say I’m brave; perhaps foolish ;-)

        There’s no question that WP is an awesome piece of software and the progress made in the last year or so has made it even better. The new Media Management interface for example is fantastic and I’m very keen to see what similar UX/UI improvements can be made in the future.

        However, as long as we still need to use workarounds like shortcodes for managing inline content, using WP is going to always feel a bit like bashing a square peg into a round hole. Look at widgets for example: they’re very useful, but why are they managed on a completely separate screen from the pages they’re displayed on? Lots of legacy stuff like this made sense when it was just for simple blogs, but with new CPTs and complex functionality being added to WP sites, these kinds of UI issues need to be reviewed and improved.

        I realise saying something like “Start Over!” is radical and has huge implications. I certainly won’t pretend that I would even know where to start: I don’t. But I do worry that infinite backwards compatibility is restricting where WP could go in the future. It’s a great CMS, but a lot of the cool stuff that it can do isn’t possible “out of the box” and I just feel perhaps it’s time to start looking at what exactly is in the box, what customers are asking for, and questioning if that box needs to be changed for a new one… :-)

        Sorry, I realise I’m going off-topic from the shortcodes issue, but I do firmly believe with a better backend interface, WP wouldn’t even need a “solution” like shortcodes. That was really my point… :-)

        1. Look at widgets for example: they’re very useful, but why are they managed on a completely separate screen from the pages they’re displayed on?

          This is another good point that would be a topic for a good point. A related – though off topic, but while we’re at it – is widgets being added to sidebars when sidebars now span the widget of, say, footers.

          It’s more just widgetized areas, you know?

          At any rate, I see all of these things as ways to continue to improve WordPress. The thing is, I hate when people offer problems with no solutions so I try not to do that with my blog (as I mentioned above).

          So, to that point, I’m going to stop talking about widgets here until I can spend more time on it ;).

          Plus, I think the UI and the UX guys will do a better job of providing solutions that I would.

          1. It’s more just widgetized areas, you know?

            Yes, I completely agree: the whole of WP’s interface needs a major rethink in my view.

            Have you used SquareSpace at all? Their drag-and-drop system is very cool and exactly the sort of thing I’d expect from a modern, flexible CMS. And it’s the sort of approach that WordPress needs to take at some point (and soon) or it’s going to be left behind.

            On the flip-side, I’ve seen a lot of devs ditch WordPress and move over to static sites. Systems like Statamic and Kirby seem to suit many devs a lot better as they are completely flexible in terms of build and output. Those tools don’t suit “normal” users though, and for the majority of users you have to go completely the other way: no coding at all and just a super slick, drag-and-drop type system, such as SquareSpace.

            WordPress may be the most used CMS on the planet, but at some point it needs to ditch its legacy and do something radical and new or its simply going to stagnate.

  2. Awesome post. I totally agree with you and I don’t think this topic is brought up enough. I’ve been looking into replacing shortcodes with a placeholder image (like the image gallery) as I think it’s currently the best option. Let me know if you find any tutorials on that.

    1. Thanks Patrick!

      I’ve been looking into replacing shortcodes with a placeholder image (like the image gallery) as I think it’s currently the best option.

      In some cases, I agree. I think that it all depends on exactly what you’re looking to achieve.

      Sometimes, I think using custom meta boxes, custom fields, and the like offer some flexibility that others don’t often consider. I’m not saying they are the best solution, but I think they should be considered as viable options, in some cases.

  3. It depends on the context I suppose.
    Shortcodes shouldn’t be used where a carefully thought out custom interface can be used. With the help of custom fields, and repeatable groups, you can avoid the use of shortcodes.
    In publicly released themes, it’s another story, I think the theme should not include shortcodes for the end user. (Hybrid has shortcodes for use in templates for outputting the post date for example, instead of a function call, which is a valid use case)
    The discussion often comes up in the theme review team and the generally accepted answer is to not include them.
    In a plugin I made, I added a tinyMCE button to include the shortcode which makes it a bit easier for the user, but I probably agree that it’s better to avoid if possible.
    Shortcodes that just replace HTML with no real simplification are useless. For example
    [div id=”my-div”]some text[/div]

    1. Shortcodes shouldn’t be used where a carefully thought out custom interface can be used. With the help of custom fields, and repeatable groups, you can avoid the use of shortcodes.

      Agreed so long as the end user understands repeatable groups. Sometimes, I’m not even sure they do. I think that it’s our responsibility to provide the necessary guardrails to guide the user to their end goal.

      Hybrid has shortcodes for use in templates for outputting the post date for example, instead of a function call, which is a valid use case.

      I’ve not used Hybrid so I don’t want to come off as critical, but I’ve seen similar implementations. But is this the proper use of shortcodes?

      Why not expose options in a meta box that allow users to set the settings, or does it have to be placed within the middle of the post? And, if so, why not introduce a series of options that the user can select through prompts to build what they need?

      Of course, I’m playing devil’s advocate, but I have to do so considering I wrote the post.

  4. Okay, I’m going to go out on a limb here and (partially) defend shortcode. I know, I know. As a UI Engineer, this could get me shot. Nevertheless, I think it has it’s place…

    One thing that I think should be baked into core, or at least into any good theme, is a settings page where the website administrator can enter important information about the company. Things like the company name (which might differ from site title), address, telephone number, hours of operation, embedded map for directions, social media pages, etc.

    In that case, allowing an end user to enter [company-name] or [company-telephone] in the body of a post or page is very intuitive and self-evident. The brackets and generic terms indicate that this is information being pulled from elsewhere, and is very similar to boilerplate documents that most people are familiar with.

    I do agree that when you start introducing parameters or non-text shortcode output, that things start to get ugly. For that, a good solution _might_ be to filter the content in the TinyMCE visual editor and actually do_shortcode right there…although the resulting output would need to be static and appear in a visible container to indicate that.

    Anyway, that’s my two cents. I agree with Matt Hill’s comment that, in a perfect world, all content should be manageable on a single screen, but I also believe in managing one thing at a time…and if you have the ability to, say, alter your photo gallery from within your post, things could get a little hairy. You would need to open up a separate modal and basically AJAX in the other content editor screen.

    1. One thing that I think should be baked into core, or at least into any good theme, is a settings page where the website administrator can enter important information about the company.

      There’s a tension here – WordPress tries to push decisions not options and introducing an options page for stuff like this rubs up against that.

      Why not allow them to use widgets and introduce widgetized areas? Or page templates with custom fields?

      Again, this is just meant for me to play devil’s advocate, but I do have a visibly hard stance against shortcodes. They are an absolutely last resort, if not a last resort at all ;).

      1. Widgetized areas are great, and custom fields have their place, but for the use case I described (company info) both seem like overkill.

        I stand by my idea of enabling admins to enter static information about the company in a single place, and then allowing them to insert it dynamically anywhere on the site using shortcode. That way, if the company information changes, those changes can easily be made from a single settings panel.

        This would be no different than creating a ‘user’, except that the ‘user’ data would pertain to the company. And as we all know, businesses are people too. ;-)

  5. I think, as with nearly everything it seems, “it depends.” It depends on who the user’s going to be and the functionality he or she really needs, along with the tools wanted, considering the level of sophistication and comfort using what’s basically a just a macro. Not what we as developers and designers feel like giving them, or think will appeal to them more than the next guy’s bundle of shortcodes.

    I see shortcodes as a bridge; a means to and end when, as you pointed out, there aren’t better, more ‘local’ alternatives other than using a shortcode API.

    I think if ease-of-use is the top priority, then each function needs to be addressed individually. For example, to continue with your gallery example, a better idea may be to allow the user to select which images they want in a gallery in the media area or from a modal window with simple drag and drop alongside their post, and simply click a button to insert it where they’d like. Having them navigate through screens just to collect ID’s, jot them down, then go back into the editor and “code” (albeit ‘short’) them in themselves is definitely half-baked. Not to mention a cross-referencing hassle. A completely different set of functions and steps is obviously required for other effects that are often shortcoded and packaged all together: toggles, buttons, columns, accordions, etc…

    I think the source of the problem, if there really is one, is that we’re trying to find the right balance of ease of use for the user against what’s easiest and best, and available to us at the moment, for devs to offer the most functionality. And we go to the the same solution for myriad pain points that need individual and better-thought-out, more narrowly-focused solutions. But until we’re given better options by the WordPress core than an API, or someone can mastermind a better solution, that’s what we’re stuck with. And sometimes it is the most elegant solution and a perfect fit for the user.

    1. It depends on who the user’s going to be and the functionality he or she really needs, along with the tools wanted, considering the level of sophistication and comfort using what’s basically a just a macro.

      I can agree with this, but I don’t want to settle for this, if that makes sense. If a user is comfortable with it, then go for; however, I don’t want to use this as a justification for not trying to create something that’s a bit better.

      But you hit directly on this:

      I see shortcodes as a bridge; a means to and end when, as you pointed out, there aren’t better, more ‘local’ alternatives other than using a shortcode API.

      And that’s what I want to help improve or contribute to – providing better, more local alternatives rather than the shortcode API.

  6. I think shortcodes were largely adopted because of a lack of flexibility with the WordPress content editor.

    In WordPress, we are able to utilize the_content() and not much else for, well, content. The excerpt has its own limitations. So if we are to utilize flexible content in any other way, it’d have to be with a custom meta box and replicated wp_editor(). Shortcodes are simply a byproduct of these limitations and the relatively high barriers to creating various layouts.

    I shared it in my first Post Status newsletter (sorry for the shameless plug), but I think greater flexibility for theme and plugin authors to define content areas can be a more natural solution. I know it would mean some challenges from a data storage standpoint, but I think it’d make it better.

    I wouldn’t blame developers, per say, for the lack of consideration to an average user. I’d say most were doing their best to meet feature requests and client demands to enable unique content layouts.

    Anyway, I still largely agree with you, and prefer a TinyMCE solution over asking users to use shortcodes. But based on my experience with clients, they are better w/ shortcodes than html, even though I hate admitting that.

    1. Shortcodes are simply a byproduct of these limitations and the relatively high barriers to creating various layouts.

      Agreed in that they are a byproduct of “days gone by,” so to speak, and I’m not even against removing them completely especially when it comes to compatibility issues (see this comment for my thoughts on that particular part of it).

      The problem that I see with them is that:

      It’s somewhat of a perpetual problem. Not enough of us (read: those who design and/or develop things for WordPress) are providing suitable alternatives for others to follow suit. I’m guilty of this, too, but I’m doing what I can to change that.
      As long as developers care more about getting something out the door than caring about providing an elegant solution to their users, we’re going to continue to have shortcodes.

      I think greater flexibility for theme and plugin authors to define content areas can be a more natural solution.

      Yes. Agreed. I think this is actually an awesome starting point for brainstorming what the editor or the editor options would look like in a “world without shortcodes.”

      Definitely gonna ruminate on this a bit. Might draft up a future post if I can think of anything that would be worth sharing. My UI design may be better suited for a comedic blog.

      I know it would mean some challenges from a data storage standpoint, but I think it’d make it better.

      That’s what development is all about – overcoming a challenge and solving that problem :). Of course, I’m just preaching to the choir here. Basically, if the challenge to providing a more elegant solution is a problem of data storage, then we have greater problems that shortcodes ;P.

      They are better w/ shortcodes than html, even though I hate admitting that.

      Ha! Yeah, I’ve had mixed results. Once you educate them, they normally get it – most do, at least – but I’d love to be able to eliminate that one gap from the process of the hand off.

      We’re a long ways off yet, but I think having conversations about it is one place to start.

      Oh, and don’t apologize for the shameless plugin. Doesn’t bother me to see others spreading their good work. I’d just mark it as spam if it were otherwise ;).

  7. Shortcodes can be very confusing for clients and end users, I agree 100% with your points, they simply do not belong inside content like a text editor.

    Even though you want to design a system without using them, in reality people have budgets and time constraints and they often show up.

    One solution I have been using is to always register CPT’s and extend the template hierarchy a lot to use `do_shortcode`. Sure it adds a bit of template bloat but at least client never has to see a shortcode.

    Having a WYSIWYG button submit the shortcode is pretty hacky solution, it’s certainly better than having them remember how to type a shortcode with parameters, but again your adding code markdown where it does not belong.

    I think the real solution is to have a dynamic visual edit page that allows you to place text and custom functionality in “blocks” , which is the traditional CMS way to do it. The blocks could be re-arranged the same way widgets in a sidebar are via drag-drop, and have actual visual output, like the gallery block actually shows the pics and not some wierd blue camera.

    Of course the above is already possible with WordPress, it just requires a lot of work.

    1. Even though you want to design a system without using them, in reality people have budgets and time constraints and they often show up.

      This is true. I don’t mean to come off representing a pie-in-the-sky solution, because I’m totally used to working under these types of constraints.

      But the desire for something better comes directly from these constraints, you know? Experiencing the pain clients feel when they have to understand a meta-language (no matter how simple it is for developers) is something that I’d love to do way with.

      Sure it adds a bit of template bloat but at least client never has to see a shortcode.

      I think that this is a fair trade. When it comes to providing solutions to others, I’m far more willing to take a hit at the code level (read: implement something slightly more complex) to make their use case that much better.

      Having a WYSIWYG button submit the shortcode is pretty hacky solution, it’s certainly better than having them remember how to type a shortcode with parameters, but again your adding code markdown where it does not belong.

      Yep – it’s a half-baked solution, at best but I’ll admit that I’ve gone this route to at least try to meet them halfway.

      Clearly though, I’m trying to strive for something more.

      1. You can always tailor a theme or even 3rd party plugins to “hide” shortcodes behind the scenes, but the problem is making a system flexible enough to accommodate the current shortcode functionality intuitively into a UI.
        I think the only way plugins could tie into this is with a really robust Form/Meta Box API. An idea would be to extend the current “meta box” into shortcode parameter fields that could then be dragged around. You see this in “other” CMS’s with drag + drop functionality, such as:

        Title Box
        Text box
        Shortcode box — (really just a formwith a bunch of inputs)
        Text box
        Meta Box
        Text box
        etc..

        I don’t think it would be incredibly difficult to do this, but then again is there a demand for it.

  8. I think it’s dependent on the situation. For example, I think shortcodes are an appropriate solution for some UI elements like tab groupings and the like vs straight html. If developers had to explain to users how to write the appropriate html and enqueue the appropriate javascript to get their tab interface working, it would be a mess. But teach them to use `[ tabs ]` and `[ tab ]` and you will gain traction.

    1. In my 20 year career, I’ve trained a lot of people in how to use lots of different CMSs. I can confidently say that NONE of those people wanted to deal with anything that wasn’t “obvious”.

      HTML and WordPress shortcodes are non-obvious to most users and when you watch real users try to manage content using anything other than a simple point-and-click/drag-and-drop system, one begins to understand why “solutions” like shortcodes just make the problem worse.

      Users want simpler solutions that require as little thinking as possible. Shortcodes don’t provide that, however you look at it.

  9. Shortcodes are awesome. It’s much easier to deal with shortcodes than giant blocks of HTML. How else are you supposed to insert contact forms, galleris, product showcases etc.?

    1. How else are you supposed to insert contact forms, galleris, product showcases etc.?

      How else indeed!? Your comment neatly highlights the fundamental problem with how WordPress currently works.

      Shortcodes may be an available “solution” in WordPress, but they are not elegant nor friendly to most users. It’s time WordPress started thinking about a more modular, visual way of building page so that shortcodes can finally be put to rest. They have no place in a modern CMS.

      1. I think shortcodes aren’t friendly when user’s are to remember what all the parameters are, how the work, etc, but when given an interface, they can be very effective. Orman Clark’s themes have an interface that allows to you pick what parameters to use ( here’s how to add tabbed content, for example: http://cl.ly/NPfJ ) and I built a much simpler version that works as well.

        I think if WordPress implemented an api that allowed us to do that like Orman did, it would help in the long run. Honestly though, I don’t think shortcodes are that bad. They give end users an avenue of adding custom content here and there that might not be better implemented via custom fields. How can you insert something in the middle of a post via a custom field? You can’t, at least I can’t think of a way to do so without some form of key (like a shortcode) to insert that content. I think they’re just like using a templating language like Mustache or Liquid. They have their place. Curious your thoughts.

    2. How else are you supposed to insert contact forms, galleris, product showcases etc.?

      That’s exactly my point! :).

      They’re “awesome” because they are our only option (for now, at least). What I’m talking about here in this post is a call-to-action for us to begin working on something that’s even easier (and that’s truly “awesome”).

  10. Shortcodes are handy workarounds at first glance but a pain later when the shortcode itself or parameters are forgotten and have to be looked up.
    They could be replaced with meta boxes below the editor and beside which allow options and possible insertion points to be set. Of course this would mean lots of work but at the end the simple user would just expand the metabox below the post, page or custom post type and start clicking and filling out fields. I learned from my customers that those click-and-fill boxes are mostly appreciated and short codes often earn me lengthy support-hours.
    At the end there will always be some kind of short code or reference if one wants to insert something at an exact position into text. But this short code should be produced by the above described boxes and simply dropped into place.
    What about that for future work? :-)

    1. Shortcodes are handy workarounds at first glance but a pain later when the shortcode itself or parameters are forgotten and have to be looked up.

      And this is true regardless of if you’re a developer or an end user, so it goes to show that even though the use case for our customers is rough, we can suffer from their implementation, as well.

      Of course this would mean lots of work but at the end the simple user would just expand the metabox below the post, page or custom post type and start clicking and filling out fields.

      Yes, I agree. The thing is – and you’re not the first person to mention that it would take a lot of work – is that I see this as our job as developers. We do the work so the users don’t feel the pain, you know?

      short codes often earn me lengthy support-hours.

      I know that fee, bro.. :)

      At the end there will always be some kind of short code or reference if one wants to insert something at an exact position into text.

      I’d like to believe that we can move beyond this, but it’s going to take some seriously advanced work in the editor view. With the stuff that’s coming available in HTML5, CSS3, and JavaScript, I don’t think it’s a pipe dream.

      It’s just a matter of time.

  11. I don’t hate shortcodes, but you’re right there is a lot of room for improvement.

    One thing I’ve gotten used to explaining to clients is that the wp editor is a visual editor NOT a WYSIWYG editor. This is a bigger issue for many than just shortcodes and editor-style.css doesn’t fix the fact the H3 may be totally different on one page than another. /OT

    Back to shortcodes, I’ve long wanted something I call an ‘image object’ (probably not the best term for it). In essence when I insert an image in the post editor I want that image object to be able to dynamically pull image metadata in (attribution for example) when it gets displayed. The caption shortcode is not a solution since it doesn’t pull data when the page is rendered, it offers to pull data and make it static when the image is inserted into the post.

    What I’m getting at is maybe the start to this is forking shortcodes into something new. Something like an advanced object which is always inserted via an MCE UI button, always displayed as preview or editable object in TinyMCE. Something with a full WordPress API to support it akin to custom post types.

    I’m fine keeping the visual editor, non-WYSIWYG because what you get will always depend on what page your on (front, archive, single, single-post-format), but at least giving all shortcodes a preview like gallery, or hopefully much better, would be a start.

    1. One thing I’ve gotten used to explaining to clients is that the wp editor is a visual editor NOT a WYSIWYG editor. This is a bigger issue for many than just shortcodes and editor-style.css doesn’t fix the fact the H3 may be totally different on one page than another. /OT

      I think this depends on how far you take your implementation. Though I don’t necessarily disagree with you, I do think that at first glance, it looks like a WYSIWYG editor and and if you opt to take this a step further by implementing editor-style.css, it comes even closer.

      It’s only when you begin to address advanced elements – ala galleries – that it loses that identity.

      What I’m getting at is maybe the start to this is forking shortcodes into something new. Something like an advanced object which is always inserted via an MCE UI button, always displayed as preview or editable object in TinyMCE.

      These are the types of ideas I love to hear. As I mentioned in the post, I don’t really have a proper solution for this, though I do try to offer something because I hate simply pointing out a flaw and not doing anything about it, but I know that we all have some ideas as to how we could fix them.

      Thanks for sharing this!

  12. I agree with the direction of this post and hopefully this will evolve in future updates. I do think the use of shortcodes work using do-shortcode

    I worked on some sites for galleries and museums and I can say that even the “insert gallery” action was complicated for a lot of my users. All the steps associated with saving the images correctly, uploading the files and adding the titles and viewing order was complicated enough.

    So what I did was use a plugin called Portfolio Slideshow and used do_shortcode to implement the gallery directly in the template without the user having to do anything. So all they had to do is upload the images to the post, add captions and nothing more. It also limited user access to placement of the gallery on the page so I could control the design better.

    Matt is right on in terms of users ability to understand an work with a CMS. It needs to be very simple.

    1. I think that your approach is right (along with some of the other commenters) in that it’ll be an iterative a approach.

      I’m a strong believer and firm advocate for implementing smaller changes over time rather than big bang releases, because I think that it helps both the developer and the user work to discover what’s working, what isn’t and the like.

      I’d never call for a major haul of the TinyMCE implementation, but maybe a few small changes or even experimental things introduced to improve the shortcode functionality into something a bit more user-friendly.

      And, at the end of the day, that should be our ultimate goal: Regardless of how much work it takes, it’s got to be easy for the user.

  13. I remember how excited I was when I first found the Front-end Editor plugin (http://wordpress.org/extend/plugins/front-end-editor/ — there may be better alternatives to this by now). However, I quickly became frustrated the limitations of this tool. I would love to see WordPress move into being a platform where all editing (headlines, widgets, post content, menus, images etc) can be done from a relatively simple front-end GUI (the only limitations of which would be the skill of the developer and the paranoia of the site administrator). The change -> preview/draft -> change again -> preview/draft (or just publish quickly and change back) is quite a drain on users and myself when dealing with content. There is a place for “zen mode” but there is also value in users grappling directly with content as it will actually be displayed.

    1. The change -> preview/draft -> change again -> preview/draft (or just publish quickly and change back) is quite a drain on users and myself when dealing with content.

      Exactly this. I think it’s a pain felt by anyone who drafts even an moderately extensive level of content.

      Couple this with someone who is less technically savvy and there’s quite a challenge.

      This is one of those things that has no clear solution, but even iterative improvements would be welcome.

      And just to drive the point home, I’m not certainly not saying that someone else should be implementing this. WordPress is open-source so any developer who works on it has the potential to work on this (myself and the rest of us included).

      So the next time the opportunity presents itself, I’m certainly going to begin thinking about what options I have for improving the experience.

  14. One issue I’ve been trying to figure out recently is how to make internal links independent of site location. Images, for example, are placed using absolute links. The best thing I’ve come up with here is a shortcode. Example:

    [img style=”styling” class=”myclass” slug=”image-one.png”]

    The shortcode places everything in, but divorces the site URL from the image name, and doesn’t have to be changed when moving a site. And for this case, there isn’t anything better, because the code is replacing code. In the code view of the editor, it would show this instead of <img… , so we aren't making it worse. The only issue I can see is that the visual editor won't render it as an image.

    My question is, can you think of a better way to do this without using a shortcode?

    1. To be honest, I think you may be working a little harder than you need to =p

      When I move WordPress, I use a search and replace script that finds all instances of a url and replaces it with the new one. It’s super handy and works great with single installs, though it can get a little hairy with multisite. Depending on what you try to replace ( http://site.com vs //site.com ), you can target things pretty well and get what you want. To date, save for multisite, there hasn’t been a string I haven’t been able to replace.

      Now, quick commentary. Yes, it stinks that WP uses absolute URL’s in the database for its images. But sadly we have to deal with it.

      The search and replace script is step 2 here: http://codex.wordpress.org/Moving_WordPress#When_Your_Domain_Name_or_URLs_Change

      1. I ended up using a search/replace. However, that method is akin to slapping a bandage on instead of fixing the actual cut. Links shouldn’t be absolute in the first place. WordPress almost acknowledges this in their menu functionality, because that doesn’t use absolute linking. But for extra links, and for images, we are still forced to use absolute links.

        A compromise I can think of that wouldn’t use shortcodes would be a search/replace function was more of an automatic that was monitoring the site location. When that changes, the plugin would go through and update all strings with the original and the new.

          1. Nothing that would be constantly changing. But every site I develop I’ve got to move once, from a development to production location. If WordPress had a built in search/replace function that hooked into the action of changing site location, it would be one less step that I’d have to do for moving the site.

              1. That does seem to do most of it. I’d still argue that the way it’s taking care of it still goes back to the fixing symptoms vs fixing the problem, but as you said, we play the cards we are dealt. I appreciate the link.

                1. Thank you for an insightful article on why and how to go beyond shortcodes.

                  I followed the discussion here with interest, especially as I’m working on a sort of “shortcode to rule them all”.. Shamefully, two in fact, which can perform query loops and display any content from posts, pages, custom post types, custom fields, images, attachments, menus, and sidebar/widget areas.

                  This makes it possible to write and preview site/page/section layouts in the browser just like any other post, without the need for additional PHP page templates. So, to me shortcodes are like simple and flexible macros to display any content anywhere.

                  That said, end users shouldn’t have to see such code, much less learn to “program” with it. I put everything with HTML and shortcodes into a separate post type. For the client, I create a different admin menu with custom post types and fields only for the content that needs to be edited.

                  There is a need for a simple drag-and-drop GUI approach to editing layout and content. An interesting idea is front-end visual editing in the website itself, with no separate admin backend.

                  By the way, Andy, the problem you mentioned about “how to make internal links independent of site location” – I also solve it using a shortcode, as simple as putting [siteurl] in the link address.

            1. What Tom said :)

              You also might want to look into Capistrano. It’s a commandline deployment tool that you can script to do a whole bunch of stuff. I’ve got mine set up to run a search and replace. Might be a good place to look.

              https://github.com/nathanielks/Wordpress-Capistrano-Deploy

              Also check out Mark Jaquith’s WP Stack. His is more refined than mine is, I believe, but I don’t think he has the DB S&R.

              https://github.com/markjaquith/WP-Stack

  15. Thank you for posting this article. I was searching on Google for more info about how others feel on this topic, and I come up with mostly praises. I too am frustrated with shortcode usage in WordPress, and agree that it undermines one of the most basic and fundamental concepts of using a content management system.

    What frustrates me more is how they are showing up in WP themes. Sometimes I’ll recommend to someone that they purchase a WP theme for their website when they don’t have the budget to get a completely custom site created. I’m always disappointed on how a theme that looks so professional on the front end can be littered with hard to navigate shortcode on the backend. I’m in the business of using content management systems as a way to safely and confidently turn over a website to a client for their own content updating. Shortcodes make that impossible.

    I do hope to see some “back to basics” movements occurring where we can once again have access to cleanly coded websites.

    1. See, the only issue I have with that is it comes down to the skill of the developers, not the shortcodes. Did they write their code in such a way that required crazy nesting and a bajillion other things? Or did they write it where it could be used simply?

      Not a limitation of shortcodes. It’s a limitation of the developer.

  16. After reading your article and all the comments I must say the our feeling about shortcodes are the same.

    Unlike like you we do include shortocodes in our plugin and in many times we know that for the average user will hard time using them but we can’t really accomplish this functionality in any other way.

    Shortcodes are cluttering the content and if you are really want to accomplish a complex website design you content will look almost like the page source code.

    From out point of view self-closing shortcodes (like the gallery shortcode) in most cases don’t have this problem and they are just simple functions that are being replaced

    The real problem is the enclosing shortcodes and as much as we tried we couldn’t find a way to do the same things with using them.

    1. From out point of view self-closing shortcodes (like the gallery shortcode) in most cases don’t have this problem and they are just simple functions that are being replaced

      I think this is a fair point. Self-closing shortcodes *are* easier to read, but I think this also is up to the parameters that the developer asks the user to enter.

      For example, if you have to provide the ID of some unique aspect of the element, then you’re increasing the complexity for the user; however, if you’re doing some type of element with height and width, then that’s a bit easier for a user to understand – at least, I’d think for some users :).

  17. I think shortcodes have their place – as “placeholders”. If you want to pop a gallery in, there should be a visual, WYSIWYG gallery option to modify. Almost like template parts.

    Theme Developers goodlayers have created a visual builder that inputs in a ‘column’ that you can increase the size and determine what is displayed. It works pretty well and is a good start. The problem I think though is that most web designers believe in simplicity and clean, and when we give the controls to the end user, they start wanting to do crazy things.

    1. I think shortcodes have their place – as “placeholders”. If you want to pop a gallery in, there should be a visual, WYSIWYG gallery option to modify. Almost like template parts.

      Yes – I agree. If the shortcodes are simple like `[this]`, then I think it’s okay as there’s very little to learn, but as soon as you introduce attributes, or code that can fit in between shortcodes, then you’ve ended up introducing a crazy markup language for ’em to learn :).

      1. Great! I completely agree with you then. The number of attributes should be limited to close to zero. Another plugin – revolutionary slider – lets you name the shortcode yourself, which is kind of cool and at the very least, lets the user learn a bit about what they are doing.

  18. I believe the case should be against post editor rather than shortcodes which gives the solution of all the editor limitation.

    One important feature is missing on the editor is handling shortcodes (like showing list of available shortcodes).

    even i think shortcode is not hard thing for normal user to use, the code of shortcode can be generated on the editor after taking some inputs from the user.

    I wish there will be well written shortcodes for the most common tasks and these shortcodes will be buildin in wordpress or a plugin

    Alot of non programmers will be so happy.

    1. One important feature is missing on the editor is handling shortcodes (like showing list of available shortcodes).

      True, but you could also implement a custom dropdown in the TinyMCE editor that’d support exactly this. Of course, this is coming from me who’s clearly against shortcodes – at least for the most part ;).

      even i think shortcode is not hard thing for normal user to use, the code of shortcode can be generated on the editor after taking some inputs from the user.

      I think basic shortcodes are easy for power users to use; however, they create a disparate experience between what the user is writing, and what the viewers will be reading. That’s a bummer.

      Secondly, as soon as you start introducing attributes and/or content that fits between the shortcodes, then you’re making it much more complex for the user.

      Alot of non programmers will be so happy.

      Depending on the task, I think you and I disagree. I don’t think technically minded people get the idea of tags, attributes, and child nodes which is essentially what shortcodes come out to be.

      They are a form of markup, thus they look like code, and that scares people.

  19. I completely agree. WordPress needs some kind of a visual grid builder (instead of one WYSIWYG field) where you can attach widgets/plugins/whatever_you_name_them to. Just like squarespace.

    Is there any news on this?

    1. I’m not a huge fan of the idea of a visual grid builder on the backend or part of WordPress core, but I am a fan of third party solutions such as Velocity Page as I think it strikes the perfect balance between what’s needed in terms of page design, and does so without adding much to core.

      1. Wow, VelocityPage looks quite nice. I’m only missing the option to add plugins to the grid (like for example with squarespace where you can add forms, slideshows, Google Maps, directory to the grid).

        It looks like currently you can only add text-related things.

  20. Hey, Tom! I’m really with you in this case… I never liked shortcodes. It does feel like a hack. I aways wanted a better way to edit multiple kinds of content, in a way that we could have a better view of what we’re building. In fact, this is the reason that I recently started to participate in some core projects.

    There’s a project been developed as a “feature as a plugin”, called Content Blocks, a.k.a CEUX, that I think is trying to solve the problems that sometimes are “solved” by shortcodes. It breaks the idea of editing the content inside a single tinyMCE instance, giving more freedom to build interactive blocks of content. You really should check it! The development is currently happening on GitHub: https://github.com/melchoyce/CEUX.

    Unfortunatelly, this project hasn’t gotten much attention from developers to help build it, and I’m one of the few working on it, but I do believe that it could bring a whole new kind of workflow that could reduce the need of a shortcode and at the same time, remove the gap between what the user sees / gets. For example, the gallery thing: right now, the editor places this placeholder you showed on this post when you insert a gallery. In the CEUX project, a gallery is a Content Block, and has it’s own logic. You can insert / remove images, sort them, and you see instantly how your gallery should look like in your content.

    Of course, the main goal is edit the content, and leave the presentation for themes, but the hability to see and interact with something closer to the real content, it’s really a great improvement.

    1. Diego – this is pretty sweet. Thanks for bringing it to my attention.

      If I have the need and/or opportunity to use this in an upcoming project, I’ll check it out and write up a post on it :).

  21. I’ve been meeting with and contemplating this issue for quite a while now, like most serious developers who also care for thier own as well as thier clients ease and sanity of workflow : )

    A couple of things I’m aware of which are heading in this direction and bridging the tehcnical gap are:

    1. A wordpress specific plugin called Visual Composer
    2. A non-wordpress CMS/framework called Concrete5 who (last time I looked a couple of years back) specialise in front end in-context editing

    Developing something between these two for WordPress would certianly be game changing, to say the least!

    Thought provoking article, many thanks

    ~ Sean

    1. After doing a few client sites I came to the same conclusion regarding shortcodes.
      The alternatives for now I see require up-front work from a developer but make the non-developer’s user experience much better.

      1. Advanced Custom Fields plugin – if someone designed a page and you want to make it pixel perfect but still be editable by the user this is a must. The developer can create a page template and use Advanced Custom Fields to create fields that the user can edit using the WordPress Editor. For me as a developer this makes the most sense, but the drawback is, as my wife points out, you can’t see your content in context of the page. You only see a list of fields to edit.
      2. WPBakery Visual Composer plugin – I just started looking into this. I’m still not sure how well it can integrate with different themes, but if the developer has a way to hook into the drag and drop pieces and define what html/css should be outputted then that seems like that would be perfect. The user doesn’t have to worry about shortcodes yet they still see a WYSIWYG view for the most part.

      1. Yeah – it’s a tough spot, for sure, especially for people who have historically used themes that include a lot of shortcodes because content simply isn’t portable. It should be in a plugin, but I digress on that.

        As far as ACF is concerned, it’s a powerful plugin for end-users. From a developer’s standpoint, I’d say it’s pretty good, but it lacks some things that I wish it supported in an API.

        As far as Visual Composer is concerned, I’ve never really used it so I don’t have much to add to the conversation :).

  22. Hey Tom, I just stumbled across this post when researching for my new plugin and you’ve absolutely hit the nail on the head.
    The main problem is mostly to do with the limitations of the TinyMCE editor (and I still think they do an excellent job), which means as developers we just can’t do a lot of things in the editor.
    So I guess you’re excited by the upgrade of the TinyMCE editor in WP 3.9 then?
    Well I’ve just created a plugin (in its early versions) to basically tackle most of what you are saying in this article (in regards to creating buttons only) and it works with the new features of TinyMCE in WP 3.9.
    Its basically a button creator/editor which you can use in your posts and pages without using shortcodes at all!
    https://wordpress.org/plugins/forget-about-shortcode-buttons/
    Would love to hear your feedback on it – I have some more interesting ideas leveraging the new TinyMCE and getting rid of shortcodes for some simple visual elements…

    PS I just started using your plugin boilerplate on a new plugin so thanks for that ;)

    1. Glad to hear you stumbled across this and found it a good read, Ross!

      Overall, I agree with you that I’m a fan of the TinyMCE editor. I think it’s a solid piece of software. As far as shortcodes are concerned, I’m definitely a fan of some of the implementations that I’ve seen with adding buttons to the editor; however, I fear that in introducing them in the editor could potentially pass the buck, so to speak, and overload the toolbars with options.

      That said, your implementation is neat because it doesn’t deal with those buttons, it’s WYSIWYG, and users get to edit the options from within the editor, and they can see exactly how it’s going to look when it’s published.

      Nice work :).

      1. Thanks for the kind words :) Yeah although TinyMCE is a great piece of software its pretty difficult to work with unfortunately, but I think we get a little bit more flexibility with 4.0 which might be just enough for a new breed of plugins that don’t rely on shortcodes so much – I guess we’ll see!

  23. Hi Tom,

    I’ve came across to your blog for just a few weeks until now. Thanks for many many nice tips and tricks about WordPress developement. (Yeah, one of your posts introduces CodeKit to me and makes me buy it yesterday lol)

    Concerning reusability, if we ignore shortcode way, do you have any recommendation how to manage/design custom templates and make it resuable?

    For example, I’m having two custom templates (separate php files)
    1. home template
    2. portfolio template

    Both templates have a section that show portfolio grid. Therefore, we should create a portfolio grid component which can be reused and displayed on those two templates.

    I know get_template_part and locate_template (I seem to mix them also ;( )
    I’m curious to know how to properly writing reusable and maintainable component for reusing in any templates?

    Not sure if you have written about this.
    I’m new here ;)

    Thanks

    1. Concerning reusability, if we ignore shortcode way, do you have any recommendation how to manage/design custom templates and make it resuable?

      This really depends on the nature of the project. If it’s a project for a client, then it’s something that can be done relatively easily if you opt to use custom templates, custom post types with meta boxes, and things like that (though it is more work).

      As far as products for mass consumption – like a theme – I don’t really have a specific solution for this other than to consider moving the functionality into a portable plugin. Even then, you’re asking users to write code of some sort which is my biggest issue with them.

      Sometimes it can’t be avoided, and I get that, but I do what I can not to use short codes in the work I share.

      I’m curious to know how to properly writing reusable and maintainable component for reusing in any templates?

      Here are three quick links for you:

      1. https://tommcfarlin.com/template-in-a-wordpress-plugin/
      2. https://tommcfarlin.com/include-require-and-get_template_part-in-wordpress/
      3. https://tommcfarlin.com/separation-of-concerns-with-wordpress-templates/

      Hope this helps!

  24. Hi Tom,
    As regular user like me w/o IT background, I sick to see a lot of Elite author in themeforest promote “short code” at their page. Shortcode nowadays just like back to Visual Basic century. It’s a markup job for website developer. Shortcode means the shortcut way for developer to NOT develop user-friendly page in WP dashboard for customer who’s spend money for their theme.

    If WP management take off the “Shortcode” option from WP dashboard, I think, only few Elite website developer success in selling theme in themeforest.

    I’m still looking website author that selling their premium theme with our using short code (or less). Any suggest?

    1. I’m still looking website author that selling their premium theme with our using short code (or less). Any suggest?

      Unfortunately, no I’ve no recommendations. I mean, I sell a a single theme and it uses no shortcodes, but it’s also extraordinarily small on features compared to what most people are used to getting themes from places like other marketplaces.

  25. Hi Guys,

    Tom – Thanks for your recommendations. I’ll read those of your posts. ;)

    Rom – Actually, I’m a new theme author on ThemeForest. I’m worried that Tom will ban me for sure if I’m advertising on his blog ;P. ( Anyways, my name above is the thing you may need to see.)

    Do you guys have tried something like Visual Composer or other page builders which turns shortcodes to UI (Drag&drop) in a friendly way?

    How is it good or bad for non-technical users like you, Rom ?
    Just like to know your opinions as a real user.

    I’ve mainly developed my themes mainly with advanced “metaboxes” and “Theme options” so users don’t have to touch any shortcodes. But, it seems like users start to like Visual Composer or Page builder. How do you think?

    Thanks

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.