A Detailed Know-How On Utilizing ShortCode API In WordPress
A Detailed Know-How On Utilizing ShortCode API In WordPress
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.
1 comment