Proposal to Overhaul the Shortcode API in WordPress Goes Back to the Drawing Board

Robert Chapin, who contributes to WordPress core, published the first draft of a roadmap that explains how the Shortcode API could be overhauled. “The decision to create this roadmap arose from specific needs that are not met by the old code,” Chapin said.

The proposal has an aggressive timeline with development starting in WordPress 4.4 and ending in WordPress 4.7. In WordPress 4.4, a new syntax would be introduced that provides opportunities to make significant changes to the API.

Here are a few examples of shortcodes that use the new syntax.
Self-Closing: [{{shortcode}}]

Attributes: [{{shortcode attr1=”value1″ attr2=’value2′ “value3” ‘value4’ value5}}]

Enclosing: [{{shortcode}$] HTML [${shortcode}}]

Multiple Enclosures: [{{shortcode}$] HTML [${encl2}$] HTML [${encl3}$] HTML [${shortcode}}]

Escaped Code: [!{{shortcode}}]

In the WordPress 4.5 development cycle, the focus would be to deprecate the old syntax, “Plugins that register shortcodes without declaring support for new features will raise debugging errors to alert developers that support for the old shortcode syntax is ending,” Chapin said. Posts using the old syntax would continue to work.

During the WordPress 4.6 update process, shortcodes using the old syntax would be converted to use the new syntax. The Shortcode API would continue to provide deprecated support for the old syntax to provide a smooth transition.

An important point to note is that the new syntax does not support HTML inside of shortcode attributes. This leaves the potential for many sites to break as shortcodes may not perform the same way prior to WordPress 4.6

The transition process ends with WordPress 4.7 where support for the old syntax is eliminated. Shortcodes and plugins that use the old syntax would stop working. During the WordPress 4.7 update process, a second attempt would be made to upgrade old content to use the new syntax.

The Proposal Raises Concerns

The proposal has drawn constructive criticism from several members of the WordPress community. Nick Haskins, founder of Aesop Interactive, voiced his concern saying the syntax isn’t easier for authors to use and will affect a large number of sites.

Mika Epstein, who voluntarily moderates the WordPress.org support forums and interacts with users on a daily basis, sums up a list of concerns that many developers agree with.

All the plugins and themes on the planet we will break (because we will, they won’t read or test). We have to degrade them as gracefully as humanly possibly. Continuing to say “Well the developers were notified and should have updated” now that we’re as big as we are is not sustainable.

All the very (legitimately) angry end users who are broken because they didn’t upgrade plugins and themes (or the themes/plugins didn’t get updated). People were rightly angry last time. It’s the end users, not the developers, who will be hardest hit by this change.

Communicating clearly to the users that it’s now {{gallery}}. That’s going to be very hard. Incredibly hard. Updating their old posts (keeping in mind Justin’s Markdown caveat and those who use them as an aside – I know I know) is easier than making sure everyone knows what to do. At best we can keep tabs on the ones built into WP and perhaps use the logic we have in the visual editor NOW to convert them, but we have to figure out how to make sure everyone knows. This is nothing like the move of Menus to customizer. That was confusing, but the users could see what happened. This is a legit change, your old way is no longer going to work. That is huge.

The number of users who have premium themes and plugins that do not get update alerts. These people are simply not going to know they need to update and this is not their fault. We should never be breaking them if there’s possibly any alternative.

Users will be upgraded by their hosts vis-a-vis one-click installs and managed hosting so they will have up to date WP and out of date plugins/themes. So yes, many users will be on 4.7 and then a theme from 2014. It sucks, it’s the reality, we know it’s the reality, we cannot stick our heads in the sand.

Plugins that are already using {{template}} tags in their code. Yeah, I’ve seen it. Most of them use it for search/replace within their own code, but we’ll want to make sure we check for everyone in the repo who might be doing it on their own.

The best argument against using the new shortcode syntax is made by Stefano Agiletti. Agiletti says Italian keyboards don’t have keys that create curly braces.

Maybe English people don’t know that { and } are not present in all keyboards directly as the [ and ] are. On Italian keyboards [ and ] are generated using ALT-GR+è or ALT-GR++ and keyboards show ALT-GR basic sign like €@## and [ ].

To get { and } you need to type ALT-GR+SHIFT+è and ALT-GR+SHIFT++. Most people don’t know about this combination (I think only those who write code do) and the parentheses are not written on any key.

Back to the Drawing Board

After a considerable amount of feedback and concerns shared by developers, the proposal is heading back to the drawing board. In a comment summarizing the feedback, Andrew Nacin confirms that the new shortcode syntax does not fit the core team’s vision of being easy and intuitive for non-technical authors to use.

At the same time, he cautions that the team needs to do something, “The proposed syntax significantly clashes with the proposed vision and given all of your feedback, we’re clearly going to have to go back to the drawing board. Please note that we still need to do something, but maybe we can think further outside the box.”

I highly encourage you to read the proposal and the comments that follow it. It’s a great read that highlights how difficult it will be to make changes to the Shortcode API that don’t end up causing a lot of sites to break.