Shortcodes with Parameters

Now that we know how to create a basic shortcode and how to use it as self-closing and enclosing, we will look at using parameters in shortcode [$tag] and handler function.

Shortcode [$tag] can accept parameters, known as attributes:

[wporg title="WordPress.org"]
Having fun with WordPress.org shortcodes.
[/wporg]

Shortcode handler function can accept 3 parameters:

• $atts – array – [$tag] attributes
• $content – string – post content
• $tag – string – the name of the [$tag] (i.e. the name of the shortcode)

function wporg_shortcode($atts = [], $content = null, $tag = '') {}

Parsing Attributes #Parsing Attributes

For the user, shortcodes are just strings with square brackets inside the post content. The user have no idea which attributes are available and what happens behind the scenes.

For plugin developers, there is no way to enforce a policy on the use of attributes. The user may include one attribute, two or none at all.

To gain control of how the shortcodes are used:

• Declare default parameters for the handler function
• Performing normalization of the key case for the attributes array with array_change_key_case()
• Parse attributes using shortcode_atts() providing default values array and user $atts
• Secure the output before returning it

Top ↑

Complete Example #Complete Example

Complete example using a basic shortcode structure, taking care of self-closing and enclosing scenarios, shortcodes within shortcodes and securing output.

A [wporg] shortcode that will accept a title and will display a box that we can style with CSS.

<?php
function wporg_shortcode($atts = [], $content = null, $tag = '')
{
    // normalize attribute keys, lowercase
    $atts = array_change_key_case((array)$atts, CASE_LOWER);

    // override default attributes with user attributes
    $wporg_atts = shortcode_atts([
                                     'title' => 'WordPress.org',
                                 ], $atts, $tag);

    // start output
    $o = '';

    // start box
    $o .= '<div class="wporg-box">';

    // title
    $o .= '<h2>' . esc_html__($wporg_atts['title'], 'wporg') . '</h2>';

    // enclosing tags
    if (!is_null($content)) {
        // secure output by executing the_content filter hook on $content
        $o .= apply_filters('the_content', $content);

        // run shortcode parser recursively
        $o .= do_shortcode($content);
    }

    // end box
    $o .= '</div>';

    // return output
    return $o;
}

function wporg_shortcodes_init()
{
    add_shortcode('wporg', 'wporg_shortcode');
}

add_action('init', 'wporg_shortcodes_init');