Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Browse files

Added data-at2x support and hints about Rails usage to README.

  • Loading branch information...
commit 14ed9cca6130f32993809000dc791c9a29667e75 1 parent 71778f3
@ronny ronny authored
Showing with 41 additions and 1 deletion.
  1. +41 −1
@@ -10,16 +10,26 @@ retina.js makes it easy to serve high-resolution images to devices with retina d
When your users load a page, retina.js checks each image on the page to see if there is a high-resolution version of that image on your server. If a high-resolution variant exists, the script will swap in that image in-place.
-The script assumes you use Apple's prescribed high-resolution modifier (@2x) to denote high-resolution image variants on your server.
+The script assumes you use Apple's prescribed high-resolution modifier (@2x) to denote high-resolution image variants on your server. It is also possible to override this by manually specifying the URL for the @2x images using `data-at2x` attributes.
For example, if you have an image on your page that looks like this:
<img src="/images/my_image.png" />
The script will check your server to see if an alternative image exists at this path:
+However, if you have:
+ <img src="/images/my_image.png" data-at2x="" />
+The script will use `` as the high-resolution image. No checks to the server will be performed.
##How to use
@@ -71,6 +81,36 @@ Will compile to:
+### Ruby on Rails 3.x
+...or any framework that embeds some unique hash to the asset URLs, e.g. `/images/image-{hash1}.jpg`.
+The problem with this is that the high-resolution version would have a different hash, and would not conform the usual pattern, i.e. `/images/image@2x-{hash2}.jpg`. So automatic detection would fail because retina.js would check the existence of `/images/image-{hash1}@2x.jpg`.
+There's no way for retina.js to know beforehand what the high-resolution image's hash would be without some sort of help from the server side. So in this case, the suggested method is to supply the high-resolution URLs using the `data-at2x` attributes as previously described in the How It Works section.
+In Rails, one way to automate this is using a helper, e.g.:
+ # in app/helpers/some_helper.rb or app/helpers/application_helper.rb
+ def image_tag_with_at2x(name_at_1x, options={})
+ name_at_2x = name_at_1x.gsub(%r{\.\w+$}, '@2x\0')
+ image_tag(name_at_1x, options.merge("data-at2x" => asset_path(name_at_2x)))
+ end
+And then in your views (templates), instead of using image_tag, you would use image_tag_with_at2x, e.g. for ERB:
+ <%= image_tag_with_at2x "logo.png" %>
+It would generate something like:
+ <img src="logo-{hash1}.png" data-at2x="logo@2x-{hash2}.png" />
##How to test
We use [mocha]( for unit testing with [should]( assertions. Install mocha and should by running `npm install`.

0 comments on commit 14ed9cc

Please sign in to comment.
Something went wrong with that request. Please try again.