In WordPress Shortcode Fundamentals (Part 1), we covered shortcode preliminaries. This included detailing their purpose, allowing shortcodes in text widgets, and listing all the installed shortcodes on a blog.
You can access the linked table of contents for the entire series below. Now, let’s look at some different types of shortcodes. There are essentially four types:
Basic Style Shortcodes
The ‘shortest’ shortcode is a single word. For example, [my_address] might display your name and contact info.
A step up in complexity is a shortcode that has only one attribute. With these, you don’t have to type the attribute name (this is a programmer-dependent option). BTW, the WordPress documentation doesn’t reveal this capability … I discovered by examining their parser’s source code.
For example, have you noticed the various links on this site to lookup PHP and WordPress functions? To accomplish this, I created a simple shortcode that has a syntax like this [php_lookup echo()]. This macro expands to a link that opens the PHP> site on that specific keyword’s description … echo(). We’ll reveal the shortcode for it later in this article.
Another variation of this type of shortcode is one that has more than one attribute. In this case, the attribute names must be used (in any sequence). The values for those attributes can be enclosed in single or double quotes. But, you only need to do this if the value contains white space.
Well designed shortcodes have default values for the various attributes, when applicable. With multiple attributes, the syntax might look like this:
. With this particular WP shortcode, both attributes are optional.
BB Code Style Shortcodes
You may be familar with BB Code. It’s origin can be traced back to the first online forums and bulletin boards. To allow visitors to enhance comments/posts without granting dangerous access to actual HTML tags, a substitution method was employed.
For example [b]my bold text[/b] was processed as <b>my bold text</b>. The output would look like this: my bold text. Although it is rather simple to filter HTML tags, this practice is still in widespread use.
Shortcodes employ this technique to allow the supporting PHP to perform options on the content between the tags. For example, [big_and_bold]my text here[/big_and_bold] might take the content between the bb-code-style tags and make it bold and larger than surrounding text.
This type of shortcode also offers the possibility of including attributes in the opening tag. However, this feature is rarely used.
Let’s Create a No-Parameter Basic Style Shortcode
Let’s create a simple macro to display your name and contact info. If you want to use this one, you will, of course, need to enter your own data. This one is as basic as shortcodes can be.
The first step is to write a PHP function to perform a task. Then, we write another function (a wrapper of sorts) that calls the workhorse function. Finally, we use add_shortcode() to make the shortcode available.
These three items should be saved in your theme’s functions.php file. Actually, there are more advanced methods. But for now, put the code there.
add_shortcode('wcs_my_address_macro', 'wcs_my_address_macro_shortcode_handler');
function wcs_my_address_macro_shortcode_handler($atts)
{
return wcs_my_address_macro_func();
}
function wcs_my_address_macro_func()
{
$output = 'My Name Here' . '';
$output .= '123 Some Street' . '';
$output .= 'My Town, SC 12345' . '';
$output .= '<a href="mailto:me@here.com">me@here.com</a>' . '';
return $output;
}
You’ll note my particular code styling here. For example, I prefer to name my function the same as the shortcode … adding ‘_func’ to the end. But, you can name your workhorse function whatever you like. In this example, replace the strings in lines 12-15 with your own information.
Also, note that my shortcode handler function is the name of the shortcode … adding ‘_shortcode_handler’ to the end. This is a very common practice and I highly recommend that you do it this way yourself.
In theory, you could include the workhorse functionality inside of your handler function. Here’s a basic rule of thumb. If you think that you might ever want to use your workhorse function in your own PHP code (outside the shortcode), make it a separate function. Otherwise, include it in the handler itself.
This is the shortest handler function possible. But, note that you must include the $atts variable (any name) as a parameter even though no parameters are used.
Finally, the WP function add_shortcode() takes two parameters. The first is the name that will invoke your shortcode in a post/page. The second is the name of the handler function.
From our example, [wcs_my_address_macro] output looks like this:
My Name Here
123 Some Street
My Town, Dhaka 12345
youremail@here.com
continue to reading more WordPress Shortcode Fundamentals (Part 3)
