In my earlier post about template parameters in MediaWiki, I lamented that WordPress doesn’t have a similar mechanism. Actually it sort of does: it has shortcodes.
Shortcodes pretty much do what a MediaWiki template does, in that they allow you to easily add content to a post or page. You can even pass variables, which WordPress calls attributes and MediaWiki calls parameters.
The key difference is development: MediaWiki templates can be created on the front end by anyone with editing privileges, whereas WordPress shortcodes can only be created on the backend, where they are typically included in a child theme or plugin. (WordPress no longer allows shortcodes in themes, so even though I have been using these in my child themes, I will probably soon move my shortcodes to my own plugin.)
Background
I recently updated my bookblog and opened it up to some of my friends who also like to read and review books. The problem is that I insist on properly citing the books I’m reviewing, along with any secondary sources. When it was just me, I would simply edit the html of the page to get a structure something like this:
<div class="src">
Works Cited
<p class="srcp">Smith, John. <i>A History of Balloons</i>. New York: Penguin, 1988. Print.</p>
<p class="srcb">This is a note about the above book.</p>
</div>
I could have taught my contributors how to do this, but they would have needed to know a little about html and a bit about the text editor in WordPress (which is very different to a desktop text editor). I would rather they spend their time and energy on content, so this is exactly the case in which shortcodes makes perfect sense, because we can allow the shortcodes to handle the html, and the child theme or plugin to handle the shortcode.
Overview
Creating a shortcode requires two basic steps. First, we define a handler function that accepts attributes and returns outputs. Second, we use the WordPress `add_shortcode()` function to register our handler function, which makes it available.
The Shortcode Handler Function
Shortcodes work by returning data to the browser, so the heart of a shortcode handler is simple:
function myshortcode_handler() {
return 'This is a note.';
}
We’ll call this shortcode “addnote”, so whenever we type `[addnote]` in a post or page, WordPress will replace it with “This is a note.”
Shortcodes can handle extensive blocks of html, so we could also use:
function myshortcode_handler() {
return '<p class="srcp">This is a note, along with an image.<p><img src="http://example.com/puppies.png" alt="Puppies" style="float: left;" />;
}
Registering a Shortcode
Once we’ve created that shortcode handler, we need to register it using the WordPress `add_shortcode()` function. This function accepts two arguments: the name of the shortcode (that is, what users will type between the square brackets), and the name of the shortcode handler function:
add_shortcode('addnote' , 'myshortcode_handler');
Enclosing vs Self-Enclosing Shortcodes
The previous shortcode example is a self-enclosing shortcode. That is, the only data it can return to the browser is contained within the shortcode function.
You may have times, however, when you want to add content to a shortcode. For example, you may want to use a shortcode to add a yellow background to text to simulate highlighting. In that case we need to use an enclosing shortcode.
An enclosing shortcode has opening and closing shortcodes, like this:
`[myshortcode]This is the content.[/myshortcode]`
To create an enclosing shortcode, we need to send a parameter that contains the content to the handler function. That content is contained in the `$content` variable, which we initially set to a value of `null`:
function highlightshortcode_handler( $atts, $content=null ){
return '<span style="background: yellow;">' . $content . '</span>';
}
So if we use this in our post or page:
`[highlight]This is our highlighted content.[/highlight]`
WordPress will return this html to the browser:
<span style="background: yellow;">This is the highlighted content.</span>
Yep, the possibilities are endless. But wait, there’s more!
Attributes
You may have noticed in the last example that we actually set two parameters to our shortcode handler function: `$content` and `$atts`.
`$atts` is shorthand for attributes, and is an array in which we can define variables that users can give to the shortcode for inclusion in its returned output. For example, in the above example, we could create an attribute to allow users to select which background color they would like to highlight their text with.
function highlightshortcode_handler( $atts, $content=null ){
extract(shortcode_atts(
array(
'hex' => 'FFFF00'
), $atts )
);
return '<span style="background: #' . $hex . ';">' . $content . '</span>';
}
If we type this in WordPress:
`[highlight hex=”3FCDBA”]This is our highlighted content.[/highlight]`
We would then get highlighted content with a blue background, rather than a yellow one.
A few things you should note about this shortcode:
- We initially set the value of `hex` to FFFF00, so that if a user doesn’t enter an attribute code, their text will still be highlighted yellow. (This is good practice to follow if you are updating older shortcodes.)
- The `#` in front of the hex code is part of the `return` statement, saving users a keystroke. Also, it’s one less thing for them to forget to enter.
- There is no filter to make sure that they are entering valid hexadecimal values, so it’s possible for users to enter useless code. You could use an `if` function in the shortcode handler to run the attribute against a regex of some sort, so that if it’s not a valid hex value, it defaults to the yellow color.
Where to Put It
If you are wondering where to put this code, it depends on what you are working with:
- In a child theme, put it in the child theme’s functions.php file.
- In a plugin, put it in the plugin’s main file, or another file which then gets called with `require_once()`.
Conclusion
Shortcodes are a great way to easily add repeated content to your WordPress blog. For more information, check out:
- Shortcode API — from the WordPress Codex.
- WordPress Shortcodes Generator — from GenerateWP
Looking at the samples here can be especially informative.
https://techblog.kjodle.net/2015/02/01/create-wordpress-shortcodes/
