Shortcodes are great tools for creating complex content in the WordPress post editor without having to resort to tags or other complex mechanisms. Since you control the exact output when using a shortcode, you can easily blend shortcodes into any project or create hooks to let others do the same.
In this article, we’ll look at how the Shortcode API works by creating some handy shortcodes ourselves to help save time when writing posts.
The Basics of Shortcodes
The basic building block is the
add_shortcode() function through which you define a keyword and a function which will handle the shortcode output. The first parameter will be parsed for in the editor and any matches will be converted to the output specified by the function defined in the second parameter.
When adding shortcodes you really should use a plugin, but if you want to see all this in action quickly feel free to use your theme’s functions.php file temporarily. If you’re new to plugins take a look at our comprehensive guide to creating plugins.
To use this shortcode, simply type
[hello] anywhere in the editor and it will be expanded according to the output in the function. Always remember to return the required output, don’t echo it!
Parameters allow users to modify the behavior of their content easily. The WordPress Gallery Shortcode is a great example. It has a number of parameters that you can use to control the column count, order, images in the gallery, and so on.
On the front-end users can add any parameters they like, it’s up to us developers to determine a fixed set we’ll be looking for.
Let’s look at an example:
This shortcode will display a small color swatch with the color given as a parameter. Note that users could add any other parameters they like, but we chose to only “listen for” a specific one.
In an ideal scenario we would use a CSS file and do some checks to make sure the color is a HEX value, but this is fine for getting the point across.
shortcode_atts() function is used for merging default and given parameter values and should be used any time there are parameters since it makes our attributes hook-accessible.
So far we’ve only looked at shortcodes without content, but it is possible to create ones that are wrapped in a shortcode tags.
Here’s an example of a notice shortcode you can use to create Bootstrap/Foundation style alerts:
The content of the shortcode needs to be wrapped in a start and end tag. Our shortcode function will receive this content as its second parameter.
Note that you may want to perform some checks on the content to make sure users don’t output any unclosed tags or anything else harmful. You may also want to run the shortcode content through
do_shortcode() to make sure any shortcodes within shortcodes are also expanded properly.
Using Shortcodes in Template Files
The previously mentioned
do_shortcode() function can be used to display shortcodes when working in template files. To display a permanent gallery built with WordPress’ own gallery shortcode you could do the following:
Remember to add the full shortcode (square brackets and all) in addition to echoing it. This format will display the same result as if you had added it in the editor.
If you’ve created or used a particularly useful shortcode, let us know in the comments below and share a link so we can check it out!