A Handy Guide on Using Shortcode API in WordPress

WordPress popularity is surging, because of the ease it provides to users to improve and enhance the productivity and capabilities of their website. One great feature of WordPress that contributes to its popularity is the WordPress Shortcode API. Introduced with the release of WordPress version 2.5 the Shortcode API, consists of a set of functions that helps in creating macro codes that be placed within WordPress posts/page content. For example, the below mentioned shortcode will display a list of recent posts of specific post category:

How to Utilize Shortcode API in WordPress?

The Shortcode API help developers to create custom contents like buttons, forms, etc. These contents can be embedded into posts or pages by adding their corresponding shortcode. The API can take care of the complex parsing, however, in order to include shortcode in your posts/pages you’ll have to write a custom regular expression for each of the shortcode. Let’s see how you can utilize the WordPress Shortcode API.

Step 1: Register Shortcode Handler Function

Shortcodes are written using a handler function. The handler functions are pretty similar to WordPress filters: they accept different attributes (also referred to as parameters) and then return shortcode output as result.

In order to make use of a shortcode you’ll need to first register a shortcode handler. For this purpose, you need to use the add_shortcode function. This function accepts two parameters: the first parameter is “shortcode name” (i.e. the string within the post body) and the second one is “callback function name”.

The callback function is passed three arguments, however, you don’t need to use all of the arguments and can opt for any one of those arguments:

• $atts – can be used to define an associative array with a number of attributes; or an empty string without any attributes
• $content – this argument let you use the shortcode in an enclosed form
• $tag – this argument is useful for using a shortcode tag for the shared callback functions

Next, you will need to make use of the following API call so that the shortcode handler can be registered.

add_shortcode( 'customshortcode', 'custom_shortcode_handler' );

 Step 2: Entering Attributes for the Shortcode

Here is an example of PHP code that you will need to add in your theme’s functions.php file for creating a shortcode:

function my_custom_shortcode($atts){
    $atts = shortcode_atts(
        array(
            'text' => 'My Custom button',
            'color' => '#ffffff',
            'bg' => '#cccccc'
        ), $atts, 'my_button');
    return '<button style="color:'.$atts['color'].'; background: '.$atts['bg'].'">'.$atts['text'].'</button>';
}
add_shortcode( 'my_button', 'my_custom_shortcode' );

The above code is creating a shortcode that will help you in inserting a custom button into the WordPress post. If you’re a novice developer, probably you may find the code a bit tricky. Let’s break the code to see how it works:

1. To begin with, we’re defining a shortcode handler function named ‘my_custom_shortcode’. This function will return the output of the newly created shortcode.

function my_custom_shortcode($atts){

2. Shortcodes are known for being remarkably flexible, as they allows to add arguments for extending their functionality. For instance, if you want to change the color of the button (i.e. the shortcode we’re creating) we can add an additional option to our custom function. For this purpose, WordPress built-in function “shortcode_atts” can be used – that helps to define default values for the attributes that are missing (i.e. those values that are not recognized by your shortcode).

$a = shortcode_atts(
        array(
            'text' => 'My Custom button',
            'color' => '#ffffff',
            'bg' => '#cccccc',
        ), $atts, 'my_button');

In the above code, shortcode_atts(array, $atts, my_button) function is passed three parameters. The first parameter is an array that specifies the attribute names along with their values that are recognized by the shortcode. Next, the $atts include attributes specified by the user. If the $atts included an array (‘bg’ => ‘D3D3D3’), then the resulting $a would be array ( ‘text’ => ‘My Custom button’, ‘color’ => ‘#ffffff’, ‘bg’ => ‘#cccccc’). The $atts[‘bg’] overrides the default value of #cccccc. Since, the $atts[‘title’] and $atts[‘color’] attributes are not set, the default ‘My Custom button’ is used as the text that will be displayed for our “button” shortcode and the default color used is #ffffff.

3. In this step, the return statement enable us to make changes to our shortcode attributes i.e. button ‘text’ and ‘background color’.

return '<button style="color:'.$atts['color'].'; background: '.$atts['bg'].'">'.$atts['text'].'</button>';

4. The function will get closed.

}

5. Lastly, we’re utilizing add_shortcode function to register our shortcode (refer to step 1). This function is taking two parameters. The first one is ‘my_button’ that can be used with or without arguments, in our case, we’re passing a few attributes to the function like color etc., e.g. [my_button]. The second argument “my_custom_shortcode” is used to tie the shortcode [my_button] with the function: #function my_custom_shortcode($atts).

add_shortcode( 'my_button', 'my_custom_shortcode' );

6. Now all we need to do is to save the theme’s functions.php file. Once it’s done, the custom function can be called whenever the shortcode ‘my_button’ is used.

Conclusion

This tutorial will guide you to implement your own custom shortcodes anywhere on your WordPress website. For this you will have to create a shortcode handler function accordingly, and pass required attributes into the shortcode. Once your shortcode has been created, you can use it anywhere on your site.