Making Your First Shortcode Plugin in WordPress


Shortcodes are, as I said in my last post about them, a bit like magic. They’re a way that you can, with very little code or concern about complexity, include large collections of markup or even custom functionality into a post. And many many plugins already exist that use shortcodes in WordPress and make it easy to include specific features you might care about.

But sometimes, you may want some pretty specific markup in your WordPress blog that no one else has wanted before, or maybe even that no one else will ever want. That’s when it makes sense to move to a custom WordPress plugin for your shortcodes. Obviously we here are Press Up would love to help you put a custom WordPress shortcode plugin together, but we don’t believe that means we can’t teach you how to do it.

Diving into WordPress Shortcodes

This tutorial will take for granted that you know the basics of HTML, and that you’re familiar with PHP. There’s no need for super-deep knowledge, but you should have some sense what an array is in PHP and how to work with it. I’ve written a quick introduction to arrays in PHP that can help you with any gap. Because we’re aiming to demonstrate this concept at it’s simplest possible level, what our shortcode will do is wrap its contents in some rather basic HTML and allow us to do a bit with it. This is just the start of how you can use shortcodes though, so don’t worry that you can only use them for simple things.

Though the practical case for the shortcode may be dubious, but it gives you a good sense of how to work with shortcodes. So to make a shortcode plugin, you want to first make a WordPress plugin. If you’re not confident about that, I recommend you run through my “minimum viable WordPress plugin” post to get a skeleton in place and have a more thorough understanding of what a WordPress plugin is and how it works.

After you’ve created a basic doc block for your plugin in your PHP file (again, the tutorial I just mentioned will walk you through that process) we create a shortcode using a pretty simple WordPress hook. Like so:

add_shortcode('pullquote_shortcode', 'pqsc_process_shortcode');

The add_shortcode function takes two arguments, both are just a run of characters, called “strings” by programmers. The first is the shortcode name that you want people to be able to use in their post to get you shortcode. This can be just about whatever you want, but because of weird traits of shortcodes in WordPress I’d generally recommend that you keep your shortcodes to lowercase letter and underscores. Other things can work, but no need to chance it. The second part of the add_shortcode function call is the name of the function which will process the shortcode data and return the necessary data to WordPress. This name should be entered to be identical to the name of the function (were going to create in the next section).

The Actual Shortcode Function

The two non-negotiables of shortcodes are that you must use add_shortcode, and your function must return the content you want added to the post where the shortcode declaration was. Anything else is technically optional. That said, there are generally two parameters that your function should expect, and for completeness we’re going to use both of them in this tutorial. The first parameter is the attributes of the shortcode. WordPress with happily process these and hand them off to your function in an array, and you can accept them and incorporate them into the output of your function. The other parameter is the contents that (may be found) within your shortcode’s opening and closing brackets.

To add some clarity to the concept, an example of our shortcode in use:

[pullquote_shortcode class="alignright"]This is the text that should 
go inside my pullquote[/pullquote_shortcode] 

In our example, class is said to be an attribute of our shortcode. The contents of our short code are “This is the text that should be inside my pullquote”. By default WordPress will hand these — the attributes and contents — to the shortcode function as the first and second parameters. So here’s our example function:

function pqsc_process_shortcode( $attributes, $content = null ) {
	extract( shortcode_atts( array(
		'class' => ''
	), $attributes ) );

	return '<blockquote class="pullquote '.$class.'">'.$content.'</blockquote>';
}

As we discussed, the content will be whatever is between the opening and closing shortcode, and the attributes will be any variables set in the opening of the shortcode. Most of this is pretty straight forward, the return just sends back what we want to replace the shortcode with, we’re incorporating both the content that WordPress handed us and the attributes that it gave us in that return.

The thing here that can easily seem a little esoteric that that strange combination of the PHP functions extract() and the WordPress shortcode_atts() function. (I’m going to take it for granted that you have a basic understanding of arrays going forward from here; again this post about them can help if you don’t).

shortcode_atts() is a WordPress provided functions that simply combines a defaults array and the shortcode attributes array processed from the declaration. What this means is that if that if the array generated by our shortcode contains a class specified — my call above specifies the WordPress layout class “alignright” — that will be used. If not, the class from the defaults array — in our case an empty string here — will be used. For this example, the use of shortcode_atts might look a little silly because there is only one default, but for complex shortcodes that have tons of attributes that a user may or may not specify it’s vital. So the result of shortcode_atts is just an array, in our case the array would look like (using array shorthand available in PHP 5.4 and above): ['class' => 'alignright'].

extract() is a PHP function which essentially pops an array into local scope. It’s hardly necessary to do it, and in some contexts can be a bad idea, but essentially it’s really nice in this shortcode example. What this allows us to do is access the class that is set by our rectification of the shortcode call and the defaults as the variable $class, rather than something like $array['class']. As I said, it’s hardly necessary, and if you have a lot of variables in your local scope already it can be really hazardous, but here it’s nice.

So, you’ve done it. If you’ve been following along, you’ve just made you very first shortcode plugin. Once you understand it, it’s a stunningly simple process. Go forth and shortcode!

About David Hayes

David likes learning, solving hard problems, and teaching. He bikes a lot, and lives in (and loves) Colorado. You can find him on Twitter as @davidbhayes and check out his latest hobby-project, Quodid, a monument to his love for pithy bits of wisdom.

8 thoughts on “Making Your First Shortcode Plugin in WordPress

  1. Pingback: Guide to Making Your First Shortcode Plugin in WordPress | WPShout.com

  2. Pingback: Guide to Making Your First Shortcode Plugin in WordPress - WordPress News

  3. Pingback: Making jQuery Plugins into WordPress Plugins | WPShout.com

  4. Pingback: Using PHP Session Cookies in WordPress | WPShout

  5. Pingback: Using Cookies in WordPress, Part II: Cache-Busting with Ajax | WPShout

  6. Pingback: Using WP_Query Objects Without the Loop | WPShout

  7. Pingback: Using WP_Query Objects Without the Loop - The Amazing Host

Leave a Reply

Your email address will not be published. Required fields are marked *