A lot of our plugins use embedded shortcodes inside square brackets.
- Foliopress Testimonials
- FV WordPress Flowplayer
- Embedded Menus
- FV Embedded Menus Pro
- Sniplets (created with John Godley)
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 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.
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.