Welcome to our series on creating shortcodes using WordPress. This will be the first of many entries devoted solely to helping you learn to make powerful shortcodes (the right way).

In this first example, we’ll walk through the most basic shortcode possible. This shortcode will simply display a specific string of text whenever it is used.

What we’ll be creating

Here’s the final code for this demonstration:

/*
Plugin Name: Mastering Shortcodes
Plugin URI: http://realbigplugins.com
Description: This plugin creates a shortcode.
Version: 0.1
Author: Kyle
Author URI: http://kyleblog.net
License: GPL2
*/

function my_phone_number() {
 return '(123) 456-7890';
}

add_shortcode( 'phone', 'my_phone_number' );

Pretty simple right? And here’s a video which walks through the entire process for this first shortcode we’ll be making:

How it works

In this example, we’re creating a very simple WordPress plugin which includes three things:

1. The plugin header. This is simply a comment at the top of the main PHP file for the plugin which WordPress looks for. It identifies the file as a plugin and enables the plugin to be activated within WordPress.
2. A function declaration. This is where we define a new PHP function that will be globally accessible throughout the site’s codebase. This function must have a unique name. If another function exists in the entire codebase with the same name, the entire site will blow up. Well, not exactly but it will cause a fatal error and your site won’t load.
3. Use of the add_shortcode() function. This PHP function is included in WordPress core and accepts two parameters: the name of the new shortcode and the name of the function to be used.

What it does

When we use the add_shortcode() function, WordPress adds the new shortcode to the global variable $shortcode_tags. This contains all the registered shortcodes that WP looks for in the content of a post or page. Whenever a word or phrase wrapped in square brackets is encountered in the contents of a post, WordPress checks to see if that statement matches a shortcode contained in that global. If it doesn’t find anything, it just treats it like regular text and displays the square bracket statement like everything else.

But if it does find a shortcode which matches, the corresponding function (second value used in the add_shortcode() statement above) is executed. In this example, when WordPress encounters [phone] in the content of a post, it executes the my_phone_number() function. As defined in this plugin, that function simply returns a string which is just arbitrary text. Here we’ve defined that string to be a phone number.

Why is this even useful?

A valid question may be “why would I even bother to create such a simple shortcode?”. Certainly it is true that the true power of shortcodes is more fully demonstrated through the execution of more complicated elements such as forms, sliders, tabbed layouts and dynamic queries. However, I believe that shortcodes are uniquely useful even in cases such as this one.

Being able to make a string of text callable through the use of a short, memorable statement can be very practically useful. In fact, I’ve done this on several client projects. I’ve found that using a shortcode to output the string instead of just typing out the string itself has the following benefits:

• It becomes more memorable and easier for content creators. Maybe multiple people are writing content and frequently have to use something in their content like their email address, someone’s job title, a company’s tagline, a date, a company’s name, some name or statement that is hard to spell, a phone number, or many other simple things that someone would usually need to look up to make sure they’ve got it right.
• Maintains consistency. Since every instance of the shortcode outputs the same exact content, there is no risk of it being misspelled or used incorrectly somewhere.
• It can easily be modified globally. If the string for some reason needs to be different everywhere, all that is needed is a quick update to the above code and the entire site will reflect the change instantly. Also, it can be easily enhanced to be more functional. For example, building on the phone number example, it would not be complex (in fact we’ll cover it in a future lesson) to make which phone number is displayed be dynamic based on some factor such as time of day, day of week or whether a user is logged in or not. This does not require someone to scour the site and change each occurrence. Only a simple addition to the code above is needed.
• In a plugin, these benefits could be extended to other sites. Once this plugin has been created, it is easy to add the same plugin to other sites and extend the above benefits to them as well. Or in a multisite scenario, network activating or dropping in mu-plugins can empower all sub sites with this functionality instantly.

I hope you’ve found this tutorial to be useful. Please feel free to leave comments with questions or other input on this topic. I’ll be posting again soon with the next lesson which will add another shortcode to this plugin which will be slightly more complex.