Shortcode Fundamentals (Part 1)

by on February 9, 2011

WordPress shortcodes are a feature that allows you to embed macros in your posts and pages. They convert short textual content into other content before it's presented in the browser.

In other words, the shortcode is replaced by more extensive content for those who visit your blog. The term itself is probably a contraction of shortcut pseudo-code. WordPress began offering this powerful feature with the 2.5 release in the spring of 2008.

You can access the linked table of contents for the entire series below.

Some shortcodes (a single word and maybe a few attributes) display: image galleries, photo slideshows, mp3 audio players, google maps, user polls … and much more. Shortcodes do the same work as lightweight plug-ins. However, there is no admin page on the dashboard for shortcodes. Many themes and plug-ins come complete with their own specific, feature-rich shortcodes.

This substitution can be as simple as displaying your address by merely typing a code like this: [show_my_address]. But, the extended usefulness of shortcodes is exhibited when they harness powerful functions to collect data and/or perform data manipulations for the output replacement.

Shortcodes save you time. And, they allow you to offer features to other editors of your site outside the realm of plug-ins. As your library of shortcodes expands, it will be almost like having an added language in your arsenal.

Shortcodes extend the available feature set of blog writing. Once installed, you can offer myriad advanced capabilities (for yourself and other post editors) with just the basic Dashboard Editor. You don't have to resort to granting direct PHP access.

Also, your WP editor must be in HTML mode when you SAVE a post with shortcodes in it. Otherwise, the Visual Editor will completely IGNORE the macro. In fact, although the Visual Editor is tempting to use, it can severely dismantle some of the cool capabilities of WordPress.

Table of Contents for this Tutorial
  1. Shortcode Fundamentals (Part 1)  (you are here)
    Shortcode Preliminaries · How to List All Available Shortcodes
  2. Shortcode Fundamentals (Part 2)
    Basic Style Shortcodes · BB Code Style Shortcodes ·
    Let's Create a No-Parameter Basic Style Shortcode
  3. Shortcode Fundamentals (Part 3)
    Let's Create a Single-Parameter Basic Style Shortcode ·
    Let's Create a Multi-Parameter Basic Style Shortcode ·
    Let's Create a BB-Code-Style Shortcode

Before we get into the basics of shortcode creation, let's take care of a few preliminaries.

Shortcode Preliminaries

By default, you can not include the shortcode feature in text widgets. Let's fix that first. Put the following code in your theme's functions.php file. Some theme's already have it. But, there is no problem with duplication.

Code: PHP (plus WordPress)

add_filter('widget_text', 'do_shortcode');

Interestingly, WordPress includes the following line in includes/shortcodes.php to allow their use in regular content.

Code: PHP (plus WordPress)

add_filter('the_content', 'do_shortcode', 11); // AFTER wpautop()

And, if you want to call your shortcodes from PHP, here's the code to accomplish it.

Code: PHP (plus WordPress)

echo do_shortcode($content);
// $content should be the exact shortcode text

Unfortunately, shortcodes became very popular before the WordPress developers incorporated a methodology to track and encapsulate them … as with plug-ins. So … the only way to know what a shortcode does (without examining the PHP source code) is to rely on the author to provide that information.

Shortcodes, however, can be installed just like plugins (with the correct header info in the file).

How to List All Available Shortcodes

How do you know what shortcodes you have access to? Well … there's no built-in function for that either. But, we'll create a shortcode that lists all of your active shortcodes. It's only a list of the names (followed by the functions they call). Again, you have to rely on the author of the shortcode for usage instructions.

When you use our new simple shortcode, [wcs_list_all_shortcodes], in a post or page, you'll get an output that looks similar to this:

Current Shortcode Count = 78

  • album (show_album)
  • bloginfo (blog_info_shortcode_handler)
  • gallery (gallery_shortcode)
  • ngg-plus (ngg_plus_shortcode_handler)
  • ngg-simple-slide (ngg_simple_slide_shortcode_handler)
  • nggallery (show_gallery)
  • wcs_link (wcs_link_shortcode_handler)
  • wcs_list_all_shortcodes (wcs_list_all_shortcodes_shortcode_handler)
  • wcs_syntax (wcs_syntax_shortcode_handler)


We created a function named wcs_list_all_shortcodes_func() that does the lion's share of the work. You can actually call this function in your PHP code, if you want. Use the echo() command to output the resulting string.

Then, we constructed a quick shortcode handler, wcs_list_all_shortcodes_shortcode_handler, which calls our new workhorse function. And finally, we implement the shortcode functionality by using WordPress's add_shortcode() function.

Our new shortcode features four attributes. before_line and after_line are the text/html inserted for individual output lines. And, before_content and after_content are the text/html inserted before/after the entire content block. We used defaults for each of these attributes. So … you only need to use them if you want a different output appearance.

Here's the entire source code. To use it, put it in your theme's functions.php file.

Code: PHP (plus WordPress)Shortcode: wcs_list_all_shortcodes

1
2
3
4
5
6
7
8
9
10
11
12
13
add_shortcode('wcs_list_all_shortcodes', 'wcs_list_all_shortcodes_shortcode_handler');
 
function wcs_list_all_shortcodes_shortcode_handler($atts)
{
    $parms = shortcode_atts(array('before_line' => '<li>', 'after_line' => '</li>', 'before_content' => '<ul>', 'after_content' => '</ul>'), $atts);
 
    $before_line = $parms['before_line'];
    $after_line = $parms['after_line'];
    $before_content = $parms['before_content'];
    $after_content = $parms['after_content'];
 
    return wcs_list_all_shortcodes_func($before_line, $after_line, $before_content, $after_content);
}

And, here's the workhorse function called by the shortcode:

Code: PHP (plus WordPress)Function: wcs_list_all_shortcodes_func

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
function wcs_list_all_shortcodes_func($before_line='<li>', $after_line='</li>', $before_content='<ul>', $after_content='</ul>')
{
    // output line format:
    // shortcode_name (shortcode_function_name)
 
    // init
    global $shortcode_tags;
    $sc_list = array();
 
    // get the list into an array
    foreach ($shortcode_tags as $key => $val)
    {
        $sc_name = $key;
        if (is_array($val))
        {
            $sc_name .= ' (' . $val['1'] . ')';
        }
        else
        {
            $sc_name .= ' (' . $val . ')';
        }
        $sc_list[] = $sc_name;
    }
 
    // sort it
    sort($sc_list);
 
    // now, process for output
    $output = '<b>Current Shortcode Count = ' . count($sc_list) . '</b><br/>';
    $output .= $before_content;
    foreach ($sc_list as $item)
    {
        $output .= $before_line . $item . $after_line;
    }
    $output .= $after_content;
 
    return $output;
}

Part two of this post is here.

Share This Article: “Shortcode Fundamentals (Part 1)”

(Also Available: Press CTRL+D to Bookmark this Page)

Comments

Share Your Thoughts  2 Responses to “Shortcode Fundamentals (Part 1)”
  1. 1
    Zack S says:

    Between this shortcodes tut and your newer plugin tut, I am finally ready to kick my development efforts up a notch.

  2. 2

Share Your Thoughts

(Some editor features are restricted unless you're logged in.)

(When replying to a specific comment, your browser may require Shift+Enter instead of just Enter.)


(get a gravatar)


Notify me of followup comments via e-mail. You can also subscribe without commenting.