How To: Create a WordPress Shortcode

by

A WordPress Shortcode is a shortcut to allowing the authors to execute code in different areas of the website without having to write a single line of code. The shortcodes were originally introduces in version 2.5 of WordPress and they evolved a lot ever since.

There are a few built in shortcodes that come with the WordPress base install:

[audio]
[caption]
[embed]
[gallery]
[playlist]
[video]

Then there are a lot of others that are created by WordPress developers. This is where things become interesting!

For creating a shortcode, you have to use the so called Shortcode API. The shortcode API allows 2 main types of shortcodes: self-closing such as:

[my_shortcode]

or enclosing such as:

[my_shortcode] ... other content ... [/my_shortcode]

The Shortcode API also supports shortcodes with attributes. A good example of such a shortcode is:

[my_shortcode attribute1="value1" attribute2="value2"]

You can use attributes in both self-closing and enclosing shortcodes.

Giving the Shortcode a viable tag

Whenever you create a shortcode you must make sure that the shortcode name is correct and that it won’t cause issues to the WordPress parser.

The shortcode names should only be made of lowercase letters, numbers or underscores.

Using hyphens in the shortcode name might create unexpected results because the WordPress parser has problems when it comes to this.

For example the following might make WordPress ignore the -code part of the second shortcode and execute [short] twice.

[short]
[short-code]

To avoid this, make sure you use _ as separator in your shortcodes.

Creating a Basic WordPress Shortcode

For creating a shortcode we must use the add_shortcode function in the Shortcode API. This function takes 2 parameters: the shortcode name and the callback function.

NOTE: you should always prefix the shortcode names with a personalized string to make sure it will not conflict with other plugins or theme shortcodes. For example, our shortcode prefix is my_

add_shortcode( 'my_shortcode', 'my_callback' );

The callback function can take up to 3 parameters, all being optional.

For displaying the content it must return a string value. As a result, the string that is returned will replace the shortcode tag in the post body.

NOTE: Using echo or any other direct output function will lead to unexpected results ( like displaying the content outside the <html> tag )

NOTE: Multiple shortcodes may reference the same callback function

function my_callback() {
    return 'My Shortcode Text Content';
}

WordPress Shortcode With Attributes

Using attributes can easily extend the functionality of the shortcode by giving the author the means of manipulating the output by using the same shortcode with different attributes. In other words, instead of adding multiple similar shortcodes that do almost the same thing, you can have only one shortcode with attributes.

To set the default attribute values and to remove the unsupported attributes, you should use the shortcode_atts() function which does it all.

For instance, a callback for a shortcode with 2 attributes: ‘foo’ and ‘bar’ which returns the 2 attributes values joined by a ‘ – ‘ would look like this:

function my_callback( $atts ) {
    $atts = shortcode_atts(    array( 
        'foo' => 'default foo',
        'bar' => 'default bar'
    ), $atts, 'my_shortcode' );

    return $atts['foo'] . ' - ' . $atts['bar'];
}

add_shortcode( 'my_shortcode', 'my_callback' );

Therefore, using the shortcode like this: 

[my_shortcode]

Will output:

default foo - default bar

Likewise, using it like this:

[my_shortcode foo="custom shortcode" bar="with attributes"]

Outputs the following:

custom shortcode - attributes

A few things that you should be aware of:

  • You should always use lower-case only attribute names.
  • A user can add whatever attribute names and values he wants to the shortcode. Similarly, he can choose to use no attributes at all even if the shortcode needs some attributes for working correctly. Therefore, you should always use shortcode_atts() for handling valid and default attribute names

Build an Enclosing WordPress Shortcode

The most noteworthy difference between enclosing and self-closing shortcodes is that the 2nd parameter of the callback function, $content, can have a value different than null.

We can easily demonstrate the functionality by building a basic self-closing shortcode:

function my_callback( $atts, $content = null ) {
    
    return '<span class="my-shortcode-content">' . $content . '</span>';
}
add_shortcode( 'my_shortcode', 'my_callback' );

As a result, using the shortcode like this:

[my_shortcode]My awesome content is here[/my_shortcode]

Will output the following:

<span class="my-shortcode-content">My awesome content is here</span>

Another nice featured of the enclosing shortcode is that it supports raw HTML in the $content variable.

For example:

[my_shortcode]<a href="https://my-url.com">My Link Anchor</a>[/my_shortcode]

Will output:

<span class="my-shortcode-content">
    <a href="https://my-url.com">My Link Anchor</a>
</span>

Adding Shortcodes to the Shortcode content

There will be cases when you will need to wrap shortcodes inside other shortcodes.

Let’s take the following example. First, we create 2 basic shortcodes. One enclosing and one self-closing.

function my_enclosing_callback( $atts, $content = null ) {
    
    return '<span class="my-shortcode-content">' . $content . '</span>';
}
add_shortcode( 'my_enclosing_shortcode', 'my_enclosing_callback' );

function my_callback() {
    return 'My Shortcode Text Content';
}
add_shortcode( 'my_shortcode', 'my_callback' );

Then, we can wrap my_shortcode inside the content of my_enclosing_shortcode

[my_enclosing_shortcode][my_shortcode][/my_enclosing_shortcode]

This will generate the following response:

<span class="my-shortcode-content">
    [my_shortcode]
</span>

For parsing the enclosed shortcode, we have to update the callback function to include the do_shortcode() function, like this:

function my_enclosing_callback( $atts, $content = null ) {
    
    return '<span class="my-shortcode-content">' . do_shortcode( $content ) . '</span>';
}
add_shortcode( 'my_enclosing_shortcode', 'my_enclosing_callback' );

After doing this change, the previous shortcode output changes to:

<span class="my-shortcode-content">
    My Shortcode Text Content
</span>

NOTE: nesting shortcodes of the same type will fail:

[my_enclosing_shortcode] the [my_enclosing_shortcode] shortcode output [/my_enclosing_shortcode]

Conclusion

Using shortcodes makes the editor’s life very easy. It can also aid the developers by making custom dynamic content easy to manage.

This article should give you a starting point into the WordPress Shortcode world.

Good luck in building your own shortcodes.

In case you have any questions regarding shortcodes, don’t hesitate to leave a message in the comment section below.

Leave a Comment