Understand WordPress Shortcode API in 2 easy steps

Examples

/*
 * Example 1: Simple shortcode
 */
[testimonials]

/*
 * Example 2: Shortcode with parameters
 */
[testimonials items = '5' show_author = false show_date = 'yes']

/*
 * Example 3: Shortcode with opening and closing tag
 */
[testimonial] some content (html/text) in between (optional) [/testimonial]

Steps to create shortcodes using WordPress Shortcode API

• Step 1: register shortcode.

add_shortcode( 'shortcode_name', 'shortcode_callback' );

Best practice notes:
1. use lowercase letters for shortcode names.
2. use underscores for separating shortcode name (e.g., latest_posts)  

• Step 2: handle the callback function
  • This function will handle the functionality of your shortcode
  • It accepts 3 parameters.
    • $atts: key value pair (e.g., show_content = true)
    • $content: html or normal text between opening and closing shortcode tag
    • $tag: the shortcode tag. useful for shared callback functions

function shortcode_callback( $atts, $content = NULL ){
    // you must output the response instead of echoing.   
}

Handling shortcode attributes ($atts)

• You pass values to a shortcode in the form

[testimonials items='5' show_author=false show_date='yes']

• These attributes are converted to an associative array (attribute name as key and value as value).

Array(
    [items] => 5
    [show_author] => false
    [show_date] => yes   
)

Note/Tip: the attribute names are always converted to lowercase before they are processed. So, its always good practice to use lowercase for attribute names. 

• You can notice here, a user using the shortcode can pass as many arguments as possible. So, its up to developer on which arguments to process. For this exact reason, we have a function available to normalize the $atts array; shortcode_atts().

$required_attributes = shortcode_atts( $default_array, $atts );

// example: let's say your shortcode only needs 3 parameters (e.g., items, show_author, show_date). Then you can set $default_array like:

$default_array = [ 'items' => 5, 'show_author' => true, 'show_date' => true ];

// here we are providing default values to the attributes as well (in case user forgets to pass them).

// now let's consider a scenario where user passes more than required attributes and misses few attributes as well

[testimonials show_author=false show_date=false bad_attribute='nonsense value]

// here, we are missing an attribute 'items', and we are also passing an attribute that is not required i.e., 'bad_attribute'. 

// the shortcode_atts() function will output:

Array
(
    [items] => 5,
    [show_author] => false,
    [show_date] => false
)

// explanation: shortcode_atts() function first removed the unnecessary attribute i.e., bad_attribute, then used the default value for missing attribute i.e., items = 5, and finally override the values for passed attributes.

Note: when passing attribute values, wrap strings in quotes and don't use quotes for numbers and booleans.
e.g.,
items=10
show_author=false
show_date=false

Handling $content

• You can pass content (html or plain text) to shortcode handler by enclosing the content in opening and closing shortcode tag.

[shortcode_name] <a href="#">Link</a> [/shortcode_name]

// this will output Link in the browser. If the shortcode should not permit raw HTML in its output, it should use an escaping or filtering function to deal with it before returning the result. e.g., esc_html()

Handling output

• Remember to return the output instead of echoing the result.
• If the shortcode produces lots of html, then use:

function shortcode_callback( $atts, $content = NULL ){
    $atts = shortcode_atts( $defaults, $atts );
    ob_start();
    ?>
        <!-- html content here ... -->
        <div>
            .......
        </div>
    <?php
    return ob_get_clean();
}

• If you want to allow users to use shortcode in its content (opening and closing shortcode tag) then you can do so by:

add_shortcode( 'shortcode_name', 'shortcode_callback' );
function shortcode_callback( $atts, $content = NULL ){
    ob_start();
    // some html here
    do_shortcode( $content );
    // some html here
    return ob_get_clean();
}

// now you can call another shortcode within the content.
[shortcode_name] [another_sc] [/shortcode_name]

Using shortcodes

• In a content i.e., in WYSIWYG editor:

[shortcode_name]

• In a page template

echo do_shortcode( "[shortcode_name]" );

Shortcode functions

• remove_shortcode( ‘shortcode_name’ ): removes the given shortcode

Reference: WordPress Shortcode API