WordPress Shortcodes

WordPress has a functionality called shortcodes which gives you the ability to insert generated elements into your posts just by typing in a shortcode in the text. All you need to do to make this work is to define a function in your theme’s functions.php file, and hook this funcion to a shortcode using WordPress API for shorcodes. A shortcode is a word enclosed with [ and ] like

[this]

What this means is that you can write a function in PHP, this could be anything you like, as long as it return some data. The data returned will replace the shortcode before the page is sent to the visitor. A popular use for this is Google AdSense, this would allow you to insert ads into your post by entering the code you defined for adsense. Now you can easily place ads where ever you want in your posts.

First let’s try something simple

First let’s create a simple function that returns the word bar. Open the file functions.php which is located in your theme’s directory.

function sc_foo() {
    return 'bar';
}

Now whenever we call this function it will return a string with the word bar. it’s pretty straight forward.

[adsense-banner]

Now that we have our function in place let’s associate this function whit a shortcode. Place this line of code just below the function we just made. This code tells WordPress that whenever the word foo comes up in the form of a shortcode it should replace it with the data returned from the function sc_foo.

add_shortcode('foo', 'sc_foo');

Now that we have this in place, let’s try it out shall we? Create a new post and type this inside the content text field:

 I did it! Now raise the [foo]...

Now you can preview the post to see what it looks like. Now it should say I did it! Now raise the bar… If it does, it works great. If it did not work, make sure your installation of WordPress is up to date. (Shortcodes has been available in WordPress since version 2.5.1)

Let’s raise the bar

The previous example was pretty straight forward, a simple function called from a simple shortcode. We could make the function more complex to return something more useful than bar, the sky is the limit for what we can make of this, if you want you can make shortcodes to display a gallery of images, calculate something, display a graph, or just a simple advertisement.

But there is much more to this API than displaying the output of simple functions, you can also pass arguments to the functions, and make the function wrap elements around some content text by using opening and closing tags.

How to handle arguments

You can set attributes inside the shortcode like this:

[banana color="yellow"]

The attribute color now has the value of “yellow” and this will be sent as an argument to the function through the associative array $atts. Let’s see how we can access this atribute in our function.

function sc_banana($atts) {
    return "The banana is {$atts['color']}";
}
add_shortcode('banana', 'sc_banana');

This would return The banana is yellow, which they usually are if they have not been lying on the kitchen counter for weeks. So why should we have to define the color of the banana if it’s yellow, can’t we set the default color to yellow and define the color if it’s not yellow? Sure.

function sc_banana($atts) {
    extract( shortcode_atts( array(
        'color' => 'yellow'
	), $atts ) );
    return "The banana is {$color}";
}

[adsense-banner]

Now we have defined the default color to be yellow, if it’s set in the attributes then it will be overwritten with another color, if the attribute is left out it will still be yellow. The extract function will extract the attribute name from the array and set it to a variable

[banana] -> The banana is yellow
[banana color="brown"] -> The banana is brown

Wrapping around some content text

Now let’s write a function that wrap some text into a box for us, let’s call it something sketchy as coolbox, notice that we now will add the argument $content to our function.

function sc_coolbox($atts, $content) {
    extract( shortcode_atts( array(
        'class' => 'coolbox',
        'float' => 'left'
        ), $atts ) );
    return '
'.$content.'
';
}
add_shortcode('coolbox', 'sc_coolbox');

This function will wrap the text into a div with the default class of coolbox

[coolbox]This text will be wrapped into a div with the class coolbox,
the box will have a default floating of left[/coolbox]

We can also give our box a custom class, or float it left and right.

[coolbox class="coolbox-blue" float="right"]This text will be wrapped
into a blue div with right floating applied to it[/coolbox]

Note: If you change theme you would have to update your functions.php file in your new theme folder with this code.