WordPress Shortcodes: an Introduction

Introduced in version 2.5, shortcodes are one of the most useful and powerful features for WordPress developers.
When you insert a shortcode in the content of a post or page, it will automatically be replaced with a piece of content generated by the attached function. One could think of it like a sort of “macro”.

Basic example

Let’s create a shortcode to display a banner ad in the body of your posts.
This will come handy for several reasons:
– You won’t have to copy/paste your ad’s code in every post you make
– You can choose to add it wherever you want within your content
– If at some point you want to change the ad’s code, you won’t have to go through every post to edit it.

function my_ad_shortcode() {
	$output = '<div class="banner-ad">
	<a href="http://the_ad_link/">
	<img alt="" src="http://the_banner.gif">
	</a></div>';
	return $output;
}
add_shortcode('my-ad', 'my_ad_shortcode');

Add this code in your child theme’s function.php (or in a plugin) and you have just created this shortcode on your site.
Now when you put [my-ad] in your content, it will output the banner.

Of course shortcodes are way more than this, you can basically process anything with php before “returning” the output, and also pass some attributes and content to your shortcode.
Let’s look at these possibilities.

Shortcode with attributes

Let’s improve the previous shortcode to allow different ads size.

function my_ad_shortcode($atts) {
  extract(shortcode_atts(array(
    'size' => '250x250',
    'link' => 'http://the_ad_link/'
  ), $atts));

  switch($size):
    case '250x250':
      $banner = "http://my_250x250_banner.gif";
      break;
    case '300x250':
      $banner = "http://my_300x250_banner.gif";
      break;
    endswitch;

  $output = '<div class="banner-ad">';
  $output .= '<a href="'.$link.'">';
  $output .= '<img alt="" src="'.$banner.'" />';
  $output .= '</a>';
  $output .= '</div>';

  return $output;
}
add_shortcode('my-ad', 'my_ad_shortcode');

Now our shortcode has two available attributes: “size”, and “link”.
Note that our function sets default values in case the shortcode is used without passing values to these attributes.
You can now use it in your content this way:

[my-ad size="300x250" link="http://the_banner_link/"]

Embeding shortcodes

You can also create “embeding” shortcodes and wrap some content inside of them, so it can be used like so:

[myshortcode] some content here [/myshortcode]

The PHP source looks like this:

function my_shortcode($atts, $content = NULL) {
  $output = $content;
  return $output;
}
add_shortcode('myshortcode', 'my_shortcode');

This example shortcode does nothing except for displaying the embedded content, which actually is not very useful, but hopefully you get the idea!

Allowing shortcodes outside of post and page content

By default, shortcodes are only available in the content of post and pages, and ignored everywhere else. But you can easily make them available to use in text widgets, in excerpts, in comments etc. with the following:

add_filter( 'widget_text', 'do_shortcode' ); // Allow shortcodes in text widgets
add_filter( 'the_excerpt', 'do_shortcode' ); // Allow shortcodes in the excerpts
add_filter( 'comment_text', 'do_shortcode' ); // Allow shortcodes in comments

You can also use shortcodes directly in your theme’s templates, using the do_shortcode() function:

do_shortcode('[shortcode]');

This concludes this introduction to shortcodes, feel free to ask question in the comments below, and stay tuned for more!

Share the love!