In the spirit of the topic, I’ll keep this post short and sweet. Today I’ll be discussing WordPress’s shortcode API and how to utilise it.
WordPress shortcodes are codes (eg: [list_bookmarks]) which can be typed into the content area of a page or post in order to provide functionality of some kind. Shortcodes can be wrapped around text (similarly to how HTML tags are wrapped around text) or can be used as a single tag. In this post, I will discuss using shortcodes as a single tag to save time as well as providing more control to the user of your WordPress theme/plugin/function.
A shortcode consists, in it’s most basic form, of two elements: a PHP function and a line to add the shortcode into the system. A basic structure would like like this:
function list_bookmarks() {
INSERT CODE HERE
}
add_shortcode('list_bookmarks', 'list_bookmarks');
The call to the shortcode would look like this:
[list_bookmarks]
To provide a bit of clarity to the above, the add_shortcode function has two attributes: the first being the code you want to be the shortcode and the second being the name of the function called when the shortcode is typed.
Another really useful aspect of WordPress shortcodes is the $atts attribute passed to the function. This is an optional parameter which can be included within the function in order to pass attributes through the shortcode. An example of the above with the $atts parameter would look like this:
function list_bookmarks($atts) {
extract($atts);
INSERT CODE HERE
}
add_shortcode('list_bookmarks', 'list_bookmarks');
The call to the shortcode could now look like this:
[list_bookmarks category=“Uncategorised”]
The above will then pass a variable called $category inside the function, with the value “Uncategorised”.
The above code now looks for attributes passed through the shortcode and creates a variable out of each (using the PHP ‘extract’ function). If no attributes are passed through, your function will throw an error.
One thing to keep in mind with WordPress shortcodes is that when displaying information, it is recommended that one uses return instead of echo to display the information.
Your shortcode could perform any function you desire, from displaying a single line of text to creating a large page of content with functionality, database queries and more. This is also a great way to be able to re-use code, as well as be able to shirt content around your website with just the move of a single string of text.
I hope this post has been informative and useful. (make sure to check any native WordPress shortcodes so as to not create shortcodes with names that have already been used in WordPress, eg: gallery).
For more on WordPress shortcodes, check out the WordPress Codex Shortcode API.
