Intro to WordPress Plugin Development: Shortcodes

We’ve been able to get quite a bit accomplished so far in the Intro to WordPress Plugin Development series. Next, we’ll be diving into creating our own custom shortcodes next.

What are WordPress shortcodes?

According to the WordPress codex, shortcodes were introduced to create macros to be used in a post’s content.

So, what does that mean? Basically, it lets you insert a small code into the content of your posts where a PHP function will be executed. Shortcodes can embed files or even output content.

A simple shortcode example

Let’s say we have a blog that occasionally writes sponsored posts. We want to be nice to our readers and let them know that the post is sponsored by using a consistent message. We don’t need this message on every post we write – just on the sponsored posts.

Our shortcode would look something like this:

<?php
function sd_sponsored_post_shortcode(){
	$message = 'We were compensated for writing this post. We only accept compensation for products and services we have used and trust.';
	return $message;
}
add_shortcode( 'sponsored_post', 'sd_sponsored_post_shortcode' );

It’s really simple. Any time you use the [sponsored_post] shortcode in a post, it will then display the message we wrote in the function above.

Allowing user input in the shortcode

Now, what if we wanted to include the sponsor’s name in the message? The way we wrote the shortcode’s function, it will only return the static message we coded into the function.

What we can do, is let the user of the shortcode provide us with that sponsor’s name in the shortcode they use by passing an attribute.

function sd_sponsored_post_shortcode( $atts ){
	$atts = shortcode_atts(
		array(
			'sponsor' => 'our sponsor'
		),
		$atts
	);
	$message = 'We would like to thank ' . $atts[ 'sponsor' ] . ' who compensated us for writing this post. We only accept compensation for products and services we have used and trust.';
	return $message;
}
add_shortcode( 'sponsored_post', 'sd_sponsored_post_shortcode' );

Now, we’ve added the $atts variable to the function. This allows the end user of our shortcode specify the sponsor’s name by adding the sponsor attribute like this [sponsored_post sponsor="Sponsor's Name"].

If they used the shortcode without specifying a sponsor’s name, we set the default to be “our sponsor”. So regardless of whether a sponsor’s name is used, or no sponsor is specified at all, the message will still make sense.

The shortcode with a sponsor will output like this ( [sponsored_post sponsor="Acme Co."] ):

We would like to thank Acme Co. who compensated us for writing this post. We only accept compensation for products and services we have used and trust.

The shortcode without a sponsor will output like this ( [sponsored_post] ):

We would like to thank our sponsor who compensated us for writing this post. We only accept compensation for products and services we have used and trust.

It is always a good practice to define default values for any attributes a user might pass through your shortcode. So, if we have several attributes, we would just add them to the array where we added the sponsor attribute.