Shortcodes are one of the most ubiquitous features used throughout thousands upon thousands of plugins. If a plugin does anything more than very basic or specific tasks, it is likely that it uses one or more shortcodes as a means for the user to apply the functionality of the plugin to their site.
Gallery plugins use shortcodes to display image galleries on specific pages; Google Maps plugins use shortcodes for embedding maps onto posts or pages; ecommerce plugins use shortcodes to place purchase buttons on the site.
Shortcodes are everywhere and they can be exceptionally powerful, but they can also be used poorly, providing a less than stellar user experience.
I would like to help you better utilize this tremendously powerful feature of WordPress to make your plugins better. To do that, we first need to have a solid understanding of how the shortcodes API works and how to use it.
Even if you have created shortcodes before, it is always beneficial to go back to the basics and re-look at the API from the very beginning.
The Shortcode API was first introduced in WordPress 2.5 and consists of several main functions:
- add_shortcode() – This is the primary function that is used to register a new shortcode
- shortcode_atts() – This function is used for setting up the attributes that can be passed to a shortcode
- shortcode_exists() – This function checks if a specified shortcode has been registered
- has_shortcode() – This function lets you check if the specified content contains a specific shortcode
- remove_shortcode() – This function lets you deregister a shortcode
- remove_all_shortcodes() – This function lets deregister all registered shortcodes
- do_shortcode() – This function lets you parse all shortcodes present in a text string
- strip_shortcodes() – This function removes all shortcodes from a specified text string
- get_shortcode_regex() – This function returns the regular expression that is used to detect shortcodes inside the post content
We will get into each (or at least most) of these functions as we continue through the series, so do not worry about fully grasping what each one does just yet.
A shortcode is really quite simple. In its basic form, a shortcode is nothing more than a placeholder that is placed in the content area of a post, page, or custom post type and then programattically replaced with HTML markup, Javascript, CSS, and more by PHP when the content is rendered on the frontend of the website.
For example, if you add [gallery] to a post or page, it will be automatically replaced with any images that you have uploaded to the post or page.
WordPress core includes several default shortcodes:
- [gallery]
- [audio]
- [video]
- [caption] / [wp_caption]
- [video]
- [playlist]
The shortcodes included in WordPress by default are all related to the display of media items, but there are many, many more use cases for shortcodes, and that is where plugins come in.
Registering a shortcode in WordPress is really simple. All we have to do is tell WordPress what our shortcode is and then instruct WordPress on the callback function to be used when the shortcode is rendered. It looks like this:
function pw101_sample_shortcode( $atts, $content = null ) {
// Display something here
}
add_shortcode( 'pw101_sample', 'pw101_sample_shortcode' );
Once we have registered it with the add_shortcode() function, we can use the shortcode in the main content area of any post, page, or custom post type, like so:
[pw101_sample]
Let’s look at more complete example.
Assume for a moment that we wanted to setup a shortcode that let us display text in a special “box”, perhaps for alert messages. The shortcode for this would look something like this:
function pw101_box_shortcode( $atts, $content = null ) {
// Display something here
$box = '<div class="pw-box">';
$box .= $content;
$box .= '</div>';
return $box;
}
add_shortcode( 'pw101_box', 'pw101_box_shortcode' );
This shortcode is quite simple and lets us do this:
[pw101_box]This is the content displayed in my box HTML[/pw101_box]
When calling add_shortcode(), there are two parameters passed to your callback function:
- $atts – This is an array of all attributes passed to the shortcode. For example, color is an attribute: [pw101_box color=”blue”]
- $content – This is the content that is placed between the opening, [pw101_box], and the closing, [pw101_box] tags
Our simple box shortcode is doing nothing more than wrapping the content placed between the opening and closing tags in a DIV tag that has a special class. Our plugin would then style the div.pw-box via CSS.
Let’s go a little further now and add support for specifying a color in our shortcode. This is done by utilizing the shortcode_atts() function:
function pw101_box_shortcode( $atts, $content = null ) {
$atts = shortcode_atts( array(
'color' => 'blue'
), $atts, 'pw101_box' );
// Display something here
$box = '<div class="pw-box ' . esc_attr( $atts['color'] ) . ">';
$box .= $content;
$box .= '</div>';
return $box;
}
add_shortcode( 'pw101_box', 'pw101_box_shortcode' );
The shortcode_atts() function lets us setup an array of the default attribute values, but then allow those attribute values to be overwritten by the user that is using the shortcode.
With this example, using [pw101_box] is the same as using [pw101_box color=”blue”] because we have set our color attribute to have a default color of blue. If, however, we pass red to the color attribute, our HTML will have a red class appended to it instead of blue. This color class allows us to target the box with CSS and provide a unique background color, border, etc, for each color option.
This has just been a basic look at shortcodes and shortcode attributes, so we will be going much further in depth in the upcoming parts to this series.