An Introduction to WordPress Shortcodes

Shortcodes are WordPress‘ way of inserting content within a given post, page or custom post type. This content is often of a more dynamic nature. Take for instance, the gallery shortcode built into WP. Just pop

into any WordPress post and out pops a nice gallery of all images attached to that post. Awesome!

In this tutorial, we’ll cover the basics of creating your own shortcodes.

The first step is actually add the shortcode – that is, let WordPress know about it. We do this with a function called, conveniently, 

add_shortcode

I like to wrap the call to add_shortcode inside a function hooked into init. Why? Because WordPress loads in phases. Registering a shortcode on init ensures the entire WordPress enviroment is loaded (including the add_shortcode) function before doing anything.

<?php

add_action( ‘init’, ‘pmg_sctut_add_shortcodes’ );

function pmg_sctut_add_shortcodes()

{

add_shortcode( ‘post-link’, ‘pmg_sctut_shortcode_cb’ );

}

What happens when WordPress encounters a shortcode in post content is it looks for it in its array of registered shortcodes. If it finds it, it calls the callback function (registered with add_shortcode), which returns a value. WP then replaces the shortcode with that returned value.

The callback function is where the work happens. Our shortcode will insert a link to another post based on an id attribute.

Shortcode callbacks receive two arguments: attributes of the shortcode and the content. [shortcode-name these="are" attributes="yes"] this is content[/shortcode-name]. Content doens’t have to be used, so it’s best to give that function argument a default value. With that in mind, here’s the skeleton of our callback.

<?php

function pmg_sctut_shortcode_cb( $atts, $content = null )

{

// do stuff here

}

The attributes passed into a shortcode can be dangerous. And you also probably don’t want to have to call isset all the time to make sure certain attributes were included. Enter, shortcode_atts. It takes two arguments, the first is an array of allowed attribute array keys, and their default values. The second should be the array of atts passed into the shortcode callback function. shortcode_atts will check to see if the passed in attributes has a given key. If it does, that key’s value will be sent in the returned array. If the attributes array doesn’t a have a key, the default value will get returned.

Our call to shortcode_atts is wrapped in extract, a built in PHP function.

<?php

function pmg_sctut_shortcode_cb( $atts, $content = null )

{

extract( shortcode_atts(

array(

‘id’ => False

),

$atts

) );

}

Next up, we’ll check to see if we have our id attribute and get the post associated with it. Make sure the post is published, and then build our link.

<?php

function pmg_sctut_shortcode_cb( $atts, $content = null )

{

extract( shortcode_atts(

array(

‘id’ => False

),

$atts

) );

// no id?  bail

if( ! $id ) return ”;

// get the post we’re linking to

$tolink = get_post( absint( $id ) );

// not a published or we didn’t get a post, bail

if( ! $tolink || ‘publish’ != $tolink->post_status ) return ”;

$link = get_permalink( $tolink );

$title = $content ? $content : $tolink->post_title;

return sprintf(‘<a href=”%s”>%s</a>’, esc_url( $link ), esc_html( $title ) );

return sprintf(‘<a href=”%s”>%s</a>’, esc_url( $link ), esc_html( $title ) );

}

The only thing of note in the remainder of that function is the check to see if the $content variable actually contained a value. This is common: content is not required of a shortcode, so if you’re planning on using it, have a default or something else you can use.

Shortcodes are awesome. But they are not the solution for everything. For instance, you could use shortcodes to replace something like <div class="alert">Some message<div> with [error]some message[/error]. That shortcode looks suspiciously like HTML. If that’s the case, why not just learn HTML?

Shortcodes can also cause a lock in effect. Deactivate the plugin that adds them or change away from the theme that adds theme, and you now have ugly shortcodes in your content. Awesome. There’s not much that can be done about that, but it’s something to be aware of.