Shortcodes are WordPress‘ way of inserting content within a given post, page or custom post type. This content is often of a more dynamic nature. Take for instance, the gallery shortcode built into WP. Just pop
into any WordPress post and out pops a nice gallery of all images attached to that post. Awesome!
In this tutorial, we’ll cover the basics of creating your own shortcodes.
1. Adding Shortcodes
The first step is actually add the shortcode – that is, let WordPress know about it. We do this with a function called, conveniently,
add_shortcode. It takes two arguments: the shortcode name, or the stuff your surround with brackets in the post to make it work and (2) the call back function.
I like to wrap the call to
add_shortcode inside a function hooked into
init. Why? Because WordPress loads in phases. Registering a shortcode on
init ensures the entire WordPress enviroment is loaded (including the
add_shortcode) function before doing anything.
What happens when WordPress encounters a shortcode in post content is it looks for it in its array of registered shortcodes. If it finds it, it calls the callback function (registered with
add_shortcode), which returns a value. WP then replaces the shortcode with that returned value.
2. The Callback Function
The callback function is where the work happens. Our shortcode will insert a link to another post based on an
Shortcode callbacks receive two arguments: attributes of the shortcode and the content.
[shortcode-name these="are" attributes="yes"] this is content[/shortcode-name]. Content doens’t have to be used, so it’s best to give that function argument a default value. With that in mind, here’s the skeleton of our callback.
The attributes passed into a shortcode can be dangerous. And you also probably don’t want to have to call
isset all the time to make sure certain attributes were included. Enter,
shortcode_atts. It takes two arguments, the first is an array of allowed attribute array keys, and their default values. The second should be the array of atts passed into the shortcode callback function.
shortcode_atts will check to see if the passed in attributes has a given key. If it does, that key’s value will be sent in the returned array. If the attributes array doesn’t a have a key, the default value will get returned.
Our call to
shortcode_atts is wrapped in
extract, a built in PHP function.
Next up, we’ll check to see if we have our
id attribute and get the post associated with it. Make sure the post is published, and then build our link.
The only thing of note in the remainder of that function is the check to see if the
$content variable actually contained a value. This is common: content is not required of a shortcode, so if you’re planning on using it, have a default or something else you can use.
When Not to Use Shortcodes
Shortcodes are awesome. But they are not the solution for everything. For instance, you could use shortcodes to replace something like
<div class="alert">Some message<div> with
[error]some message[/error]. That shortcode looks suspiciously like HTML. If that’s the case, why not just learn HTML?
Shortcodes can also cause a lock in effect. Deactivate the plugin that adds them or change away from the theme that adds theme, and you now have ugly shortcodes in your content. Awesome. There’s not much that can be done about that, but it’s something to be aware of.