Introducing Image Shortcake v0.1.0

One pain point we’ve had with WordPress, Fusion’s content management system, is that attachments in posts are not treated as first-class objects. Most content, like posts and pages, have metadata attached to them, which define everything from how the piece of content displays in its template, to its relationships with other pieces of content, to additional contextual information for the reader. If this sounds jargon-y, stay with us — we’ll get to concrete examples shortly.

Even though WordPress doesn’t treat them as such, attachments are first-class objects. They have their own entry in the wp_posts database table just like posts and pages, and they can hold metadata too. Developers can define templates for single and archive views for different types of attachments (e.g. images vs. MP3s). Yet in practice, images in the body content don’t get easy access to their rich supporting data. Once an image is added to a post, it becomes frozen as a piece of markup, and subsequently loses all of its contextual information.

We’ve solved this problem for Fusion with Image Shortcake, a tasty topping to our Shortcake plugin. Image Shortcake allows images to be used much more dynamically, as befits a full-featured content management system that treats images as first-class content types. Image Shortcake saves images in post content as shortcodes, which preserve a reference to the database object for the embedded image.

Shortcodes are an obvious solution because they can hold arbitrary amounts of data attributes, and WordPress has built-in functionality for processing them at render time. The key is that the shortcode contains a reference to the attachment post, which allows the plugin to look up data from the attachment and template it for output.

Consider this example. You are a cat and a photographer, and your site is full of, you know, typical cat things, interspersed with your original and amazing photos. Here is the HTML representation of your image, as it’s normally inserted within post content:

Screen Shot 2015-06-04 at 8.22.17 AMtext via

In this example, what happens if you want to change the way images are displayed on your site? Say, for instance, you decide that you want to show off your territory to all of your cat friends. You know that your camera saves geolocation data in its image files, and you know WordPress can extract that information when you upload your images, so you decide to make your theme show maps next to every picture you’ve taken.

Here’s your problem: you have hundreds of posts with this legacy image markup. And you really don’t want to go back through all of them, click through to the attachment, look at the image meta, and insert it into the post again. So you try using regex to process the post content on the fly. Now you have two problems. You could hack something together in JavaScript, but that’s a lesson for another day.

Using Image Shortcake, the <img> tag is instead stored in the post content as:

Screen Shot 2015-06-04 at 8.30.03 AM

“42” is a reference to the original attachment in the database. If you want to tweak the output of all your images, you can just attach a function to one of the filters provided by the plugin. Cats like filters fine. And PHP.

No, seriously, what does Image Shortcake do?

At Fusion, we’re already using Image Shortcake to customize images in our posts in several ways:

  • Responsive Images. Responsive or “adaptive” images are an HTML-based method of serving different image sources to different browsers, based on viewport size, resolution, or file format support. In layperson’s terms, Safari on your iPhone will receive a different size image than Chrome on your laptop. By filtering the output of the shortcode, we’re able to insert a srcset attribute, so that all of the images on our site are served at the smallest possible file size to display clearly in browsers which support the Adaptive Images specification.
  • Replacing GIFs with videos. Another plugin in development, our GIF2HTML5 WordPress plugin and open-source hosted app converts animated GIF images to auto-playing video elements, for massive bandwidth savings. The fact that attachment images are directly referenced in the shortcodes makes this easier than trying to parse through image markup in our content. We can attach the video representations of these GIFs as meta attributes to the images, and in rendering the shortcodes, we can just reference the attached data and output it.
  • Inline sharing buttons. We’ve added share links to each of the images on our site. Because these are inserted through a filter on a shortcode and not in the post content, it’s easy to modify them on the fly. And having this logic in template files rather in on-page javascript that runs after page load keeps our site lighter-weight, quicker to load and more interactive.
  • Photo credits. No more forgetting to attribute images! Photographers typically add credit information to the image file as IPTC metadata. We’ve added “credit” as an image meta field, and we use a filter on ‘img_shortcode_output_after_linkify’ to display it on all images.

These are all useful features which would be much more complex to try to achieve with WordPress’s out-of-the-box approach to inline media. And we’ve only begun to experiment. When images are truly handled as a first-class content type, new possibilities suggest themselves.

Tagging images with people or places? Why not add some structured microformat data to the output and see if it helps with searchability on Google. Testing alternate archive formats? It’d be easy enough to build a photo archive of images, linked to the stories they appeared in. Extracting EXIF data from your photography? It’d be easy enough to display that data in post content.

How does it work?

Screen Shot 2015-06-03 at 1.56.54 PM

First of all, like all Shortcake-enabled shortcodes this adds a screen in the Insert Media > Insert Post Element modal. You can click through the “Image” post element to get a form much like WordPress’s Media Library form:

Screen Shot 2015-06-03 at 1.57.29 PM

But what really makes the plugin powerful is that it also intercepts images inserted through the Media Library, transforming them into shortcodes and inserting those instead. Writers don’t have to do anything different than they’re already doing to take advantage of the flexibility of images as shortcodes.

And like all shortcodes with a UI in Shortcake, you get a nice, almost-WYSIWYG preview in a TinyMCE view:

Screen Shot 2015-06-03 at 2.13.31 PM

We’ve also bundled an experimental migration function and WP-CLI command with the plugin, for bulk updating of existing content to replace <img> tags in content with shortcodes where possible.

What’s next

This is the first Shortcake shortcode we’ve released publicly. We’re building out a bakery full of recipes using Shortcake to power delicious post content. We welcome contributions to Image Shortcake, and to the Shortcake project behind it. Join us for our regular Slack conversations on Mondays at 19:00 UTC, or dig into the repository and find an open issue to hack on.


Here’s where you can catch us on TV:

Want to know what’s on right now? Head over to our show lineup page.