How to use shortcodes in WordPress?

June 23, 2014

 - Tags: ,

Have you ever wanted to add some special content to your website, like a Twitter widget, or any other embedded content called back from another website? WordPress Shortcodes exists for this. All you have to is to add a shortcode in your post or page editor, and it will automatically be transformed into the desired special content once your page is loaded. In this article, I will show you how to create and use shortcodes.

Introduction

A shortcode is a special tag that you first put into a post that then gets replaced with a special content when displaying the post on your website. For example, WordPress galleries use a shortcode: you put a [gallery] in your post, and it actually displays a gallery on your website. This provides a very easy way to add special content in your website. WordPress is shipped with some shortcodes, but you can also create your own. And that’s what make these shortcodes so powerful. For example, it’s possible to use shortcodes to display youtube videos, show your tweets or anything else you like.

Example

Let’s see a specific example with the plugin Contact Form 7 which allows you to easily create contact forms.

  1. First, you create a contact form with the graphical interface of the plugin. No need to code, just use user-friendly interface and the plugin will create the html code for you
  2. Once you created the contact form, the plugin will provide you with the shortcode of the plugin. This will look like something like this:
    [contact-form-7 id="1234" title="Contact form 1"]
    Make sure you copy this shortcode
  3. Paste the plugin in the page or post you want it to appear
  4. Reload the page, et voila, your contact form appears magically on your website

Behind the hood, what happened is that when you loaded your page, the plugin replaced the shortcode [contact-form-7 id="1234" title="Contact form 1"] with the actual html code required for the contact form to show on your website.

Another solution would be for the plugin to provide you with the html code directly, instead of a shortcode. You would then have to copy paste the html code of the contact form in the post directly, but that would be a bit tedious, more complex and more prone to error than just having to handle the shortcode. I am sure that now you realize the value provided by shortcodes.

This being said, you must be thinking that all of this is great, but how can I create a shortcode? I will show you this in the next section.

How to create a shortcode?

With WordPress, it is quite simple to create your own shortcodes. Let’s implement our previous example for the contact form.

#1: Create the html code

First, in functions.php, you need to create a function that produces the html code of the contact form:

function output_contactform() {
    $html_output = '<form action="contact.php" method="post" id="contact-form">'
       //Name field
       . '<label for="name">Name</label>'
       . '<input type="text" id="name" name="name">'

       //Email field
       . '<label for="email">Email</label>'
       . '<input type="email" id="email" name="email">'

       //Message field
       . '<label for="message">Message</label>'
       . '<textarea rows="3" id ="message" name="message"></textarea>'

       //Submit button
       . '<button type="submit" value="Submit">Submit</button>'
       . '</form>';
    return $html_output;
}

This function just returns the html code of the contact form. The shortcode will be replaced by the html returned by this function. For the sake of clarity, the function does not take any parameters. That means that this solution will only allow to create a contact form with the fields name, email, and message already predefined for the user. But it is also possible to create more sophisticated solutions allowing users to create contact forms with custom fields (that is actually the functionality offered by Contact Form 7, the plugin I mentioned before.

Note that the function called by the shortcode should never produce output of any kind. Shortcode functions should return the text that is to be used to replace the shortcode. Producing the output directly will lead to unexpected results.

#2: Link the html code to the shortcode

Now, our function return the html code, but how can we link this to a shortcode? This is where the WordPress API for shortcodes will be helpful. For this, we will need to use the following snippet in functions.php:

function register_shortcodes(){
   add_shortcode('contactform', 'output_contactform');
}
add_action('init', 'register_shortcodes');

Here, we first define a function register_shortcode.

Within this function, we use add_shortcode(). The first parameter of this function is the name of the shortcode (contactform in our case) and the second parameter is the name of the function to be called when the shortcode is used (output_contactform in our case).

Finally, we hook register_shortcodes() to the init event, so that it gets called at the right moment during the loading process of WordPress.

How to use a Shortcode?

This is the most simple part. You just need to add the [contactform] shortcode in the editor of your post or page. Congratulations ! You have just created your first shortcode and you can now use it very easily.

Conclusion

  • In the Introduction, I explained that shortcodes where tags that could be added to any post or page to include special content in your website, like youtube videos or tweets. When the page is loaded, shortcodes are replaced with the html of the special content. Some of these shortcodes are already shipped with WordPress, but it is also possible to create your own shortcodes.
  • In the Example, I mentioned the plugin Contact Form 7 that uses shortcode to display contact forms in a easy way for users.
  • Then, we learned how to create custom shortcodes, using the add_shortcode() function to link a shortcode to another function used to output the actual html code of the special content to display.
  • Finally, I showed you how to use these shortcodes, by inserting the shortcode tag in the editor of your post or page.

If you liked the article, you can subscribe to my blog to receive updates when new articles are posted.

If you would like to know more about shortcodes, please check out the below resources.

Additional Resources

  • add_shortcode() function on the Codex: Link
  • ShortCode Api on the Codex: Link
  • A very complete tutorial about shortcodes: Link

Leave a Reply