How To Create Your Own WordPress Shortcodes

Shortcodes are a very powerful feature of WordPress. In essence a shortcode is a placeholder for some other content. A well-known shortcode is the built-in gallery shortcode. Just type into the WordPress editor and it will be replaced by a gallery of images taken from media uploaded to the post.

Although the media uploader gives you a nice interface to create a gallery, behind the scenes however, a shortcode is built, something like this: . Depending on your theme this may look different on your installation but one possible output would be something like this:

The HTML you would need to write to make this happen is pretty hefty; using the shortcode makes it considerably faster. If you need to do any repetitive tasks in the post editor or you need a specific HTML format which takes a while to mark up, you may find that your own shortcode can help.

In this article I’ll show you how shortcodes work and how you can create your own through some easy examples.

The Basics Of Shortcodes

As I mentioned, shortcodes essentially get replaced by some other content you define. Let’s take a look at the basics through an example. Let’s assume that throughout your post you want to reference the owner of the website.

"According to our company’s owner – Daniel Pataki – the main goal of the website is to generate lots of money. Daniel Pataki thinks that sharing is also important."

Instead of writing "Daniel Pataki" we could use a shortcode.

"According to our company’s owner – [owner] – the main goal of the website is to generate lots of money. [owner] thinks that sharing is also important."

This would allow us to change the name of the owner in one location, so in the event that the owner changes, all instances of our shortcode would use the new name.

Coding this is actually pretty simple. We’ll need to use the add_shortcode() function to tell WordPress about our shortcode, and then create our function to handle the output:

add_shortcode( 'owner', ‘owner_output' );
    function owner_output() {
    return ‘Daniel Pataki';
}

Note that this code should be added to your theme’s functions.php file or your plugin’s files. If you are using a third party theme I recommend using a child theme.

The add_shortcode function requires 2 parameters: the first parameter is the shortcode WordPress tries to match — this is what you write between the square brackets — the second parameter is the name of the function which handles the output, which is completely up to us.

Inside our output handling function we need to return the output that we want to replace our shortcode.

Shortcode Attributes

It is important to be aware that our shortcodes can use attributes as well. For instance, if you want to make sure that the owner of the website is shown in bold, you can make this happen by creating a attribute named "bold" and when that is set to true, the appropriate HTML tags will be added.

add_shortcode( 'owner', ‘owner_output' );
function owner_output( $atts ) {
    $atts = shortcode_atts( array(
        ‘bold' => false
    ), $atts );
    if( $atts[‘bold'] == true  ) {
        return ‘<strong>Daniel Pataki</strong>';
    }
    else {
        return ‘Daniel Pataki';
    }
}

This looks a lot more intimidating, but in reality it’s fairly straightforward. First of all, start out with visualizing how your shortcode would be used. When typing your shortcode you would do this:

[owner bold='true']

We now know that we’re going to have an attribute named "bold".

In our output handling function we use the shortcode_atts() function to parse out all the attributes and give some of them default values. We are making sure that if you don’t specify what the value of "bold" is, then it is set to false.

Next we just take a look at the value of the bold attribute. If it is true we return the name of the owner in a strong tag, otherwise we just return it as is.

Shortcode Content

Shortcode content is usually used when a bit of content needs to receive special HTML formatting. Let’s assume that your website uses fancy titles like this:

<h1><span class="fa fa-check"></span>My Title</h1>

This is a special title which is a level one heading and contains an icon as well. We could create this as a shortcode using the following formatting:

[title icon='check']My Title[/title]

Note that we’re using an opening shortcode tag which has some parameters and a closing shortcode tag. The content within (My Title) is passed to our output generating function as the second parameter.

add_shortcode( ‘title', ‘title_output' );
function title_output( $atts, $content ) {
    $atts = shortcode_atts( array(
        ‘icon' => ‘pencil'
    ), $atts );
    return ‘<h1><span class="fa fa-' . $atts[‘icon'] . '">' . $content . ‘</h1>';
}

As you can see, the default icon is "pencil", unless it is defined in the shortcode. The content is passed as the second parameter and is used as the content inside the level one heading.

Practical Uses

There are a great number of uses for shortcodes from placing sliders and galleries into posts, to countdown timers and other dynamic content. These usually require some Javascript and CSS to work well. In these cases it is up to your imagination and your coding chops.

There are a number of things you can do to make your life easier (even as a non coder), such as to simplify the editing and writing process. Let’s say you write game reviews and in each one you need to enter a table like this:

<table>
<tr>
    <th>Title</th>
    <th>Developer</th>
    <th>Genre</th>
    <th>Price</th>
    <th>Our Verdict</th>
</tr>
<tr>
    <td>Never Alone</td>
    <td>Upper One Games</td>
    <td>Indie Casual Adventure</td>
    <td>$14.99</td>
    <td>5/5</td>
</tr>
</table>

Even if you copy-paste this from article to article, it’s a fair amount of mucking about compared to the amount of content you are adding. You could use a simple shortcode to get the job done:

[final_table title="Never Alone" dev="Upper One Games" genre="Upper One Games" price="14.99" rating="5"]

Your shortcode output function would be responsible for adding the whole table and other bits of content around this information, something like this:

add_shortcode( ‘final_table', ‘final_table_output');
function final_table_output( $atts ) {
return ‘
<table>
<tr>
    <th>Title</th>
    <th>Developer</th>
    <th>Genre</th>
    <th>Price</th>
    <th>Our Verdict</th>
</tr>
<tr>
    <td>' . $atts[‘title'] . '</td>
    <td>' . $atts[‘dev'] . '</td>
    <td>' . $atts[‘genre'] . '</td>
    <td>$' . $atts[‘price'] . '</td>
    <td>5/' . $atts[‘rating'] . '</td>
</tr>
</table>
';
}

The Christmas Easter Egg

So you got this far and it’s nearing Christmas time so I thought I’d include a little easter egg. The Christmas Countdown Widget is a plugin which gives you the opportunity to add a Santa-themed Christmas countdown to your website as a sidebar widget or as a shortcode.

Install, activate and use [countdown] anywhere in your post content to add Mr. Clause to your post.

Conclusion

I think shortcodes are great because they allow non-coders to simplify their workflows and can increase in complexity as you expand your coding knowledge. I suggest trying to create a shortcode here and there as you have more complex needs.

For a list of all default shortcodes take a look at the Shortcode section in the WordPress codex. For more information take a look at the Codex, and you may also want to bookmark the Shortcode Generator which can save you a few keystrokes when creating your generator functions.