Add support for Retina displays when using element attribute "ng-src"
Replaces the AngularJS directive
ng-srcby a version which supports Retina displays.
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.
If you prefer to host Javascript files locally instead of using a CDN, install them with:
npm install angular-retina
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.1or later.
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="..."and/or
height="..."becomes mandatory, as the displayed image otherwise gets scaled to its double size.
Just use it in your HTML-code as you would use the common AngularJS directive ngSrc:
When this library was written, Apple Inc. recommended to use
@2xas infix, for images optimized for Retina displays. In late 2013, they changed their mind, and now suggest to use the infix
_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– but of course only, if the server-side also supports it!
my_app.config(function(ngRetinaProvider) { ngRetinaProvider.setInfix('_2x'); });
To hide (
opacity: 0) images until the library has determined what resolution to use, set the
srcand the image has finished downloading, use the following config:
my_app.config(function(ngRetinaProvider) { ngRetinaProvider.setFadeInWhenLoaded(true); });
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, so the automatic detection of image URL would fail.
The solution is to supply the high-resolution URL image from the outside of the library using the
data-at2xattribute:
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:
.+ High resolution:
@2x.
If the browser runs on a high-resolution display, and if the referenced image is available in high-resolution, the corresponding
tag is interpreted, such that the image in high-resolution is referenced.
This module can also be used to reference static image urls, to load the high resolution version on Retina displays.
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-srccan be loaded from the same domain as the main HTML file.
setInfixto configure the used infix for Retina images.
© 2015 Jacob Rief
MIT licensed.