Using Soft Hyphens to Disable Embedded Shortcode in WordPress or other CMS Web Tutorials

A lot of our plugins use embedded shortcodes inside square brackets.

Our embedded shortcodes look something like this:

[command parameter=something value=number]

The reason we use square brackets is that square brackets parse just fine in WYSIWYG editors including our own Foliopress WYSIWYG.

We've had a lot of simple questions about how to use our FV WordPress Flowplayer. I couldn't understand why. The instructions are pretty straightforward.

It turns out that the shortcodes were being parsed and showing the result instead of the code people should be using. How anybody managed to get the plugin working without the short codes is a bit of mystery to me. But they did. Wow can people be ingenious sometimes.

So once I'd found the error, we weren't much better off. I couldn't get the square brackets to stop parsing. With angled brackets it's not so difficult. One just escapes them like this:

< >

But there is no such escape for square brackets (or rather the escape still gets parsed by our plugins).

It turns out that the shortcode won't trigger even if there is a non-breaking space:  .

But that is no real solution as it means that we are telling our users to insert a space or weird character where there is none. No, we needed a real invisible character to disable execution of the shortcode but leave no visible trace in the html.

After much poking around, I finally found one: ­ That's the soft hyphen character.

So I can boldly post commands like this:

[­flowplayer src=example.flv, width=400, height=300]

Which would otherwise result in this:

Clearly showing an empty movie box isn't going to teach a visitor much about how to place an flv in his or her own post.

The long term solution is to code our plugins not to parse what is inside code tags. But in the meantime, soft hyphens can save you in a pinch from having embedded shortcodes execute when they shouldn't.

Alternate techniques (all in use on this site)

  • use javascript to write the opening square bracket): not bad but I'd rather put in an invisible character than face fragile javascript in half a dozen tutorials
  • use sniplets to hold the documentation (as sniplets don't get parsed a second time but just inserted).
    Downsides: unwieldy as you have to go over to sniplets to edit or change tutorials each time. Not easily moved between CMS's or even sites. Plugin dependent.

More readable source code without a javascript code parser

While I was at it, I decided to turn all code into a nice dark green to be more readable and made it a few pixels larger too. Previously code on Foliovision was an elegant but slightly difficult to read medium gray.

This entry was posted in WordPress. Bookmark the permalink.

4 Responses to Using Soft Hyphens to Disable Embedded Shortcode in WordPress or other CMS Web Tutorials

  1. Turns out you can escape shortcodes using double brackets, that is:
    [[shortcode]]
    I had to dig into Wordpess source code to find that out.

  2. Hi Raphael,

    that’s a nice find, thank you for sharing!

    Martin

  3. Actually, I was in the process of building a plugin around your solution when I found it.

    Note that for shortcodes with content, escaping seems to work like this:
    [[code]somecontent[/code]]

  4. Yes, that also works. The shortcode has to be registered, otherwise it’s not needed to use double square brackets. So be careful when testing, you must use some registered shortcode, otherwise this trick won’t be needed and all the brackets will appear.

    Thanks,
    Martin

Leave a Reply