How to Add a Custom Shortcode to Drupal 7

We recently received a request to embed some JavaScript for a live chat client into multiple pages within our site.  The live chat service provided the JS code snippet to our team along with the ID key we would need to use within the snippet to link the client on our pages with the live-chatters on the other side.  There were also a few settings that could be changed within the snippet — things like background color, offset width, and location on the page.

Since we do not allow JavaScript tags within our WYSIWYG editor, we couldn’t just ask our Content Managers (CMs) to copy/paste the snippet right into the Body (or other) field.  We also didn’t want to be called upon everytime the script needed to be embedded on a different page or when the ID key changed due to a new marketing campaign (or any other reason).  We decided to use Shortcodes.

Shortcodes are little bits of code that, when parsed in a field that allows them, expand to a pre-defined output, replacing any pre-defined variables in the expansion.

For a quick example, a shortcode for embedding a link to Google may be:

When that string is parsed in a shortcode-enabled field, it might render as:

This is useful because, if the link to Google were to ever change, any number of instances of the shortcode can be updated all at once by one modification to the Shortcode code.

As I mentioned, Shortcodes can also take variables.  For example:

might expand to

This tutorial requires the contrib module Shortcode.  We’ll write a custom module to extend its functionality and add a new shortcode. Here’s how to do it.

First, let’s create a module.  I’ll call mine “tmbridge_custom_shortcodes” and, thus, create a directory, tmbridge_custom_shortcodes, in my custom modules directory and two files, tmbridge_custom_shortcodes.module and, in that directory.

I won’t speak to writing the info file in this post, but you can refer to this page on d.o for more information.

The first thing we need to do in this new module is name and describe our new shortcode and indicate the callback functions it will use:

We need to define the variables (or attributes) for our new shortcode.  We do this by implementing hook_theme():

Next, let’s define our callback function for the new shortcode.  This callback function takes the variables as defined by the user in the shortcode’s use in the WYSIWYG editor and applies any business logic, formatting, or modification (like setting a default, if empty):

Now, we need to define the theme function that our process callback function calls.  In this case, it’s simply ‘shortcode_friendly_alert’.  This theme function returns the output of the shortcode with the variables replaced.  Here’s where the magic of this module happens.  You can put literally any markup you wish into this function’s output and populate as many variables within it with user-defined data (this means you could get data from any Drupal object that’s in scope, as well).  It could be JavaScript (including AJAX functionality), CSS, output from other theme functions (blocks, views, etc.), Or… just run of the mill HTML markup.

In this tutorial, we’re just using some (really) basic JS and HTML to make the point, but I really want to drive home the wide breadth of functionality one could implement herein.

Finally, let’s define our tip callback.  This function outputs text below the WYSIWYG editor that tells the user what the shortcode is used for and shows the user what parameters are available.

And that’s it for the code!  Simply enable the module and be sure to remember to enable the new shortcode in all the Text Formats you’d like it available within (/admin/config/content/formats).  The available shortcodes are listed in the vertical tab “Shortcodes” under “Filter Settings:

Enabling Shortcode in Text Format Settings
Be sure to enable your new Shortcode in the Text Format settings

You will then see your new shortcode available in all fields that use those Text Formats.

Your new shortcode is now available in all WYSIWYG fields that use those Text Formats.
Your new shortcode is now available in all WYSIWYG fields that use those Text Formats.


Leave a Reply

Your email address will not be published. Required fields are marked *