Introduced in WordPress 2.5 was a new Shortcode API. Shortcodes are easy-to-remember tags that users place in posts, to be replaced with something else by a plugin. Shortcodes should be used when you want the user to be able to add something to their post that will be handled by your plugin. Shortcodes look like: [shortcode].

Shortcodes can exist in multiple ways. The first is a standalone: [shortcode]. The second has attributes: [shortcode link='true']. The third (which can also intermix with the second) is wrapped around something: [shortcode]Lorem ipsum dolar…[/shortcode]. In the first case, the shortcode would be simply replaced with something else. In the second case, the attributes would be returned to the plugin, and they can be used to determine what to replace it with. In the third case, the contained content would be returned to the plugin, which would then (probably) factor that into its output.

The shortcode API works much the same way as other WordPress APIs work. You declare the shortcode and specify a function to handle it’s processing. The processing function should return back what the shortcode will be replaced with.

We’re going to look at an example of a shortcode that has attributes and contains contents.

[code='php']add_shortcode('revision', 'revision_shortcode');[/code]

We start out by declaring the shortcode. The first parameter is the name of the shortcode, while the second is the function that will process it.

[code='php']function revision_shortcode( $attributes, $content = null, $shortcode_name ) {
$default_attributes = array('old' => FALSE);
$atts = shortcode_atts( $default_attributes, $attributes );
$class = 'revision';
if ( $atts['old'] == TRUE ) {
$class .= ' revision-old';
}
if ( !is_null($content) ) {
return '

';
}
else {
return '[revision]';
}
}[/code]

Next we have our shortcode processing function. Three parameters are passed to this function: any attributes specified by the user, any containing content and the name of the shortcode (the last one is only since WordPress 2.7). Within this function, we list the defaults for our shortcode’s attributes, and give that and the user-specified attributes to a function called shortcode_atts(). This function will process the two parameters given and returns an associative array of the final attributes (if a user doesn’t specify an attribute, this function will sub in the default). We then process our attributes for what they change in the final output. Finally, we check if their is any content, if there is, we return what will be replaced with, if there isn’t, (in this case) we just return the shortcode back to it (not ideal, you may want to just return a blank string back).

There you have it, a shortcode. You can remove shortcodes by using the remove_shortcode() function and specifying the name of the shortcode you want to remove.