Shortcodes in Drupal? Yes, you can!

Wordpress is growing on me the more I develop websites with it.  One thing about Wordpress that I’ve grown to love is shortcodes.  They make adding complex elements pretty easy for the users managing the website, without them having to dive into HTML.  After a bit of research and trial and error, I was able to integrate shortcodes with Drupal too! Let's dive in and create a button shortcode for our Drupal 7 website.

I was developing a Drupal website and I realized shortcodes would be really useful in the sidebar of the website.  I decided to do some research and see if there were any similar modules for Drupal that would allow for shortcodes.  Whaddya know, there’s a stable Shortcodes module for Drupal 7!  The module comes with sub modules that have a set of predefined shortcodes.  I quickly realized that there is no documentation (or any good documentation I could find) on setting up your own custom shortcodes.  After a little playing around, I was able to create my own custom shortcodes pretty easily.

For this tutorial we are going to create a simple button shortcode.  It will look as follows:

[button link="http://google.com"]Button Text Here[/button]

Our HTML that will be outputted is:

<div class="button"><a href="http://google.com">Button Text Here</a></div>

Step 1: The Obvious – Install and enable the Shortcodes module

Of course, you need to make sure you have the Shortcodes module installed and enabled.  It comes packaged with several sub modules, but for this tutorial we will only need to enable the Shortcode module (and our custom module, which we will create now).

Step 2: Create our custom module .info file

To create our custom shortcodes, we need to create our own custom module.  Let’s call it Custom Shortcodes.  Here is an example of a module .info file:

name = Custom Shortcodes
description = Provides custom shortcode tags to be used within site content.
package = Shortcode
core = 7.x
dependencies[] = filter
dependencies[] = shortcode

Create a new folder within your sites/all/modules directory named custom_shortcodes and save this file in there.

Step 3: Create our module file

There are two main functions we will use within our custom module file that define our shortcodes and their properties.  Our two main functions are:

/**
 * Define our shortcodes and their titles, descriptions, and callback functions
 *
 * See comments below for explanation
 */
function custom_shortcodes_shortcode_info() {

    $shortcodes['button'] = array(
        'title' => t('Link Button'),  // The title of this shortcode, displayed in the Drupal backend for administrators to enable/disable shortcodes for input types
        'description' => t('A simple button.'),  // Description shown along with the title in the Drupal backend
        'process callback' => 'custom_shortcodes_shortcode_button', // Custom function that deals with the variables and html output
        'tips callback' => 'custom_shortcodes_shortcode_button_tip' // Custom function that displays some help text to the user
    );

    // $shortcodes['second_shortcode'] = array();
    // $shortcodes['third_shortcode'] = array();
    // and so on...

    return $shortcodes;
}

/**
 * Define our variables (parameters) for each shortcode
 */
function custom_shortcodes_theme() {
  return array(
    'shortcode_button' => array(
      'variables' => array('text' => '', 'link' => ''),
    ),
    // 'second_shortcode' => array(),
    // 'third_shortcode' => array(),
    // and so on...
  );
}

Each shortcode will then have three of it's own functions that collect its properties and output them.

function MYMODULE_shortcode_SHORTCODENAMEHERE($attrs, $text) {}
function theme_shortcode_SHORTCODENAMEHERE($vars) {}
function MYMODULE_shortcode_SHORTCODENAMEHERE_tip($format, $long) {}

These 3 functions will be used each time you create a different shortcode.  Note that you don't necessarily need the third function for the WYSIWYG tip, but I believe it is a useful feature.  You can show the user which shortcodes are available and explain how to use each one and what parameters they have.

Now, lets use these 3 functions to create our button shortcode:

/**
 * Define our process callback function for our [button] shortcode. This
 * takes in our shortcode attributes from the shortcode and if empty, sets the property
 * to the default value stated in this function.  We then pass in our attributes to the
 * theme() function which outputs the HTML.
 *
 * $attrs = shortcode_attrs(array(
 *     'attribute' => 'default_value_goes_here'
 * ),
 */
function custom_shortcodes_shortcode_button($attrs, $text) {
    $attrs = shortcode_attrs(array(
        'link' => 'http://mywebsite.com'
      ),
      $attrs
    );

    return theme('shortcode_button', array('link' => $attrs['link'], 'text' => $text));
}

/**
 * This function uses the attributes passed in to return the HTML of this shortcode.
 */
function theme_shortcode_button($vars) {
  return '<div class="button"><a href="' . $vars['link'] . '">' . $vars['text'] . '</a></div>';
}

/**
 * This function outputs some tips to the user beneath the WYSIWYG editor so they know
 * what the shortcode does and how to use it.
 */
function custom_shortcodes_shortcode_button_tip($format, $long) {
  $output = array();
  $output[] = '<p><strong>' . t('[button link="http://URLhere.com"]text[/button]') . '</strong> ';
  if ($long) {
    $output[] = t('Outputs text that is displayed as a button, which links to a specified URL.') . '</p>';
  }
  else {
    $output[] = t('Outputs text that links to a URL.') . '</p>';
  }

  return implode(' ', $output);
}

Now we have finished our module file. Save it and if necessary upload it through FTP to your website.

Step 4: Enable our custom module and shortcodes.

Now you can go ahead and enable your custom module.  Next, you must enable the individual shortcodes.  You can enable different shortcodes per input format which gives you a ton of control. 

1. Go to Configuration > Content Authoring > Text Formats.
2. Find the input format you want to enable the shortcode for and click on Configure in that row.
3. Enable the two shortcode filters (Shortcodes - HTML corrector and Shortcodes).
4. Under Filter settings, check the checkbox next to 'Enable Link Button Shortcode'.
5. Click Save.

Step 5: Test it out!

I added a custom block to test out my shortcode.  If you notice below the WYSIWYG editor is our helpful tip to users on how to use the shortcode:

After some simple styling with CSS, we now have a clickable button!