Issues caused by WordPress Shortcode API Changes

The shortcodes in WordPress are a tremendously useful tool; with them its possible to create expansive content in your Posts, Pages and Widgets without the need to write your own HTML or PHP code. For example, you’ve likely used the built-in image gallery shortcode: gallery id=”xxx” between square brackets, which adds the specified gallery to your page or post. Many developers take things much further than that, with extensive plugins that can display a range of items. In fact, if you’ve used one of our more recent themes then you might have seen our News Show Pro plugin being put to good use creating post and product showcases, with an extensive set of alternative options to play with. The great thing about this kind of setup is that it becomes trivial to duplicate the plugin, since all you need to do is copy and paste the shortcode to another content area.

shortcode content

Shortcode API Changes

At the end of July WordPress version 4.2.3 was released, and in this case it was quite a hefty security fix that directly affects the Shortcode API. Unfortunately, once the update hit it turned out that many WordPress plugins’ shortcodes stopped working, or run into bugs of some kind. In particular, many users found that the content of the shortcode wasn’t being evaluated, so instead of seeing the content the shortcode produces they’d just get the plain shortcode text appearing on their site instead.

One of the big issues here is that many users are inexperienced with WordPress, or just have automatic updates on and don’t pay attention to security updates since they are, for the most part, completely compatible with existing plugins and themes. So when something like a shortcode starts acting up, users may not even realize an update has been released and will think that they have caused the issue themselves. The article highlighting the issue was released on the same day as the update (you may find it here), but personally I think waiting to release day to highlight such problems is a bit late for plugin and theme developers, as well as users, to be prepared for the issues the updates can cause. Far better to release details earlier so that the information can be disseminated through developers, and then onto users accordingly to reduce the impact of the large changes the update included.

So what’s the scale of the problem?

Potentially all shortcodes in WordPress may be impacted by this update; it just depends on how you’ve implemented them on your site. The basic question you have to ask yourself is “Do I have any shortcodes which produces raw HTML fragments or attribute values?”. That is, shortcodes that produce things like URLs that go into href=”” or src=”” attributes in the HTML content. If possible though, it’s a good idea to review all of your WordPress shortcodes and make changes to the quoted attributes that you’ve used whenever your shortcodes are mixed with raw HTML code.

What can I do to fix it?

Things aren’t as bad as you might think; though there’s a chance that a lot of your shortcodes have run into issues, it’s generally, in most cases, quite easy to fix shortcodes used in posts or pages. As an example, let’s look at a shortcode that used to work properly:

 <a href="/[shortcode query="?ref="]"> 

This shortcode will be now rejected by the Shortcode API and you’ll be stuck with the plain shortcode text. However, as a workaround you can use the following slightly-modified shortcodes instead:

<a href="/[shortcode query='?ref=']"> <a href='/[shortcode query="?ref="]'> 

Shortcodes and our themes and plugins

In the case of our core content included in our themes and plugins, the only shortcode I’ve found that may cause an issue is the “pageurl” shortcode, which is used in our posts, pages and widgets to display the current homepage url of your website. It might sound boring, but it’s actually very useful since we use this shortcode to display background images, links etc…and thanks to it you don't have to worry about fiddling around with your file paths when moving your website to another server. It’s also the trick to getting our quickstart packages running smoothly; after installing the quickstart the shortcode is changed to reflect your server’s URLs, so no extra manual configuration required. For the most part this “pageurl” shortcode works properly with href or src attributes in our quickstart packages, and they don’t have any other shortcode attributes, but I have noticed that in this piece of HTML in our John theme:

<div class="gk-map" data-src="[pageurl]/wp-content/themes/John/images/demo/map.jpg"> </div>

the shortcode is not displayed properly.

The simplest solution for this problem is to replace the

with your current website URL, since that was the only function of this shortcode you’ll find this makes everything work fine again. In the next theme update we'll prepare an additional shortcode which will fix the issue:

function gavern_ts_tag_shortcode( $atts, $content ){
	// return the tag with class and src
	extract( shortcode_atts( array(
	    'tag' => 'div',
	    'class' => '',
	    'src' => '',
	  ), $atts ) );
	  $url = home_url();
	  return '<'.$tag.' class="'.$class.'" data-src="'.$url.'/'.$src.'">' .$content.'</'.$tag.'>';
add_shortcode( 'gktag', 'gavern_ts_tag_shortcode' );

With it, you won't have to use the shortcode as a data-src attribute, but the shortcode will produce the entire div with the necessary class and home url added automatically into the data-src attribute.

the example shortcode:

[gktag class="gk-map" src="wp-content/themes/John/images/demo/map.jpg"][/gktag]

will create the desired content:

<div class="gk-map" data-src=""> </div>

We'll check through all of our themes carefully to make doubly-sure that there aren’t any other issues, but if you should run into an issue with a shortcode in our quickstart packages do get in touch with us, either via the comment section below or in the relevant theme section in our forum and we’ll do what we can to help!

Issues caused by WordPress Shortcode API Changes 3.965 (79.20%) 25 votes
This article was first published August 19th, 2015