If you’ve ever had to migrate a client from WordPress to Drupal, one of the first things they’ll ask for is how to add shortcodes in Drupal.
Shortcodes in WordPress are macros that you can drop into content and have it render an object. For example, if you want to embed a gallery in WordPress you simply add [gal… id=”123″ size=”medium”] into the content and when a post is displayed a gallery is rendered.
Implementing similar functionality in Drupal is very easy thanks to the Shortcode module. The module is not an exact copy of the Shortcode API but implements very similar functionality. If your clients are use to shortcodes in WordPress then they’ll feel right at home using them in Drupal.
In this tutorial, you’ll learn how to configure and use the Shortcode module in Drupal.
Now, you may be thinking to yourself, can’t Token do this? The short answer is yes. You can implement similar functionality using Token Filter. The module implements a custom filter which can be added to text formats. If you add
[site:name] into the body, it’ll render the site name.
Installing Shortcode is fairly simple, just download the module and enable Shortcode and “Shortcode Basic Tags”.
If you use Drush, run the following:
drush dl shortcode drush en shortcode shortcode_basic_tags
Using Basic Tags
On its own the Shortcode module does not offer actual shortcodes, it just offers an API for other modules to use. You’ll need to enable one of it’s sub-modules like “Shortcode Basic Tags” or “Shortcode Video Macro” to embed shortcodes. The one which you’ll use the most is the “Shortcode Basic Tags” sub-module. It offers a bunch of common shortcodes like
[button] and more which can be added into content.
Let’s now configure the module to allow editors to add three shortcodes:
1. First make sure you’ve enabled the “Shortcode Basic Tags” sub-module. Then go to Configuration, “Text formats” and click on the “Filtered HTML” configure link.
2. From the “Enabled filters” checkbox list select “Shortcodes” and click on “Save configuration”.
At this point we’ve just enabled the filter. Click on the “Shortcodes” vertical tab to select which codes will be allowed.
3. Scroll down and click on the “Shortcodes” vertical tab, select Image, Link and Button and click on “Save configuration”.
4. Reorder the filters and make sure “Shortcodes” is under “Limit allowed HTML tags”. This means it’ll be processed after “Limit allowed HTML tags”. If you don’t do this then
[img] shortcodes will be filtered out and not displayed.
5. Now that we’ve configured everything let’s test things out. Go to Content, “Add content” and click on “Basic page”. Add a title and add the following shortcodes into the body field:
[button path="node/2" (class="additional class")]Order now[/button] [img src="misc/druplicon.png" (class="additional class"|alt="alt text")/] [link path="node/2"]link text[/link]
Examples of all shortcodes are available from the text format field-set. You’re not expected to remember all the shortcodes. If you’re not quite sure how to compose a shortcode look in this area.
Now if you view the page that we just created, you should see the rendered shortcodes.
Embedding YouTube Videos
In the last section we looked at the basic shortcodes, let’s now allow editors to embed videos. First, make sure you have enabled “Shortcode Video Macro”, this sub-module implements the shortcodes for embedding YouTube videos.
Currently the only platform that’s supported is YouTube.
1. We need to go back to the “Filtered HTML”, so go to Configuration, “Text formats” and click on “Filtered HTML” configure link.
2. Go to the “Shortcodes” vertical tab and select “Enable Video macro shortcode”. Then click on “Save configure”.
3. The “Convert URLs into links” filter needs to be tweaked for it to work with the
. When rendered the video will be embedded using an
As you've seen, shortcodes give editors extra flexibility by allowing them to embed media objects without having to remember big chucks of code. Each shortcodes has its own theme function which means you can modify how the link or button is rendered by overriding the theme function.
Q: I've followed your tutorial but the shortcodes are not working?
Review your filters and make sure the Shortcodes filter has been enabled. Make sure that the filter goes after the "Limit allowed HTML tags" or some HTML will not be displayed.
Q: Most shortcodes are working but some like
[img] are being filtered out.
Make sure that the filter goes after the "Limit allowed HTML tags" or add
<img> to the "Allowed HTML tags".