Shortcode Fundamentals (Part 3)

by on February 11, 2011

In Part 2, we discussed the four types of shortcodes, “Basic Style, sans attribute”, “Basic Style, one or more attributes”, “BB Code Style, sans attribute”, and “BB Code Style, one or more attributes”.

We also created a simple basic style shortcode macro that didn't require any parameters. You can access the linked table of contents for the entire series below.

Table of Contents for this Tutorial
  1. Shortcode Fundamentals (Part 1)
    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)  (you are here)
    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
Let's Create a Single-Parameter Basic Style Shortcode

As mentioned earlier, 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(). Here's the code for this little gem.

Code: PHP (plus WordPress)Shortcode: php_lookup

1
2
3
4
5
6
7
8
9
10
11
12
13
add_shortcode('php_lookup', 'php_lookup_shortcode_handler');
 
function php_lookup_shortcode_handler($atts)
{
    $keyword = $atts['0'];
 
    $keyword_text = $keyword;
    $keyword = str_replace('(', '', $keyword);
    $keyword = str_replace(')', '', $keyword);
 
    $output = '<a href="http://www.php.net/' . $keyword . '" target="_blank">' . $keyword_text . '</a>';
    return $output;
}

You can use it to automatically create a convenient PHP lookup link for your visitors. It works with any keyword in the language.

Notice that we're only processing the single parameter. Because of this, you do not need to enter an attribute name when using the shortcode. In fact, there is deliberately no provision to handle an attribute name in this example. It makes using the macro quick and simple.

On line numbers 7-9, we filter out the () so that you can display them in your post and still have the lookup functional.

Here's a very similar shortcode for looking up WordPress core functions.

Code: PHP (plus WordPress)Shortcode: wp_lookup

1
2
3
4
5
6
7
8
9
10
11
12
13
add_shortcode('wp_lookup', 'wp_lookup_shortcode_handler');
 
function wp_lookup_shortcode_handler($atts)
{
    $keyword = $atts[0];
 
    $keyword_text = $keyword;
    $keyword = str_replace('(', '', $keyword);
    $keyword = str_replace(')', '', $keyword);
 
    $output = '<a href="http://codex.wordpress.org/Function_Reference/' . $keyword . '" target="_blank">' . $keyword_text . '</a>';
    return $output;
}
Let's Create a Multi-Parameter Basic Style Shortcode

Next, we'll construct a shortcode with two (optional) attributes that displays a Log In / Log Out link … contingent upon the current status. You might want to use this in a sidebar text widget.

The full usage syntax is: [loginout login_msg='Log In Now' logout_msg='Log Out Now']. Because we set default values, you can simply use it like this: [loginout].

Code: PHP (plus WordPress)Shortcode: loginout

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
add_shortcode('loginout', 'loginout_shortcode_handler');
 
function loginout_shortcode_handler($atts)
{
    $parms = shortcode_atts(array('login_msg' => 'Log In', 'logout_msg' => 'Log Out',), $atts);
 
    $login_msg = $parms['login_msg'];
    $logout_msg = $parms['logout_msg'];
 
    // from includes/general-template.php, wp_loginout()
    if (!is_user_logged_in())
    {
        $output = '<a href="' . esc_url(wp_login_url()) . '">' . $login_msg . '</a>';
    }
    else
    {
        $output = '<a href="' . esc_url(wp_logout_url()) . '">' . $logout_msg . '</a>';
    }
 
    return ($output);
}

The code in this example is a little more complex. This is because it handles attributes and because it uses a conditional based on the WP function is_user_logged_in().

A key function here is line number 5 which uses the WP function shortcode_atts(). This one extracts parameters from attributes the end-user specified OR uses the defaults in our array. Notice how we not only indicate the attribute names, but we also include their default values.

Line numbers 7 and 8 set our local variables from the returned array. For the sake of simplicity, I prefer to name my variables the same as the attributes. You may want utilize this naming convention too.

Let's Create a BB-Code-Style Shortcode

Now, we'll construct a very basic shortcode that modifies the content between the tags of a bb-code-style shortcode. This one isn't particularly useful, but it does demonstrate the feature. It simply outputs the original content as bold and blue in a large font size.

This usage syntax is: [big_bold_blue]This is big, bold, blue text.[/big_bold_blue].

Code: PHP (plus WordPress)Shortcode: big_bold_blue

1
2
3
4
5
6
7
8
9
10
add_shortcode('big_bold_blue', 'big_bold_blue_shortcode_handler');
 
function big_bold_blue_shortcode_handler($atts, $content=null)
{
    $output = '<span style="font-size:20px; color:#000080; font-weight:bold;">';
    $output .= $content;
    $output .= '</span>';
 
    return $output;
}

Here's an example usage:
This is big, bold, blue text.

That's it for our fundamentals of shortcodes. In future articles, we'll construct many shortcodes. Most of these will offer robust capabilities.

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

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

Comments

Share Your Thoughts  3 Responses to “Shortcode Fundamentals (Part 3)”
  1. 1
    XLR8 says:

    This was a thorough tutorial about building shortcodes.

  2. 2
    Eddie B says:

    I’m ready to give it go.

  3. 3

    It is like you understand my thoughts! Material recognize a great deal about it, such as you had written a e-book within it or anything. I have faith that you may can utilize quite a few % to operate a vehicle the material dwelling a lttle bit, nevertheless apart from that, this is exceptional website. An excellent read. I am going to surely return.

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.