18 Jul

Coding your own WordPress Shortcodes

By: Alexander Gounder

WordPress shortcodes can be used within your page or post content which invokes a specific function  which inserts content at the position of where you inserted the shortcode. Uses for shortcodes are endless, from inserting media content and galleries, to social media like and share buttons, showing lists of recent or related posts, and so on.

Many WordPress themes and plugins will add new shortcodes for you to use, but at times you may wish to add your own custom shortcodes which aren’t already available. Fortunately, WordPress makes developing your own an easy task for anyone who is familiar with WordPress and has basic PHP skills.

Here I’ll show you the basics of how to develop your own custom WordPress shortcode. We might as well make it do something practical, so we will create a shortcode that inserts a Google+ +1 button. These neat little +1 buttons allow your site’s visitors recommend your site in Google search, and share via the Google+ social media platform.

The Anatomy of a Shortcode

A shortcode can be very basic as in a simple tagname within square brackets, but they can also have attributes and content if requred. eg:

For the purpose of this tutorial, we wish to insert a G+ +1 button in place of our shortcode, and we will allow an optional attribute “size”, which can be set to “small”, “medium”, “standard” or “tall” (see Google’s +1 developer documentation page). If the attribute is omitted, then we will default to “standard”.

So example usage of our shortcode will look like:

Google +1 Button Code

As per Google’s documentation, inserting a +1 button into a page is quite simple and doesn’t require alot of code, just the following and then some javascript (refer to their docs page to see that).

For the sake of simplicity, for this tutorial we will assume the shortcode will only be used once per page. If we were to cater for multiple inserts of the +1 button on a single page/post, we would consider shifting the javascript part of their code to the page footer.

Also, button size’s other than the default “standard” are defined by adding an extra attribute to the div tag in the above code, eg: data-size=”medium” .

Where to put our code?

When coding your own shortcode (or any additional WP functionality), you have the choice of adding it to the site’s current theme’s functions.php file, or into a WordPress Plugin.

Typically, if the functionality is specific to the site and it’s theme, I add my code to the theme’s functions.php, but if it were functionality I might want to use across multiple WP sites, or might be changing to a different theme in future, then I opt to write a plugin.

We at CodePeach will soon be posting a set of tutorials on WordPress Plugin Development, but to keep this tutorial simple we will just add to the bottom of the theme functions.php file. Just note that if you upgrade or change your theme in the future, you will need to append any additions again.

Using the Wordpress Shortcode API

The WordPress core provides a Shortcode API which gives us all the functionality required for defining a shortcode. The add_shortcode($tag, $function) function tells WordPress about our shortcode, defining the tag name (eg “gplus”) and which function to invoke when the shortcode is used.

This shows how to use it in it’s simplest form, to define a shortcode [marco] which will return “polo” which will show in the content wherever the shortcode is used:

Coding the Google +1 Button Shortcode

Let’s jump into writing the function which our new shortcode will invoke. We use output buffering within our shortcode function as recommended by the WP Codex, without this the output of the shortcode can appear in an unexpected position in the page content.

And that’s it!

If all went well, you can use it by using a [gplus] shortcode in your content, or to specify another size: [gplus size=”tall”]

Running Shortcodes elsewhere

Sometimes you might find the need to run a shortcode from somewhere other than the content editor. This is made possible by the do_shortcode function.

To run a shortcode from a theme or plugin PHP file:

We hope you find this introductory tutorial for developing your own shortcodes for WordPress useful, and we welcome any feedback via the comments below.. happy coding!

Related Posts