Skip to content

Once is enough. A responsive images workflow solution.

21 July 2016

In Kyoto, I had a wonderful dinner, thanks to a precognitive waitress. She tailored my dining experience to my needs and context. Sending responsive images to a site user shows a similar level of professional courtesy.

In Kyoto recently, I had a wonderful dining experience thanks to a precognitive waitress. She was attentive to my needs. As my empty water glass touched the table, she would be there, with a refill of ice water. I caught sight of her hand reach for the western style cutlery when I fumbled my yakitori tofu. The waitress paused a moment, then retracted her hand when my chopstick skills returned. All in all, she delivered an outstanding customer experience. 

Delivering responsive images in a contemporary website is similar. Developers and designers must be attentive to the needs and contexts of our site users.

Often we when talk about the "needs of our site users", we focus on the needs of our customers, who are using the public-facing side of a website. They're important. However, they're not the only people who use the sites we build. Our internal content production teams also use the sites we build, and the success of site often depends more on satisfying their needs. The needs of a content production team are a key consideration in my solution for a responsive images workflow.

Courtesy for web developers.

My waitress in Kyoto tailored my dining experience. Please pardon the obvious example - She set my table for one. Not for four people.

It might seem like an obvious discourtesy, yet many websites still send massive 2MB images to users with mobile devices. 

Sending excessively large images is a poor customer experience. We send smaller images to small phone screens, and we send high resolution images to luscious 4K desktop screens. It's good manners for web developers.

However it's a surprisingly tricky feat to implement responsive images for a real-world corporate environment workflow. 

Once is the magic number.

An organisation large enough to require a content production team would utilise a CMS, such as Joomla, WordPress, Drupal, SiteCore, et al.

The current generation of CMS engines generally lack a sensible system for incorporating responsive images:

  • Banner, header, and intro images typically only allow one image URL to be saved to the CMS' database
  • WYSIWYG editors typically provide an interface to insert a single image into a page of content
  • WYSIWYG editors normally (but not always) allow users to edit the HTML source code

Responsive images require four things:

  • Multiple versions of the same image
  • HTML code which tells the browser which images are available
  • A fallback image
  • A textual description for the benefit of screen reader devices 

An organisation large enough to require a content production team would also require that team to work efficiently.

Current workplace solutions for responsive images tend to expect its content production to blow-out their efficiency by either manually creating multiple images for every image they use, and/or manually creating or editing the HTML code. Either way, the workload for the content production team explodes unsustainably.

(Historically, developers attempted to solve this issue by resizing images on the fly, to minimise the file weight being received by the user. It was a great solution until folks realised how much the server had to work to deliver the goods).

The key requirement for my responsive images is simple: One image, once. That's it.

A member of the content production team uploads the image once into the CMS. The content production team does no additional coding - they're not coders. The site user receives one image of an appropriate size for their device. 

One image, once. That's it.

Images account for the vast bulk of a site’s raw file weight. Anything a designer and developer can do to reduce the impact of images on the end user - especially mobile users - becomes a high priority. Any undue file weight of a site can adversely affect its ranking in the search engines. 

So I developed a system which will process an image into a variety of sizes (or resolutions); allow a user to upload an image into the CMS as normal; then generate the HTML code to correctly handle the various responsive images. A human must not be responsible for the responsive image HTML.

Note: This automation only applies to images administered via the CMS. Images which the content production team adds directly into an article is not part of this workflow. That's for future development work.

The details.

The solution scales the web development stack. It stretches from the CMS admin interface (Joomla, in this case), down to the server where Grunt processes the images using GraphicsMagick, then into PHP (in the form of module overrides for Joomla), and finally rendered into HTML and CSS.

The PHP file contains a short list of constants; their values are paired to the media query breakpoints held as variables in SCSS. 

Media queries


  • define("SCREEN_XS", "480");
  • define("SCREEN_SM", "768");
  • define("SCREEN_MD", "1024");
  • define("SCREEN_LG", "1400");

These constants are based on media query breakpoints.


  • $screen-xs: 480px;
  • $screen-sm: 768px;
  • $screen-md: 1024px;
  • $screen-lg: 1400px;

These constants are based on media query breakpoints.

Image resizing

A second set of constants which control the image resizing. There's a set of folders in Joomla's images directory, paired to values within the site's gruntfile.js manifest.


  • 600px
  • 800px
  • 1400px
  • 2000px

These constants are conveniently larger than the media query breakpoints. 

Joomla images folder

  • /600px
  • /800px
  • /1400px
  • /2000px
  • /Upload_2000px

To start the process, a content production team user uploads an image into the Upload_2000px folder. The user inserts a link to an image in the Upload_2000px folder into their document.

Grunt.js watches that folder and when it detects a new file, it instructs GraphicsMagick to clone and resize the image into the other folders. 

The CMS holds a single simple reference to the Upload_2000px image in the CMS' database. 

The actual PHP functions are quite simple - just string replace and concatenation to construct a valid HTML5 picture element (or img element) when requested by the site's front-end.

A content production team member can still provide an art-directed image, if necessary. They can directly overwrite an image saved in the /600px folder, for example.


The following code can be placed inside a Joomla module override file. As such, the actual functions are written in PHP.


<?php echo createPictureSources(htmlspecialchars($images->image_intro), "1400px, 800px, 600px"); ?>

<?php echo createImageSrc(htmlspecialchars($images->image_intro), "600px", "", $item->title); ?>


You'll notice there are two functions - createPictureSources and createImageSrc. The output syntax is sufficiently different between the two to warrant separate functions.

A similar function also helps with the site’s logo - it receives a URL for an image and seeks a .svg in the same location. 


Refinement of this responsive images workflow could include the following:

  • Increase consistency of syntax across the family of functions
  • Complete documentation of the functions
  • Consistent application of class and alt text across all functions
  • Better bulletproofing of code
  • Expand functions to handle retina images, and emerging formats such as .webp
  • Complete re-write of PHP functions into Joomla (or equivalent CMS) plugin architecture


That waitress in Kyoto? She made delivering a perfect customer experience look effortless. In reality, there's a lot of work which needs to happen behind the scenes.

Let me finish by telling you about another experience I had during my Japan travels. I spend two weeks helping in the kitchen of a hostel in exchange for food and accommodation - a great way to travel!

Working in that kitchen though - it was a filthy nightmare. The chef was horrified that I would use detergent in every load of dishes I washed. There was one dish sponge - for raw meats, cutlery, crockery, pots, pans. Drying cloths got washed once a week or so. Filthy. It was the only option available for guests - we were a long way from anywhere else. They had to eat there - and the was tasty. But if you saw the state of the kitchen, you'd likely be motivated to find food elsewhere.

I left there with a genuine appreciation for the amount of effort it takes to start and maintain a system of restaurant-quality hygiene, to train your team, and to maintain those standards every single day.

Serving responsive images to site visitors, without exploding your team's workload, can involve significant effort behind the scenes. It's worth the effort to deliver a sensational customer experience to your site's visitors, wouldn't you agree?