Themes and Mods

Creating a Custom Shortcode Using the WordPress Shortcode API

WordPress shortcodes are a powerful tool that help you save your time in implementing custom contents – that otherwise require coding skills and most likely plenty of code.

Adding shortcodes to your themes or plugins, make the task of adding custom contents like buttons, forms, etc., so much easier. For instance, inserting a shortcode [Recent-posts] would display the list of recent posts of your website. However, if you needed to accomplish the same task manually, you would need to write HTML code and embed the code whenever you need to show up list of recent posts. For it’s worth, WordPress shortcodes simplifies things to a great extent.

You can create shortcodes using the WordPress Shortcode API. Introduced with the release of WP version 2.5, the Shortcode API helps to add macro codes in your website pages/posts.

Through this post, I would like to help you gain insight on how you can utilize the Shortcode API for creating shortcodes, through a simple to follow step-by-step process.

Step 1 – Register a Shortcode Handler

For writing shortcodes, you need to use a handler function. The shortcode handler function work a lot like WordPress filters: they are passed different parameters (also known as attributes) and return ‘output of the shortcode’ as a result.

Note: Keep in mind that the shortcodes names should mainly consist of lowercase letters, however, they can also use numbers and underscores. But, make sure to avoid including hyphens in your shortcode name.

In order to use the shortcode handler function, you’ll first have to register it using the “add_shortcode” function. This function requires two parameters: one is “shortcode name” and the other one is the “callback function name”.

The callback function takes in three parameters. You can choose to use any of those parameters, or none. These parameters are:

$atts – Using this argument, you can define an array with or without attributes
$content – It can be used to define the enclosed content i.e. the shortcode in its enclosing form
$tag – This parameter is useful for defining the shortcode tag for the shared callback functions

In order to get the shortcode handler registered, you will have to make an API call as follows:

add_shortcode( ‘mycustomshortcode’, ‘mycustom_shortcode_handler’ );

Step 2 – Adding Attributes for the Shortcode

In this section, we will basically discuss about how you can create a shortcode with arguments. To help you understand this process in a better way, here is a simple example of PHP code that you simply need to copy and paste in your theme’s functions.php file:

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

add_shortcode( ‘my_button’, ‘my_custom_shortcode’ );

In this code, I’ve defined a shortcode handler function: my_custom_shortcode that will return the output of the custom shortcode. Next, an array (i.e. $atts) is passed to the handler function that accepts three different arguments such as:

‘text’: ‘My Custom shortcode button’,  //text to be displayed on the my_button shortcode
‘color’: ‘#ffffff’,     //color of the text
‘bg’: ‘#d3d3d3’      // background color of the shortcode button

And then, the return statement helps in changing the attribute values of our shortcode. Lastly, the add_shortcode function (as we had discussed previously) will help to register our shortcode.

Once you have saved your functions.php file, the custom function will be called automatically whenever the newly created shortcode ‘my_button’ is used.

Let’s Wrap Up!

Hopefully this tutorial will help you learn about the importance of WordPress shortcodes, and will guide you to implement custom shortcodes anywhere on your WordPress page/post.

Author Bio:
Jack Calder is working as web developer in Markupcloud Ltd which is one of the top PSD to HTML conversion company having long term expertise in web design & development field.