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.