resources/src/jquery/jquery.hidpi.js

   1 /**
   2  * Responsive images based on `srcset` and `window.devicePixelRatio` emulation where needed.
   3  *
   4  * Call `.hidpi()` on a document or part of a document to proces image srcsets within that section.
   5  *
   6  * `$.devicePixelRatio()` can be used as a substitute for `window.devicePixelRatio`.
   7  * It provides a familiar interface to retrieve the pixel ratio for browsers that don't
   8  * implement `window.devicePixelRatio` but do have a different way of getting it.
   9  *
  10  * @class jQuery.plugin.hidpi
  11  */
  12 ( function ( $ ) {
  13
  14 /**
  15  * Get reported or approximate device pixel ratio.
  16  *
  17  * - 1.0 means 1 CSS pixel is 1 hardware pixel
  18  * - 2.0 means 1 CSS pixel is 2 hardware pixels
  19  * - etc.
  20  *
  21  * Uses `window.devicePixelRatio` if available, or CSS media queries on IE.
  22  *
  23  * @static
  24  * @inheritable
  25  * @return {number} Device pixel ratio
  26  */
  27 $.devicePixelRatio = function () {
  28         if ( window.devicePixelRatio !== undefined ) {
  29                 // Most web browsers:
  30                 // * WebKit/Blink (Safari, Chrome, Android browser, etc)
  31                 // * Opera
  32                 // * Firefox 18+
  33                 // * Microsoft Edge (Windows 10)
  34                 return window.devicePixelRatio;
  35         } else if ( window.msMatchMedia !== undefined ) {
  36                 // Windows 8 desktops / tablets, probably Windows Phone 8
  37                 //
  38                 // IE 10/11 doesn't report pixel ratio directly, but we can get the
  39                 // screen DPI and divide by 96. We'll bracket to [1, 1.5, 2.0] for
  40                 // simplicity, but you may get different values depending on zoom
  41                 // factor, size of screen and orientation in Metro IE.
  42                 if ( window.msMatchMedia( '(min-resolution: 192dpi)' ).matches ) {
  43                         return 2;
  44                 } else if ( window.msMatchMedia( '(min-resolution: 144dpi)' ).matches ) {
  45                         return 1.5;
  46                 } else {
  47                         return 1;
  48                 }
  49         } else {
  50                 // Legacy browsers...
  51                 // Assume 1 if unknown.
  52                 return 1;
  53         }
  54 };
  55
  56 /**
  57  * Bracket a given device pixel ratio to one of [1, 1.5, 2].
  58  *
  59  * This is useful for grabbing images on the fly with sizes based on the display
  60  * density, without causing slowdown and extra thumbnail renderings on devices
  61  * that are slightly different from the most common sizes.
  62  *
  63  * The bracketed ratios match the default 'srcset' output on MediaWiki thumbnails,
  64  * so will be consistent with default renderings.
  65  *
  66  * @static
  67  * @inheritable
  68  * @return {number} Device pixel ratio
  69  */
  70 $.bracketDevicePixelRatio = function ( baseRatio ) {
  71         if ( baseRatio > 1.5 ) {
  72                 return 2;
  73         } else if ( baseRatio > 1 ) {
  74                 return 1.5;
  75         } else {
  76                 return 1;
  77         }
  78 };
  79
  80 /**
  81  * Get reported or approximate device pixel ratio, bracketed to [1, 1.5, 2].
  82  *
  83  * This is useful for grabbing images on the fly with sizes based on the display
  84  * density, without causing slowdown and extra thumbnail renderings on devices
  85  * that are slightly different from the most common sizes.
  86  *
  87  * The bracketed ratios match the default 'srcset' output on MediaWiki thumbnails,
  88  * so will be consistent with default renderings.
  89  *
  90  * - 1.0 means 1 CSS pixel is 1 hardware pixel
  91  * - 1.5 means 1 CSS pixel is 1.5 hardware pixels
  92  * - 2.0 means 1 CSS pixel is 2 hardware pixels
  93  *
  94  * @static
  95  * @inheritable
  96  * @return {number} Device pixel ratio
  97  */
  98 $.bracketedDevicePixelRatio = function () {
  99         return $.bracketDevicePixelRatio( $.devicePixelRatio() );
 100 };
 101
 102 /**
 103  * Implement responsive images based on srcset attributes, if browser has no
 104  * native srcset support.
 105  *
 106  * @return {jQuery} This selection
 107  * @chainable
 108  */
 109 $.fn.hidpi = function () {
 110         var $target = this,
 111                 // TODO add support for dpi media query checks on Firefox, IE
 112                 devicePixelRatio = $.devicePixelRatio(),
 113                 testImage = new Image();
 114
 115         if ( devicePixelRatio > 1 && testImage.srcset === undefined ) {
 116                 // No native srcset support.
 117                 $target.find( 'img' ).each( function () {
 118                         var $img = $( this ),
 119                                 srcset = $img.attr( 'srcset' ),
 120                                 match;
 121                         if ( typeof srcset === 'string' && srcset !== '' ) {
 122                                 match = $.matchSrcSet( devicePixelRatio, srcset );
 123                                 if ( match !== null ) {
 124                                         $img.attr( 'src', match );
 125                                 }
 126                         }
 127                 } );
 128         }
 129
 130         return $target;
 131 };
 132
 133 /**
 134  * Match a srcset entry for the given device pixel ratio
 135  *
 136  * Exposed for testing.
 137  *
 138  * @private
 139  * @static
 140  * @param {number} devicePixelRatio
 141  * @param {string} srcset
 142  * @return {Mixed} null or the matching src string
 143  */
 144 $.matchSrcSet = function ( devicePixelRatio, srcset ) {
 145         var candidates,
 146                 candidate,
 147                 bits,
 148                 src,
 149                 i,
 150                 ratioStr,
 151                 ratio,
 152                 selectedRatio = 1,
 153                 selectedSrc = null;
 154         candidates = srcset.split( / *, */ );
 155         for ( i = 0; i < candidates.length; i++ ) {
 156                 candidate = candidates[ i ];
 157                 bits = candidate.split( / +/ );
 158                 src = bits[ 0 ];
 159                 if ( bits.length > 1 && bits[ 1 ].charAt( bits[ 1 ].length - 1 ) === 'x' ) {
 160                         ratioStr = bits[ 1 ].slice( 0, -1 );
 161                         ratio = parseFloat( ratioStr );
 162                         if ( ratio <= devicePixelRatio && ratio > selectedRatio ) {
 163                                 selectedRatio = ratio;
 164                                 selectedSrc = src;
 165                         }
 166                 }
 167         }
 168         return selectedSrc;
 169 };
 170
 171 /**
 172  * @class jQuery
 173  * @mixins jQuery.plugin.hidpi
 174  */
 175
 176 }( jQuery ) );