angular-retina

Replaces the AngularJS directive

ng-src

If the browser runs on a Retina display and the referenced image is available in double resolution, then load the high resolution version of that image from the server.

Install

If you prefer to host Javascript files locally instead of using a CDN, install them with:

npm install angular-retina

Client usage

Into the main HTML code, add the required URLs from the CDN or include the files locally:

Please note, that angular-retina requires

angularjs-1.2.1

In Javascript, initialize the main module for your AngularJS application:

var my_app = angular.module('MyApp', [...other dependencies..., 'ngRetina']);

In the body of any HTML code, access static referenced images using:

or reference the image using AngularJS's markup:

Note that when using this module, adding the element attributes

width="..."

height="..."

Just use it in your HTML-code as you would use the common AngularJS directive ngSrc:

Alternative infix

When this library was written, Apple Inc. recommended to use

@2x

_2x

Since Apple's former recommendation, the proposed infix has been hard coded into some server-side libraries for image generation. Therefore, in version 0.3.0 of angular-retina, a configuration function has been added, which shall be used to set the infix to the newly proposed

_2x

my_app.config(function(ngRetinaProvider) {
    ngRetinaProvider.setInfix('_2x');
});

Hide images until loaded, avoiding "broken image" display

To hide (

opacity: 0

src

my_app.config(function(ngRetinaProvider) {
    ngRetinaProvider.setFadeInWhenLoaded(true);
});

Images with embedded hash

When using a framework that embeds a digest/hash to the asset URL, the problem is that a high-resolution verison would have a different hash and would not follow the usual pattern that ends with @2x. Instead the hash is added at the end, i.e.

/images/[email protected]{hash2}.jpg

The solution is to supply the high-resolution URL image from the outside of the library using the

data-at2x

On the server

Applications supporting Retina displays should include two separate files for each image resource. One file provides a standard-resolution version of a given image, and the second provides a high-resolution version of the same image. The naming conventions for each pair of image files is as follows: + Standard:

.

@2x.

If the browser runs on a high-resolution display, and if the referenced image is available in high-resolution, the corresponding

This module can also be used to reference static image urls, to load the high resolution version on Retina displays.

Same Origin Policy

In order to verify if the image exists in high resolution, angular-retina invokes a HEAD request with the URL of the high-res image.

For security reasons, Javascript may not access files on servers starting with a different domain name. This is known as the Same Origin Policy. Therefore please ensure, that all images accessed through

ng-src

Release History

• 0.1.0 - initial revision.
• 0.1.3 - fixed problems with minified JS code.
• 0.2.0 - using sessionStorage instead of $cacheFactory to boost performance.
• 0.3.0 - added

  setInfix

  to configure the used infix for Retina images.
• 0.3.1 - added a noretina attribute support to conditionally disable the "retinification" for an element.

License

© 2015 Jacob Rief

MIT licensed.