While writing code for your WordPress website, you’ll most likely use lot of HTML and CSS code snippets repetitively. This makes website development a tedious and time-consuming task.
Fortunately, WordPress comes with a feature known as shortcodes that you can implement in your site, instead of calling same pieces of code again and again. Shortcodes can be inserted anywhere on your WordPress site. For instance, let’s say you want to display a list of related posts on your home page sidebar. This can be achieved by implementing a shortcode that looks like:
In order to enhance the capability of your shortcodes, you’ll need to use a set of functions called as the Shortcode API. Through this tutorial, we’ll discuss about how we can use the WordPress Shortcode API to create our own shortcodes.
A Brief Introduction to Shortcode API
Released with WordPress version 2.5, the Shortcode API enables developers to add simple to complex features in their theme or plugins without the need to insert any code. It helps to add macro codes in WordPress website pages/posts. Although, WordPress comes loaded with built-in shortcodes, but utilizing the Shortcode API you can create custom shortcodes as well.
The best aspect about using the Shortcode API is that it takes care of tricky parsing, and thus spare you from writing a custom regular expression for every shortcode that you want to add in your page/post. What’s more? It comes with helper functions that help to create and fetch default attributes.
How You Can Utilize The Shortcode API?
Here we will talk about the step-by-step process to understand how you can make use of the Shortcode API, for creating shortcodes:
Step 1: Register the Shortcode Handler Function
In order to create your own shortcodes, you will need a handler function. Shortcode handlers are pretty much the same as WordPress filters: they are passed some attributes (or parameters) and then return the output of your shortcode.
Note: Make sure that your shortcode name is written in lowercase, but you can use use numbers and underscores within the name too. However, avoid using hyphens (dashes).
You need to register the handler function that you want to use for writing your shortcodes. The WordPress built-in function ‘add_shortcode‘ is used for registering shortcode handler. This function accepts two parameters such as:
- The name of the shortcode name;
- and the callback function name.
The shortcode callback function accepts 3 parameters, however, you can utilize any one of those parameters (or use none of them). Let us look at all these parameters:
- $atts – This parameter allows you to specify an array with attributes, or an empty string without any attributes
- $content – This parameter accepts the enclosed content within the shortcode
- $tag – Also called as the shortcode tag, this parameter is useful for shared callback functions
Below is the API call, you need to make for registering the shortcode handler:
add_shortcode( 'firstshortcode', 'first_shortcode_handler' );
When the template tag “the_content” is showed up, the shortcode API will look for registered shortcodes (in our case, it would be “[firstshortcode]“). Next, the attributes as well as the content (if any) will be separated and parsed. And then, they’ll be passed to the matching shortcode handler function. In case the shortcode handler returns a string, it will be embedded into the post body for the shortcode.
Note: In this line of code, you can see that the shortcode name is ‘firstshortcode‘ and the name of handler function is ‘first_handler_function‘. You can change the name of the shortcode and handler function according to your own needs.
Step 2: Passing Attributes to Shortcode
You can add useful features to your shortcodes, by entering some attributes. Below is an example that demonstrates how you can create a shortcode with attributes:
function firstshortcode_func( $atts )
{
return "new and rule";
}add_shortcode( 'foobar', 'firstcode_func' );
This code will create a shortcode “[firstshortcode]” and all of the values of the shortcode is stored in the array “$atts”. But the array doesn’t contain any attributes and the shortcode will return output as: new and rule. Let us now see how we can enter attributes for the array:
[firstshortcode new=”rule” rule=”bing”]
In order to convert it into an associative array, you need to use the following line of code:
array( 'new' => 'rule', 'rule' => 'bing' )
Let us now look at how our final output will look like:
function firstshortcode() {
ob_start();
?> <HTML> <here> ... <?PHP
return ob_get_clean();
}
Your shortcode handler function output will be inserted into your post content output, and will replace the shortcode macro code. Keep in mind that shortcodes gets parsed only when it has applied “wpautop” and “wptexturize” post formatting, This clearly suggests that, you will have to call wpautop() or wptexturize() to format your shortcode output. Lastly, in case your shortcode generates lots of HTML code, then it is recommended that you can use ob_start to seize the output and then convert it into a string (as shown in the above code).
Let’s Wrap Up!
The WordPress Shortcode API is a powerful tool that helps developers to insert some special content, for example, forms and others to their website page or post by adding corresponding shortcodes. If you too want to make use of the Shortcode API, then hopefully reading this tutorial will serve as a good starting point for you.
About The Author:
Jack Calder is working as Front End Developer with wide experience on how to convert psd to html files at Markupcloud Ltd. He also shares his knowledge across the web.