The WordPress Shortcode API allows you to render template blocks by simply calling the shortcode in a post or page. Template blocks can be a part of a theme or a plugin, but may be included by entering a shortcode for the template when creating a post/page in wp-admin, allowing users to easily include content.

Basic Shortcode Usage

To create a shortcode, start by creating a function that will return the content you would like to display when the shortcode is used. The function should take one argument, $atts. It is important to note that the function returns the content, it does not print it to the screen. In this example we will display an alert box that says “Attention!” when the shortcode is called.

/**
 * render alert box
 * [js_alert_box]
 *
 * @author  Joe Sexton <joe@webtipblog.com>
 * @param   array $atts
 * @return  string
 */
function js_alert_box_function( $atts ) {

    $output = '<div class="alert">Attention!</div>';

    return $output;
}

 

The next step is to register the shortcode with WordPress so that it can be used. A shortcode looks like this to a user: [shortcode] with the name of the shortcode surrounded in brackets. To register the shortcode WordPress offers the add_shortcode() function. The first argument is the name of the shortcode and the second is the callback function. To register the alert box shortcode using add_shortcode() simply add this line to functions.php or your plugin file:

add_shortcode( 'js_alert_box', 'js_alert_box_function' );

 

There are two ways to call the newly created shortcode. A user can use the shortcode syntax in wp-admin in the post or page editor, to call the alert box it would look like this:

[js_alert_box]

 

WordPress has a function called do_shortcode() which allows you to call the shortcode from a theme file programmatically. To render the alert box using do_shortcode() add this snippet to the theme file:

<?php echo do_shortcode('[js_alert_box]'); ?>

 

Adding [js_alert_box] to a post in wp-admin or using do_shortcode() will render the following element on the page:

<div class="alert">Attention!</div>

 

Adding Shortcode Parameters

It is possible to add parameters to the shortcode to allow a user to pass some input into the shortcode template. To do so, we can extract the shortcode attributes from the shortcode with shortcode_atts(). For example, let’s allow the user to render the alert box with an optional title and content by adding a few attributes to the shortcode. The js_alert_box_function() will now look like this:

/**
 * render alert box
 * [js_alert_box]
 *
 * @author  Joe Sexton <joe@webtipblog.com>
 * @param   array $atts
 * @return  string
 */
function js_alert_box_function( $atts ) {

    extract( shortcode_atts( array(
        'title'   => null,
        'content' => '',
    ), $atts ) );

    $output = '<div class="alert">';
    if ( !is_null( $title ) ) {
        $output .= '<h2>'.$title.'</h2>';
    }
    $output .= $content.'</div>';

    return $output;
}

 

The shortcode gets registered the same as before with add_shortcode(). The attributes are added to the shortcode very much like they would be added to an HTML element:

[js_alert_box title="Attention" content="Check out this alert box"]

 

Calling the shortcode with these attributes would render this content on the page:

<div class="alert">
<h2>Attention</h2>
Check out this alert box
</div>

 

Adding Shortcode Content

Shortcodes can be used like HTML tags to wrap content and pass the content to the shortcode. This allows a user to add more than a few words to the shortcode and use punctuation without escaping. To allow this, add a second argument to the alert box function called $content, which will be the content that is wrapped with the shortcode tags. It might be nice to use this to allow users to add content to the alert box in our example, this is what js_alert_box_function() would look like to add the content:

/**
 * render alert box
 * [js_alert_box]
 *
 * @author  Joe Sexton <joe@webtipblog.com>
 * @param   array $atts
 * @param   string $content
 * @return  string
 */
function js_alert_box_function( $atts, $content = null ) {

    extract( shortcode_atts( array(
        'title'   => null,
    ), $atts ) );

    $output = '<div class="alert">';
    if ( !is_null( $title ) ) {
        $output .= '<h2>'.$title.'</h2>';
    }
    $output .= $content.'</div>';

    return $output;
}

 

The shortcode gets registered normally using add_shortcode() and calling the shortcode with content would look like this:

[js_alert_box title="Attention"]Check out this alert box[/js_alert_box]

 

This will render the following on the page:

<div class="alert">
<h2>Attention</h2>
Check out this alert box
</div>

 

Separate Shortcode Template Files

If the shortcode will be returning more than a few lines of HTML it might be a good idea to use a separate template file for the shortcode template. Since the shortcode content is returned and not simply printed we need to do more than just require() the template file. By using output buffering the template file can be added as a separate file and its contents returned instead of printed. To add a separate template file for the alert box shortcode, update js_alert_box_function() to include output buffering:

/**
 * render alert box
 * [js_alert_box]
 *
 * @author  Joe Sexton <joe@webtipblog.com>
 * @param   array $atts
 * @param   string $content
 * @return  string
 */
function js_alert_box_function( $atts, $content = null ) {

    extract( shortcode_atts( array(
        'title'   => null,
    ), $atts ) );

    ob_start();
    require '/templates/alert_box_template.php';
    $output = ob_get_contents();
    ob_end_clean();

    return $output;
}

 

The template file can now be created like any other theme template file using the variables set as shortcode attributes.

<?php // /templates/alert_box_template.php ?>

<div class="alert">

    <?php if ( !is_null( $title ) ) : ?>
        <h2><?php echo $title; ?></h2>
    <?php endif; ?>

    <?php echo $content; ?>
</div>