Before we dive too far into the technical aspects of creating shortcodes in plugins, I want to take a moment to discuss some of the good ways that shortcodes can be used, and some of the scenarios where shortcodes should probably be avoided.

Shortcodes can be a great tool to help users take advantage of powerful features available in your plugin, but they can also be extremely burdensome.

One of the problem with shortcodes is the similarity they share with HTML, PHP, and other “codes”. To non technical users, advanced shortcodes with a lot of parameters can be overwhelming. Take the following shortcode for an example (a real shortcode from Easy Digital Downloads):

[downloads orderby="title" price="no" full_content="yes" columns="3" number="9"]

While it may not look intimidating to developers or advanced users that are accustomed to using a lot of shortcodes, it absolutely is intimidating to many users.

How about this example:

[column size="2"][[blockquote]]This is a quote from someone[[/blockquote]][/column]

When shortcodes are nested, things gain an even greater likeness to code, and that gets scary for many users.

These two examples are not even remotely close to how complex shortcodes can get. For a terrifyingly difficult example, take a look here.

While there are always exceptions, I think we, as developers, should strive to make shortcodes as simple and easy to use as possible. There is no definite line that determines when a shortcode has become too complex, so we have to make our own judgements, but I believe there are some general guidelines that we can take into consideration when constructing our shortcodes.

If possible, limit shortcodes to one or two parameters. Of course there will be cases when three, four, or five parameters are needed, but in general, shortcodes should probably only contain one or two parameters in the vast majority of cases.  I don’t mean that your shortcodes shouldn’t include five, six, or even ten optional parameters, but for the majority of users, one or two parameters should suffice. Zero is even better.

Some examples of use cases that shortcodes are good for include:

  • Image galleries
  • Buttons
  • Embedded media (music, images, videos, maps, etc)
  • Related content
  • Forms
  • Forums

Use cases that really don’t work well with shortcodes:

  • Advanced formatting and layout controls, such as multi-column layouts
  • Advanced post queries (such as ones that attempt to replicate WP_Query parameters)
  • Any shortcode that requires a large number of parameters

I highly suspect that many people will disagree with my statement that shortcodes should never contain more than two or three parameters, and that’s okay. Each plugin developer has to decide for themselves what they believe is best.

One of my goals for this tutorial series is to help teach you how to write simple shortcodes that are still exceptionally powerful. For example, instead of providing ten different parameters that can be used to control every aspect of the rendered markup, how about making the shortcode’s markup available in a template file that can be copied to a theme and then modified to the user’s content? Most users do not need to utilize every parameter a shortcode offers, at least not when it’s well written, so some options should be catered just to the more advanced users. Template files are perfect for that, and we will dig into using template files for shortcodes later on.

Have you seen overly complex shortcodes? Feel free to share your own examples so we can all learn how to make better shortcodes together.

  1. Ryan Olson

    Great timing on this post, as I am trying to build a plugin and working on how to get the content to the front-end. I was planning on creating a shortcode that would output a search form and that form takes an address then will search custom post types of locations to find some within a radius. So is a shortcode output the wrong way to go about that?

    • Pippin

      That’s a great use case for a short code, but I would definitely suggest placing the form in a template file so the HTML markup of the template can be more easily modified. We will be getting into that soon in the series. For now, take a look at this tutorial:

  2. Ryan Olson

    Awesome thanks, really look forward to getting into that! What about adding buttons to the editor, or media buttons above editor, to make it easier for users so they don’t have to remember or copy/paste shortcodes? Do you happen to have a tut on that?