responsive_image_tag

= responsive_image_tag

== Creating responsive images

It's quite common today for web sites to be viewed on a wide range of devices, from powerful desktop workstations with huge screen resolutions and plenty of bandwidth, to tiny resource-constrained mobile devices. Serving images to this wide range of clients becomes an issue: if you make your images large, you'll severely degrade performance on mobile phones, but if you make your images small, they'll look terrible to desktop users.

Wouldn't it be nice if you could serve small images to mobile clients, and large images to desktop clients? The HTML spec doesn't really allow for device-specific asset serving, but it can be done with a little dash of cleverness. The technique used here allows you to serve device-specific images, and not make two server requests (saving bandwidth and server load).

We've packaged it up as a rubygem.

responsive_image_tag is a Rails helper which selects an image depending on the width of the current device. The screen.width is detected by javascript and then an image element is inserted in the page with a dynamically created src attribute.

It works with Rails 2 and Rails 3, and there are javascript adapters for both jQuery and Prototype. Pick your poison.

== Motivation and approach

You can find out what problems we're trying to solve with this code by reading the blog post about it here[http://headlondon.com/our-thoughts/technology/posts/creating-responsive-images-using-the-noscript-tag].

Although this is packaged as a ruby gem, the approach is generally valid across platforms, and as a bonus, it is accessible - screenreaders and web crawlers will see the content of the tag, and parse the content quite happily.

== HTML structure

Here's the HTML which the helper inserts into the page:

The responsive images have to appear for non-javascript users as well as those with javascript turned on.

To achieve this the helper places the default image inside a tag which is then deleted by the javascript library. The image attributes such as full size, mobile size and alt text are also stored as HTML5 data attributes on the tag so they are available in the DOM for the javascript to access.

The library relies on a trick which has all the elegance of a greasy late-night kebab: child elements of the tag are not added to the DOM, so deleting the prevents an HTTP request being made to the server. This way only the image being requested by the dynamically inserted image tag is making a request.

To insert the dynamically created image element into the page you need a parent element in the DOM to append to. The rails helper also creates a tag with a class of "img-placeholder" to house the new image.

When the DOM is ready the javascript object responsiveImageTag detects all elements on the page with a class of "responsivize".

It retrieves the HTML5 data attributes (data-mobilesrc, data-fullsrc, and data-alttext) and then creates an image tag with the correct source depending on the available screen width of the users device. Any device smaller than 768px is considered to be a mobile device. The library inserts the new element into the page and the tags are then hidden from view.

== Installation

Put it in your Gemfile:

gem 'responsive_image_tag'

Then install it:

bundle install

There's a generator which copies a JavaScript file into place in public/javascripts.

You can run it like this:

=== Rails 3

rails g responsive_image_tag:copy_js

=== Rails 2

script/generate responsive_image_tag *Currently untested

=== Padrino

padrino g copy_rit_js

Options:

-d, [--js_destination] The destination path to copy the Javascript file too. Default: 'public/javascripts'

== Usage

You need to do two things. First, make sure that you include a reference to the JavaScript file in your layout:

<%= javascript_include_tag "responsive-image-tag" %>

After that, you can use the new tag like so, in a view:

<%= responsive_image_tag("small.jpg", "big.jpg", :alt => "Alt text", :class => "css-class") %>

This will output HTML like so:

$(".responsivize").responsiveImageTag();

Optional CSS class for the images, otherwise it will add 'responsive'.

$(".responsivize").responsiveImageTag({cssClass: "scale-with-grid"});

== Contributing to responsive_image_tag

• Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
• Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
• Fork the project
• Start a feature/bugfix branch
• Commit and push until you are happy with your contribution
• Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
• Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

== Copyright

Copyright (c) 2011 Headlondon, http://www.headlondon.com

Authors: Dave Hrycyszyn, Mairead Buchan

See LICENSE.txt for further details.