Creating shortcodes for use in wordpress themes is fairly straightforward. Shortcodes are written by providing a handler function. Shortcode handlers are broadly similar to WordPress filters: they accept parameters (attributes) and return a result (the shortcode output).

Shortcode names should be all lowercase and use all letters, but numbers and underscores should work fine too. Be wary of using hyphens (dashes), you’ll be better off not using them.

The add_shortcode function is used to register a shortcode handler. It takes two parameters: the shortcode name (the string used in a post body), and the callback function name.

Three parameters are passed to the shortcode callback function. You can choose to use any number of them including none of them.

$atts - an associative array of attributes, or an empty string if no attributes are given
$content - the enclosed content (if the shortcode is used in its enclosing form)
$tag - the shortcode tag, useful for shared callback functions

To register your own shortcodes you will need to place them inside your functions.php file inside your child theme (or if you have another file that has access to PHP you can use this also).

Remember to never edit a parent theme directly!

Defining the Shortcodes Callback Function

The functionality that a shortcode performs is defined inside the callback function.

The callback function returns a value and that value is what is displayed to the end user when generating their page/post. This returned value might just be a value wrapped in a container for styling, or it may be as complex as outputting a dynamic form element or slider.

The structure of a callback function in its simplest sense is just a function that returns a value:

//defines the callback function used for our shortcode (does nothing) function my_shortcode_callback_function(){ return; }

Shortcodes Arguments in the Callback Function

While shortcodes just need a callback function to operate; shortcodes can take arguments (options) that can be used to dynamically change how the shortcode functions.

There are three main arguments that can be passed into the function that displays the shortcode. These variables are all optional but are frequently used. These variables are $atts, $content and $name; they are called sequentially into the call back functions as such:

//defines the callback function used for our shortcode (does nothing). Takes in three arguments function my_shortcode_callback_function($atts, $content, $name){ return; }

$atts (the options)

The $attsvariable is an associative array of options or settings that you would like your shortcode to have access to.

Shortcodes will often provide the user with a series of settings which they can pass into the shortcode to give them the ability to alter the output.

For example, consider the inbuilt audio shortcode .

This shortcode (since WordPress 3.6) gives the user the ability to embed a HTML5 audio player into the page.

By default you can use the shortcode just as it is. However you can also customise its options by passing in arguments such as the following . This allows you to set the audio to pre-load as soon as the page loads, along with automatically triggering the audio (and once the audio is finished it will loop). These settings along with others can be customised by passing in values.

Let’s go through a basic example where we want a shortcode that takes in an option and outputs content conditionally based on its selection:

//based on the passed in profession, return a statement //Shortcodes functions and information function display_my_profession_callback($atts,$content,$tag){ //collect values, combining passed in values and defaults $values = shortcode_atts(array( 'profession_type' => 'other' ),$atts); //based on input determine what to return $output = ''; if($values['profession_type'] == 'developer'){ $output = 'You are an amazing developer!'; } else if($values['profession_type'] == 'designer'){ $output = 'You are an epic designer!'; } else if($values['profession_type'] == 'other'){ $output = 'You are a great person'; } else{ $output = 'I am not sure what you are'; } return $output; } add_shortcode('display_profession','display_my_profession_callback');

The first thing you will see is that we called a function named shortcode_atts(). This function is used to return an associative array of values for you to use. This function takes in your $atts variable and also defines nice default options for you to use (this takes the hassle out of merging arrays and controlling data yourself).

In our example $values will have access to one value called profession_type, however, if we defined more default values we could also access them.

The default value for profession_type is other. This value can be over-ridden in the shortcode itself by simply supplying a value, for example [display_profession type='designer']

Once we determine the value for profession_type we format a string and return it for display to the end user.

$content (the content)

The $content variable is used for enclosed shortcodes and this value represents any content that exists between the opening and closing tag of the shortcode.

For example, if you have a shortcode that makes selected text really small such as [small_text] This text will be small [/small_text]. The value of $content will be ‘This text will be small’. This variable gives the shortcode access to the content and it is how shortcodes directly apply styles and functionality to the selected areas.

Let’s look at a coding example to illustrate this.

We can create a shortcode that takes in its wrapped around content and formats it via a span tag:

//take the wrapped around content of the shortcode and style it function wrap_content_shortcode_callback($atts, $content, $tag){ $output = '<span style="font-size: 120%;">' . $content . '</span>'; return $output; } add_shortcode('wrap_shortcode','wrap_content_shortcode_callback');

The returned content will be styled differently, wrapped around by a span.

On a related note, if you are creating shortcodes that use the $content variable, you can also use thedo_shortcode($content) function. This function will take the content and run any other shortcodes inside of it. If you don’t include this and you wrap a shortcode inside another shortcode, the inner most shortcode will simply display text instead of being transformed.

$tag (the shortcode name)

The $tag variable contains the name of the shortcode itself. This is often used for shortcodes that share the same callback function.

When you define multiple shortcodes and use the same function to handle all of them you can use the $tagvariable to distinguish what shortcode is being called.

Let’s look at a practical example where a single callback function is used for two shortcodes:

//this callback function performs many actions depending on which shortcode ($tag) calls it function display_my_shortcode($atts, $content, $tag){ //if called from the 'my_primary_shortcode' shortcode if($tag == 'my_primary_shortcode'){ return 'This is the primary shortcode'; } //if called from the 'my_secondary_shortcode' shortcode else if($tag == 'my_secondary_shortcode'){ return 'This is the secondary shortcode'; } //default else{ return 'This is something else'; } } add_shortcode('my_primary_shortcode','display_my_shortcode'); add_shortcode('my_secondary_shortcode','display_my_shortcode');

Depending on what shortcode you call (either [my_primary_shortcode] or [my_secondary_shortcode]the content will differ.

Registering the shortcode with the add_shortcode() function

To register a shortcode all you need to do is call the add_shortcode($name, $callback_name) function.

This function takes two parameters; the name of the shortcode (the name that will be used in the editor) and the name of the callback function that returns the output (that does the actual processing)

As an example, look at the following:

//callback function for the 'clear_content' shortcode function clear_content_callback_function($atts, $content, $tag){ return ' <div style="clear: both; float: left">' . $content '</div> '; } //add the new 'clear_content' shortcode add_shortcode('clear_content','clear_content_callback_function');

The shortcode name itself should be all lowercase and with only digits and underscores.

There have been long standing issues with the use of hyphens in shortcodes so I would simply define your shortcodes without them, but you are free to do so if you are feeling adventurous.