With WordPress version 4.1 available for download, I'm sure none of us have forgotten the amazingly effective features that were introduced in the prior versions. One such WP utility worth making a note of, is the Shortcode API(Application Programming Interface).
What will you find in this tutorial?
I have written this tutorial to make you familiar with what exactly is the WordPress Shortcode API and how it can be utilized for enhancing the capability of using short tags in content, displayed for posts and/or pages.
A brief on WordPress Shortcode API
Shortcode API was introduced in WordPress 2.5 and is basically a simple set of functions that allows you to create a macro code to be used in post/page content. That means, you can easily avoid the need for any programming skills. For example, here is a shortcode that allows you to display all the recent posts available for a particular post category:
[recent-posts]
Moreover, you may even opt for setting a display count for these posts by using an advanced shortcode like this:
[recent-posts posts="10"]
The Shortcode API offers developers utmost convenience of creating special kinds of content like forms etc. which can further be attached to specific pages via addition of corresponding shortcode. While the API handles all the complex parsing, you need not write a custom regular expression for each individual shortcode that you need to include in your posts/pages. This API is equipped with several Helper functions which aid in setting and fetching the default attributes.
- Here is an explanation of different steps that would mark the utilization of WordPress Shortcode API
Step 1- Register shortcode handler
Shortcodes are written with the help of a specific handler function. Quite similar to WordPress filters, these shortcode handlers accept different attributes and return a result i.e. the shortcode output. While creating shortcodes names, use lowercase letters, numbers and underscores; avoiding hyphens.
Use the add_shortcode function for registering the shortcode handler. This function uses two parameters viz: shortcode name(i.e. The string which is used in post body) and callback function name.
Next, you can choose any number of parameters(out of the three) which can be passed to the shortcode callback function. These have been listed down:
- $atts- choose this parameter if you have an array of attributes to be defined for the shortcode or have an empty string with zero attributes
- $content- choose this parameter if you want to use the shortcode in an enclosed form
- $tag- choose this parameter if you want to use a shortcode tag for shared callback functions
Use the below API call to register the shortcode handler:
add_shortcode( 'customshortcode', 'custom_shortcode_handler' );
When the template tag i.e. the_content is displayed, the shortcode API will parse all the registered shortcodes(for eg: “[customshortcode]” as per this tutorial). After this, the attributes and content will be separated, parsed and passed to the related shortcode handler. Here, you need to note that any string which is returned by shortcode handler will automatically replace the shortcode in the post body.
Step 2- Enter attributes for the shortcode
Here is an example of PHP code that is required for creating a shortcode:
//[newrule]function newrule_func( $atts ){ return "new and rule";}add_shortcode( 'foobar', 'newrule_func' );
Implementing the above code will create [newrule] shortcode which will return output as: new and return. The attributes for this shortcode would be entered as:
[customshortcode new='rule” rule=”bing”]
Now, these attributes would be converted into an associative array like below:
array( 'new' => 'rule', 'rule' => 'bing' )
In the above code, the array keys are attribute names and attribute values are their corresponding values. Here, the array is passed to the handler function as its $atts parameter, with the zeroeth entry i.e. $atts[0] holding the string that matches the shortcode regex.
A look at the final output
The return value of your shortcode handler function will then be inserted into the post content output, replacing the shortcode macro.Since shortcodes are parsed only after applying the wpautop and wptexturize post formatting, your shortcode output HTML will have curly quotes along with p and br tags as add-ons. If your shortcode is producing a lot of HTML code, then you can choose to use ob_start for capturing this output and converting it into a string as explained below:
function customShortCode() {
ob_start();
?> <HTML> <here> ... <?PHP
return ob_get_clean();
}
Bonus tip on handling attributes for a shortcode
Although the $atts array includes arbitrary attributes specified by the user, you may easily eliminate any attributes that are not recognized by the shortcode. You can do this with the help of shortcode_atts() function which resembles the wp_parse_args function and includes below mentioned parameters:
shortcode_atts( $defaults_array, $atts );
Here, $defaults_array is the associate array which defines the recognized attributes names along with their default values. $atts represents the raw attributes array which is passed into the shortcode handler and finally, the shortcode_attas() which will return a normalized array including all keys derived from $defaults_array. Here is the code associated with the same:
$a = shortcode_atts( array( 'title' => 'My Title', 'new' => 345,), $atts );
Looking at the above code, it is quite clear that if $atts was to include array( 'new' => 678, 'rule' => 'something' ), then the resulting $a would be an array as 'title' => 'My Title' , 'new' => 678. That means, the new value $atts i.e. 'new' would override the default value of 345.
So, that's it for now!
Wrapping Up
Here's hoping the details covered above would aid you in taking the full advantage of WordPress Shortcode API. So, get on and make the most of everything that's included in this absolutely brilliant WP 2.5 version feature.
No comments:
Post a Comment