Perch CMS Shortcodes

We added a shortcodes system into Perch and Runway 3 to help better integrate Editor toolbars with the Assets system. In doing so we created a whole new way to add your own functionality to Perch.

Embedding images and media into content

Our suggested way of getting images or other media into content is to do that through Perch templating. Perhaps using Blocks to let your content editor choose which type of content they want to add and build up their post or page. The benefit of doing this is that you retain full control of the generated markup and the element is stored alongside the content in a structured and reusable way.

However, we accept that sometimes you just want to be able to embed an image, video or other asset using the editor toolbar. We were frequently being asked to properly integrate the Perch Assets functionality with the editors. In Perch and Runway 3 we wanted to solve this issue in a good way, in a way that wouldn’t cause other problems and that would be more generally useful than just allowing items from Assets to be embedded.

The problem with shortcode systems

We did some research into how other systems manage the issue. We found that WordPress has a shortcode system, and in researching the problems and benefits of their implementation we discovered lots of posts warning users to be very careful when using shortcodes. The problem was that if a shortcode was generated by a theme or plugin which was later removed, these shortcodes remained littered through the content.

The thing we care about most here at Perch is your content. The idea of having any solution that littered your content with codes that we couldn’t remove for you, goes against everything we care about. If we were going to implement shortcodes, it had to be in such a way that we could always remove them - whether we had added them or a third party app had done so.

Other requirements

In addition to not leaving a mess behind, we wanted to make shortcodes easy to type. If you wanted to add one outside of using the toolbar, it should be straightforward to type into the content.

We felt that shortcodes should be easy to recognise by a content editor. When they saw one in CMS content they should instantly know that it would be replaced out.

We wanted to build a generic solution, rather than one that only worked with the Assets functionality. This would mean that Perch developers could create their own shortcodes to embed other types of things

The Perch shortcode solution

Perch shortcodes - added by us or a third party - all start with [cms:. Perch Assets shortcodes for example are as follows:

[​cms:asset 1234]

Perch can look for any tag that looks like this and replace it. We either replace it with whatever is defined by the shortcode provider for that shortcode, or we replace it with nothing. This means if the shortcode provider goes away you don’t get stray tags left lying around the published content.

As the shortcode always starts with [cms: it can easily be explained to a content editor, “this is something for the CMS”. If they are using the SimpleMDE Editor that has a preview. The preview will display the rendered output with whatever the shortcode embeds included.

The solution uses a system of Shortcode Providers. Built into Perch is a provider for Perch Assets. If you use our Twitter App you will find there is a provider for embedding Tweets. You can also add your own handlers. In the documentation you can see an example of a shortcode handler for embedding Instagram photos. This met our requirement of creating a solution that could perform far more tasks than just solving our Assets integration problem.

We think this is a nice addition to Perch and Runway. Something that helps solve a real problem in a way that won’t mess up your content, and also opens up new functionality for developers. We hope you find them useful.