Using shortcodes in WordPress like a boss

Using shortcodes in WordPress like a boss

One of the many handy features of WordPress is its shortcode functionality. This post will go through some basic principles of creating and using shortcodes in WordPress.

This is an ongoing post. Please suggest corrections, explanations, etc. in the comment section at the bottom of this page.

WordPress plugin and theme developers often use shortcodes to incorporate functionality for their users. Shortcodes come in many shapes and sizes, but ultimately, is like using a shortcut to display larger pieces of code. After a WordPress shortcode is created, it can be used in the Post Editor or inside PHP code.

What is a WordPress shortcode

In its simplest form, a WordPress shortcode is a piece of WordPress code that represents another piece of code. It is easily identified by being encapsulated in square brackets (e.g. [shortcode_name]).

The code that is represented by the shortcode can be in the form of PHP, HTML, JavaScript and CSS.

WordPress itself also has a couple of very handy, built-in shortcodes, but shortcodes can also be created using plugins and/or by using PHP and WordPress functions.

Why use shortcodes in WordPress

WordPress shortcodes have many uses. Apart from shortening pieces of code, shortcodes are also often used to ‘recycle’ code, add WordPress functionality to where it is used, to centralise code and to keep complex code away from inexperienced users.

Pieces of code (e.g. HTML code showing a message) that will be used on various Posts and/or Pages can be converted into a shortcode. This allows the code to be reused without having to retype it over and over. If the piece of code (e.g. the message) needs to be changed at some point, it only needs to be done in one place.

Complex, large and/or functional pieces of code can be written with more complex PHP or JavaScrip programming languages. These pieces of code can be converted into a shortcode, bringing it, together with its functionality to, for example, the Post Editor. The shortcode will also shorten the code significantly, preventing unnecessary clutter in the Post Editor.

Creating custom WordPress shortcodes

As mentioned earlier, custom WordPress shortcodes can be created using plugins and/or by using PHP and WordPress functions.

Sample code

As an example, let’s say you want to add and reuse the following ‘Follow me on social media!’ message to a WordPress website:

Follow me on social media!

The HTML and CSS code for this message looks as follows:

<div style="text-align: center; background: red; color: white; margin-bottom: 20px;">Follow me on social media!</div>

Creating custom shortcodes using the Shortcoder plugin

The easiest way to create custom shortcodes with WordPress is by using a plugin. There might be a couple of plugins available, but a popular free choice is the Shortcoder plugin created by Aakash Chakravarthy. It is used to create, manage and update shortcodes without being code-savvy. At the time of writing Shortcoder was at version 5.3, had more than 60 000 active installs and an average rating of 5 out of 5 stars.

Shortcoder plugin

After installing and activating the Shortcoder plugin from the WordPress Plugins section, its settings are available under the Shortcoder menu.

Using the sample code described earlier, simply Create a new shortcode, name it, and paste add code to the Shortcode content section. Code can either be added using the Visual editor and/or the Text editor feature. The shortcode is saved by clicking the Create shortcode button at the bottom.

Multiple shortcodes can be created. Shortcoder will make sure that there are no duplicate shortcodes names.

Shortcoder sample

By using, for example, ‘my_social_media_message’ as the name of the shortcode, Shortcoder will create a shortcode named [sc name="my_social_media_message"]. See Inserting shortcodes into WordPress later on this post.

Creating shortcodes using the functions.php file

For those that don’t like plugins, like to have more control and/or is a bit more code-savvy, shortcodes can also be created manually using PHP.

To create a shortcode using PHP, the shortcode output function together with the WordPress add_shortcode() function is added to the main plugin file or the (child) theme’s functions.php file.

To create a function to output the example code/message described earlier, the following code needs to be added before the closing ?> tag of the functions.php file:

add_action( 'init', 'register_shortcodes');

function register_shortcodes() {
  // Registering the shortcode using the add_shortcode() function.
  add_shortcode( 'my_social_media_message', 'bts_social_media_message' );
}

/**
* Function that returns HTML code as a string
*/
function bts_social_media_message() {
  return '<div style="text-align: center; background: red; color: white; margin-bottom: 20px;">Follow me on social media!</div>';
}

To break things down, first, create a function to output the example code/message described earlier:

function bts_social_media_message() {
  return '<div style="text-align: center; background: red; color: white; margin-bottom: 20px;">Follow me on social media!</div>';
}

where bts_social_media_message is the name of the function. The function needs to return the code. In this case, the code is encapsulated in apostrophes to indicate that it is a string. To make sure the function name is unique, it is good practice to add a prefix to the function name. In this case, bts_ is used as a prefix.

When there is a problem with the HTML formatting of the code, the return value can be run through the WordPress wpautop() function first:

function bts_social_media_message() {
  return wpautop('<div style="text-align: center; background: red; color: white; margin-bottom: 20px;">Follow me on social media!</div>');
}

To be able to use the output of bts_social_media_message() as a shortcode, it needs to be registered with WordPress. This is done with the WordPress add_shortcode() function.

According to the WordPress codex, the WordPress add_shortcode() function takes two arguments/parameters:

  1. The shortcode tag that is to be used as the identifying name of the shortcode (in this case, 'my_social_media_shorcode')
  2. The name of the function handling the output of the shortcode (in this case, 'bts_social_media_message')

Both these parameters should be unique so they don’t interfere with other shortcodes included by WordPress core, themes or plugins. If there is another shortcode output function with the same function name WordPress will throw a critical error and if there is another shortcode with the same tag, the latest one will be used.

To follow the example earlier, this is what the add_shortcode() function should look like:

add_shortcode( 'my_social_media_message', 'bts_social_media_message' );

Now, if the shortcode [my_social_media_message] is called, the bts_social_media_message() function is called.

It is good practice to call the add_shortcode() function before the output function. It is also good practice to describe the output function for future use:

// Registering the shortcode using the add_shortcode() function.
add_shortcode( 'my_social_media_message', 'bts_social_media_message' );

/**
* Function that returns HTML code as a string
*/
function bts_social_media_message() {
  return '<div style="text-align: center; background: red; color: white; margin-bottom: 20px;">Follow me on social media!</div>';
}

In order to give WordPress enough time, it is recommended to register shortcodes at the time WordPress is initiated. All the shortcode register functions can be added to their own function:

function bts_register_shortcodes() {
  // Registering the shortcode using the add_shortcode() function.
  add_shortcode( 'my_social_media_message', 'bts_social_media_message' );
}

and then added to the WordPress init() action hook:

add_action( 'init', 'bts_register_shortcodes');

The final shortcode PHP code will look as follows:

add_action( 'init', 'register_shortcodes');

function register_shortcodes() {
  // Registering the shortcode using the add_shortcode() function.
  add_shortcode( 'my_social_media_message', 'bts_social_media_message' );
}

/**
* Function that returns HTML code as a string
*/
function bts_social_media_message() {
  return '<div style="text-align: center; background: red; color: white; margin-bottom: 20px;">Follow me on social media!</div>';
}

Inserting shortcodes into WordPress

After a shortcode has been created, it can be used in one of two ways.

The most common (and easiest) way is by adding the shortcode into the Post Editor (or any other text editor).

If the Shortcodes plugin was used, created shortcodes can either be copied and pasted, or inserted into content areas using the Shortcoder button at the top of the WordPress Post Editor.

Shortcoder insertion button
After the Shortcoder plugin has been installed, a Shortcoder button will start to appear on the top of the WordPress Post Editor. Also note that another shortcode, named “ongoing” is also added to the post shown above.

When PHP was used to create the shortcode, the shortcode tag (e.g. [my_social_media_message]) is used.

In both cases, the content of the shortcode will not show until the post/page was saved, and refreshed/previewed.

For areas of a website which is not accessible through a text editor, e.g. the website footer area, shortcodes can be added using PHP. The following code will add the earlier example:

echo do_shortcode('[my_social_media_message]');

or

echo do_shortcode('');
About the author
Renier busies himself with improving his English writing, creative web design and his websites, photoshopping, micro-electronics, multiple genres of music, superhero movies and badass series.
Behind the Scenes is a free, informative website. If you find value in any of our content, please consider making a donation to our cause.
Donate via PayPal

Save, share & Disqus

Use the buttons below, on the left or the bottom of this page to share this post. Your comment is important, but don't be a knob. Keep it constructive and polite.

Comment via Disqus

Disqus is a worldwide comment hosting service for web sites and online communities. This secure platform ensures a pleasant commenting environment which is manageable from one account. Use the Login button to sign up.

More website development related posts

Improve your skills through Skillshare – get first 2 months for free
Improve your skills through Skillshare – get first 2 months for free
20 October 2020
Ad: Join the Skillshare online learning community with videos on programming, website development, art, designs and many more. Try Skillshare for free for two months now! More…