We as a WordPress developer must have definitely explored the WordPress CMS up to an impressive level. Shortcode API is one such WordPress feature that might have kept you occupied all through these years of being an avid WordPress fan.
Introduced with version 2.5, WordPress Shortcode API has undoubtedly allowed us(developers) to add both, simple and complex features into plugins and themes, without the need for inserting even a single piece of HTML code.
In this tutorial, I'll be talking about using the WordPress Shortcode API available in WordPress. I'll also be covering details about creating shortcodes and handling attributes.
Let's begin by taking a closer look at WordPress Shortcode API (Application Programming Interface)
The Shortcode API is a simple set of functions that are utilized for creating macro codes to be finally used in post content. For example, here is a shortcode that allows you to add a video gallery into a page:
The above shortcode allows the plugin developers to create specific kinds of content including forms, content generators, etc. which can then be attached to the specific page via the addition of the corresponding shortcode into the text of the page.
Now, coming to the WordPress Shortcode API, it enables you to create shortcode which support specific attributes like this:
This Shortcode API will handle all the complex parsing, without the need for you to define a custom regular expression for each shortcode.
Now, let's discuss about the steps you need to take for utilizing the WordPress Shortcode API
Step 1- Create shortcodes via registering the shortcode handler
Similar to WordPress filters, shortcode handlers accept specific attributes and return a shortcode output. While writing shortcode names, ensure to use lowercase letters, numbers and underscores only, refraining from using hyphens/dashes.
Now, use the add_shortcode function for registering the shortcode handler.
This function will fetch two parameters viz: shortcode name and callback function name.
Talking specifically about the shortcode callback function, you can choose to pass any of the below mentioned three parameters to it:
- $atts – this is an array of attributes. If no attributes are available, this will represent an empty string.
- $content – this is the enclosed content, applicable only in case the shortcode is used in the enclosing form
- $tag – This is the shortcode tag, applicable in case of shared callback functions
Simply use the below API call for registering shortcode handler:
add_shortcode( 'newshortcode', 'new_shortcode_handler' );
Now, when the template tag i.e. the_content is displayed, WordPress shortcode API will parse all the registered shortcodes including “[newshortcode]” followed by separating and parsing the attributes along with content.
Finally, the attributes and content will be passed to their corresponding shortcode handler function. Additionally, any string that's returned by the shortcode handler will be included within the post body, replacing the shortcode.
Step 2- Add attributes for the shortcode
Now, here is an example of PHP code used for creating the shortcode:
//[finestatus]
function finestatus_func( $atts ){
return "fine and status";
}
add_shortcode( 'foobar', 'finestatus_func' );
Upon implementation of the above code, a new shortcode [finestatus] will be created and will return output as: fine and status. Next, you can enter the attributes for this shortcode as shown below:
[newshortcode new="fine" fine="bing"]
The entered attributes will further be converted into an associate array as shown below:
array( 'fine' => 'status', 'status' => 'bing' )
In the above code, the array has been passed to the handler function as its $atts parameter. Also, the zeroeth entry i.e. $atts[0] holds the string which matches the shortcode regex.
Final output- How's it going to be like?
As the final output, the return value of the shortcode handler function will be inserted into the post content output via the replacement of shortcode macro.
With the shortcodes being parsed only after applying the wptexturize and wpautop post formatting, the shortcode output HTML won't automatically have the br and p tags added and the curly quotes applied.
If you aren't inclined to formatting the shortcode output, then make sure to call wpautop() or wptexturize() once the output is returned from the registered shortcode handler.
As an additional tip, if the shortcode is producing loads of HTML code snippets, then you can opt for using ob_start for capturing the output, followed by converting the same into a string as explained below:
function newShortCode() {
ob_start();
HTML here ...
return ob_get_clean();
}
In Conclusion
WordPress Shortcode API definitely serves as a great add-on for your WP website. I hope the information mentioned above would allow you to take complete advantage of this excellent WordPress 2.5 version offering.
You may also like to read:
- How to Display RSS Counter in WordPress blog
- Giveaway : 3 Annual Subscriptions to 1Theme Premium WordPress Themes
- 30 Fresh Corporate WordPress Business Themes
- WordPress Themes – 30 Hot New Template Designs
- Top 10 Premium WordPress Themes April 2014
