1stwebdesigner

Create Custom WordPress Shortcode and Make Your Site User-Friendly

Posted: 15 Oct 2014 06:00 AM PDT

As WordPress introduced the Shortcode API in Version 2.5, a large number of plugins were released to help users add content to posts and pages in a user-friendly way. Although there are five of them already, the need for more shortcodes still continues as more and more plugin and additions of features are being developed. By that, this article is about how to create custom WordPress shortcode.

Shortcodes allow users to add particular styles or features to a site without going to the codes. WordPress have five default shortcodes within the WordPress core, namely:

Understanding Shortcodes

Shortcode API is a simple set of functions for creating macro codes for use in post content. It helps developers to create special kind of content such as forms and content generators, which users can use to attach to a certain post or page.

It usually comes together with themes or plugins. By just inserting something inside square brackets, it will replace that content with some other kind of content, usually being driven by a series of PHP functions.

Shortcode usually comes with this simplest version:

  [advertisement]

The Shortcode API makes it easy to create shortcodes that support attributes like this:

  [advertisement height="100" width="100"]  This is an Add  [/advertisement]

Two Steps Involved in Creating a Shortcode

Building the Primary Handler Function
WordPress Hook for the Handler Function

Although there might be some instances that you need to go beyond these steps, these two are the essential steps to build a shortcode.

Let’s take a look how we can create a custom shortcode for the advertisement theme options created from a previous tutorial about how you can create a theme options.

STEP 1 – Building the Primary Handler Function

The primary handler function will handle all the details and content of the Shortcode. Open up your functions.php file and create the primary function.

  function advertisement_1(){    // Do something here  }

STEP 2 – Adding the Attributes

The name of our function is advertisement_1. Shortcode handlers are generally similar to WordPress filters: they accept parameters (attributes) and return a result (the shortcode output). For this part, add the $atts attribute.

  function advertisement_1($atts){    // Do something here  }

This is the most commonly used attribute which consists of an associative array of attributes or an empty string if no attributes are given.

There are two more parameters that can be passed to the Shortcode callback function:

$content – the enclosed content (if the shortcode is used in its enclosing form)
$tag – the shortcode tag, useful for shared callback functions

STEP 3 – Creating Shortcode Content

For this tutorial, you're going to display the content of the theme option advertisement area from this previous tutorial.

There are two advertisements here, the 743 X 82 px and 268 X 268 px banner ads.

Looking into to the process of calling these theme options to the template files, you've got the following codes.

  <?php $options = get_option( 'theme_settings' ); ?>  <?php echo $options['banner1']; ?>

Now, you need to call these inside your primary function and return the result. Use a variable $output to store the [banner1] option content, which is the 743 X 82 px banner ads content.

  function advertisement_1($atts){  $options = get_option( 'theme_settings' );  $output = '<div>' . $options['banner1'] . '</div>';  return $output;  }

Note: As of PHP 5.3, it's now possible to create an anonymous function but this is not recommended since anonymous functions can’t be removed later by plugins or themes.

For instance, when you distribute your theme, and another developer tries to customize or call it back via a child theme or plugin, it can't be done. Changes made by an anonymous function is permanent and can’t be revised.

STEP 4 – WordPress Hook for the Primary Function

Next, you need to hook the primary function into the WordPress to associate the shortcode of your theme options. This can be done using the add_shortcode function. Check out the code below.

  add_shortcode('advertisement_1', 'advertisement_1' );

The name of the shortcode is exactly the same as primary function for simplification but feel free to set your own name.

So by this time, if you use the [advertisement_1] shortcode the 743 X 82 px banner ads will be display anywhere according to the placement of the shortcode either in post or page.

banner1

Applying the Same Steps on Advertisement 2

It's actually easy to apply all of these steps on the 2nd banner, which is the 268 X 268 px banner ad. Check out the code below.

  function advertisement_2($atts){  $options = get_option( 'theme_settings' );  $output = '<div>' . $options['banner2'] . '</div>';  return $output;  }  add_shortcode('advertisement_2', 'advertisement_2' );

Notice that you have the same set of codes except for the name of the primary function and name of the shortcode inside the hook. You also use the ['banner2'] option to refer to the 2nd banner and then simply return it using the $output variable.

banner2