WordPress shortcodes were introduced in version 2.5 and since then have proved to be one of the most useful features. The average user acting as editor has the ability to publish dynamic content using macros, without the need for programming skills.
When a shortcode is inserted in a WordPress post or page, it is replaced with some other content. In other words, we instruct WordPress to find the macro that is in square brackets (
) and replace it with the appropriate dynamic content, which is produced by a PHP function.
The usage is pretty simple. Let’s say we want to show the most recent posts in a given post. We could use something like this:
For a more advanced shortcode, we could set the number of posts to display by setting a parameter:
Going one step further, we could set a heading for the list of recent posts:
In the first part of this tutorial, we will create the code for this simple shortcode:
The creation process is simple and does not require any advanced PHP knowledge. The basic steps are:
- Create the function, which will be called by WordPress when it finds a shortcode.
- Register the shortcode by setting a unique name.
- Tie the registration function to a WordPress action.
All codes in this tutorial can be placed in
functions.php or in a seperate PHP file that will be included in
When a shortcode is found, it is replaced by some piece of code, which is the callback function. So, let’s create a function that fetches recent posts from the database.
As shown, we’re querying the database to get the latest post and return a string with a link to it. Ιt is worth noting that the callback function does not print anything, but rather returns a string.
Now, we tell WordPress that this function is a shortcode:
Ιf a shortcode of
[recent-posts] is found in a post’s content, then
recent_posts_function() is called automatically. We should ensure that the shortocode’s name is unique in order to avoid conflicts.
In order to execute our
register_shortcodes() function, we will tie it to WordPress’ initialization action:
Our simple shortcode is ready, and the next step is testing that it operates properly. Let’s create a new post (or open an existing one) and put the following line somewhere in the content:
Publish the post, and viewing it in a browser, you should see a link to the most recent post on your blog, as shown in this screenshot:
Shortcodes are flexible because they allow us to add parameteres in order to make them more functional. Let’s say we want to display a certain number of recent posts. To do this, we need to add an extra option to our shortcode that specifies how many recent posts to show.
We have to use two functions. The first one is WordPress’ built-in
shortcode_atts() function, which combines user shortcode attributes with native attributes and fills in the defaults where needed. The second function is the
extract() PHP function, which does what its name suggests: it extracts the shortcode attributes.
Extending our callback function, we add an argument, which is an array of attributes from which we extract the parameter for the number of posts. Then we query the database to get the desired number of posts and create an HTML list to show them.
If the user skips the option,
1 is the default value. In the same way, we can add more attributes, enabling the shortcodes to accept multiple parameteres. Thanks to this enhanced function, we can set how many posts to show:
When viewing it in the browser, you should see links to the five most recent posts in the content:
We can take our shortcode one step further and add the ability to pass some content as an argument, which in this case will be a heading for the list of recent posts. To do this, we use a second parameter,
$content, in the callback function and add it as an
h3 heading before the list. The new function is as follows:
This kind of shortcode is similar to an HTML tag. We enclose the content in an opening and closing shortcode:
The result is the same as the previous example, except for the new heading for the list of posts:
Content in shortcode
By default, shortcodes are ignored in WordPress sidebar widgets. Take the following as an example:
If you type this shortcode into a widget, it would look something like this:
A shortcode in a widget before enabling the functionality
With WordPress, we can enable this functionality with a single line of code. To be able to add shortcodes in widgets, add the following:
Now, without having to change anything else, the shortcode will display properly in widgets:
A shortcode in a widget after enabling the functionality
Similarly, we can enable shortcodes in comments:
While shortcodes are a handy way to add dynamic content to posts, the might be a bit confusing for the average user, especially when they get complicated, with multiple parameteres. Most users are not familiar with HTML-like syntax; and yet they have to remember the exact syntax and all available attributes of shortcodes, because even a minor syntax error could cause an undesirable result.
To resovle this, we can add a button to the TinyMCE editor`s interface, enabling the user to create a shortcode with a simple click. There are two basic steps to creating this button:
recent-posts.js in the
js directory of our theme, and then we type the following piece of code:
As shown below, we create a new plugin, calling the
tinymce.create() method, passing in the plugin’s name and the attributes. The most important part of this code is the
init() function, where we define a name, an icon file and an event handler for the button using the
onclick() function.<1 p="">1>
In the first two lines of the
onclick() function, the user is prompted to input the parameters for the number of posts and list heading of the shortcode. Then, depending of the values of these parameters, the appropriate shortcode form is inserted in the editor.
Finally, our TinyMCE plugin is added to the PluginManager using the
add() function. Now we’ve successfully integrated the
[recent-posts] shortcode into a WordPress theme.
The first function is named
register_button() and pushes the shortcode into the array of buttons, adding a divider between the new button and the existing ones:
The second function,
The next step is to add a filter with the previous functions. The
register_button() function is tied to the
mce_buttons filter, which is executed when the editor loads the plugins, and
add_plugin() is tied to
mce_external_plugins filter, which is executed when the buttons are about to be loaded:
The previous function takes no action if the user does not have permission to edit posts or pages or if the user is not in visual editor mode.
Finally, we hook the function into WordPress’ initialization action to execute this when a page loads:
To check that the shortcode button functions properly, let’s create a new post or edit an existing one. A new button, with the icon that we set before, should have been added to the left of the first line of the TinyMCE buttons, as in this screenshot:
Shortcode TinyMCE editor button
When we press the shortcode button, a dialog appears that prompts us to type the shortcode parameter for the number of posts:
Shortcode TinyMCE editor button
After inserting the number of posts, a second dialog appears, prompting us to type in the heading of the list:
Shortcode TinyMCE editor button
If any parameter is left blank, it will not be included in the final shortcode.
Finally, the shortcode appears in the editor:
Shortcode TinyMCE editor button
This part of the tutorial provides the source code for some userful WordPress shortcodes that will take your blog one step up.
One simple example is the link button shortcode:
Use this shortcode as follows:
Something like this should appear:
Link button shortcode
Let’s move on to a more complex shortcode, one that grabs a WordPress menu:
When calling this shortcode, pass in the name of the menu you want to show:
The menu will appear in your content:
A Google Maps shortcode is really useful, because we can insert a map into our content without needing to edit the source code.
When typing the shortcode, pass in the width and height and the link from Google Maps as parameters:
The result is the following:
Google Maps shortcode
Another useful service is Google Charts, because it is very customizable. Here is a shortcode example with multiple attributes:
To create a pie chart with four types of data, we insert the following line:
The result is a pie like the following:
Google Charts shortcode
We can use the Google Docs PDF viewer to embed a PDF on your website. Here is the shortcode to do this:
To embed a PDF, type the shortcode
[pdf], and pass in the URL as the content argument:
When viewing the page, the visitor will see a viewer with the PDF:
PDF embedding shortcode
Thanks to WordPress plugins, adding shortcode functionality to a website requires no source-code editing at all. If you look at the WordPress plugins directory17, you’ll see a large number of such plugins with which to style posts and pages. In this section, we’ll recommend some of the best shortcode plugins (favoring the free ones) to satisfy your every need.
Without a doubt, this is the best shortcode plugin out there. It enables you to easily create buttons, tabs, boxes, sliders, tooltips and many more elements.
The J Shortcodes plugin is similar to Shortcodes Ultimate, offering a collection of useful elements to style a website, including buttons, boxes, tabs and accordions. J Shortcodes lets you set custom attributes on elements, such as color, size and shape, and define custom column layouts on any page or post.
Shortcodes Pro does not offer ready-to-use shortcodes. Instead, this plugin allows for quick and easy creation of WordPress shortcodes from inside WordPress’ administration panel.
Natively, WordPress does not provide functionality to execute pieces of PHP source code on posts or pages. Shortcode Exec PHP plugin enables you to execute PHP code in WordPress content using manually defined shortcodes.
Last but not least, here are some articles you might find useful.
“Mastering WordPress Shortcodes26,” Smashing Magazine
A great article that shows how to create and use shortcodes, providing some ready-to-use WordPress shortcodes.
“Getting Started with WordPress Shortcodes (+Examples)27,” SpeckyBoy
This tutorial is a good place to start messing with shortcodes.
“Getting Started With WordPress Shortcodes28,” Tuts+
This gives a detailed explanation of the WordPress shortcode API, showing some useful examples of more advanced shortcodes.
“Shortcode API29,” WordPress Codex
The official page of the API in the WordPress Codex.
“Shortcodes30,” WordPress Support
Lists some useful built-in shorcodes.