WordPress Shortcodes

Shortcodes are commonplace in WordPress themes, plugins and even WordPress core. Whether you are a new developer looking to implement a shortcode for the first time, or are a seasoned pro; come join us as we delve into the pros, cons, gotchas, best practices and creative approaches to shortcodes.

What are they?

A shortcode is basically a placeholder for dynamic content. Shortcodes support attributes and content, which can be used to exercise more control over the dynamically generated content.

WordPress has several built-in shortcodes:

  • – Allows you to embed various types of content into your posts and pages. There are a limited number of supported embeds that can be used with this shortcode.
  • [caption] – Allows you to wrap captions around content. Typically, this is used with individual images.
  • [gallery] – Allows you to add one or more image galleries to your posts and pages.
  • [audio] – Allows you to embed an audio file and play it back.
  • [video] – Allows you to embed a video file and play it back.

If you have a WordPress.com website, you can access additional shortcodes.

If you have your own WordPress.org website install, you can gain access to these same shortcodes by installing Jetpack.

When are they appropriate?

Ideally, you wouldn’t use shortcodes to just wrap content with certain HTML markup. If you want to allow users to wrap their content with markup, look into the QuickTags API.

Consider it when you need to allow the user to load dynamic content, such as:

  • Inserting AdWords conversion tracking code on a page
  • Insert a Google Map
  • Insert a Google Document
  • Insert a widget

Where can they be used?

By default, shortcodes are only supported in the body content of posts, pages and custom post types.

You can enable them in excerpts, like this:

add_filter( 'the_excerpt', 'do_shortcode');

You can enable them in text widgets, like this:

add_filter('widget_text', 'do_shortcode');

You can enable them in comments, like this:

add_filter( 'comment_text', 'do_shortcode' );

If you wanted to use a shortcode inside a theme template, you could do this:

<?php echo do_shortcode('[my_shortcode]'); ?>

The problem with this, is that when the plugin is disabled, then [my_shortcode] will actually be displayed on the site.

Many plugins will guide users to utilize the actual shortcode callback as a template tag, like this:

my_shortcode_callback( $atts, $content );

This is a dangerous approach since disabling the plugin will mean that the function is no longer defined, resulting in a fatal error and crashing the site.

Most plugin authors instruct their users to add a conditional check to see if the function exists, like this:

This is indeed a viable and safe method, but typically more prone to errors for your average theme editor who may not be familiar with PHP.

However, I think we can do a bit better:

do_action( 'my_shortcode', $atts, $content );

To utilize this approach, a developer only needs to add the following code:

If you want to enable shortcodes for custom content, you can use the do_shortcode() function. Here is an example:

How do you create them?

Here is a basic example of how to implement a shortcode:

Here is an example of how a shortcode can be implemented within a class:

Why doesn’t it work?

A few things to note when working with shortcodes:

  1. Return, don’t echo, in your shortcode callbacks.
  2. They aren’t recursive, unless you make them… and even if you do, you can’t nest shortcodes with the same name.
  3. Mixing closed and unclosed shortcodes with the same name is dangerous. If the user uses an unclosed shortcode followed by a closed shortcode, only the second will work.
  4. Only use lowercase names for your shortcode attributes.
  5. Square brackets cannot be used within shortcode attributes.
  6. Two shortcodes registered with the same name cannot co-exist. The one registered last will override the previous.

Best Practices

  • Prefix shortcodes
  • Sanitize input, escape output.
  • Avoid side effects.
  • The shortcode callback should process the attributes and hand off to a separate function. The separate function can then be used to create a stand-alone widget, or used elsewhere in the code.

Escaping Shortcodes

If you ever need to display a shortcode on the front end of the site, but don’t want it to be processed, you can escape it. This is particularly handy when you are writing a blog post about one or more shortcodes, such as this post. All you have to do is add an additional opening and closing bracket, like this: [[shortcode]]. On the front end of the site, it will be rendered like this: [shortcode].

Shortcode API Functions

  • add_shortcode() – Registers a new shortcode.
  • do_shortcode() – Searches content for shortcodes and executes them.
  • remove_shortcode() – Disables a shortcode. Note: This will cause the shortcode text to display in the content.
  • – Disables all shortcodes. Note: This will cause the text for all shortcodes to display in the content.
  • shortcode_atts() – Combines user shortcode attributes with predefined default attributes. The result will contain every key from the default attributes, merged with values from shortcode attributes. Any user defined attributes that aren’t in the predefined default list will be discarded.
  • has_shortcode() – Checks whether the content passed contains a specific short code. The short code needs to be registered with add_shortcode() to be recognized.
  • strip_shortcodes() – Deletes all registered shortcode tags from the given content.
  • shortcode_exists() – Checks whether a specific shortcode has been registered.

Resources

 

Presented at WordCamp Nashville 2016