|
| 1 | +#lazysizes RIaS extension (Responsive image as a service) |
| 2 | + |
| 3 | +The RiaS plugin enables lazySizes to hook into any third party (ReSrc, pixulate, mobify ...) or self hosted restful responsive image service. This is currently the best way to serve adaptive and or retina optimized images. |
| 4 | + |
| 5 | +The rias plugin also allows art direction by combining rias with a ``picture`` element. |
| 6 | + |
| 7 | +##Basic/quick usage |
| 8 | + |
| 9 | +* Simply add the rias plugin right after the lazysizes or concat those scripts into your script bundle: |
| 10 | + ```html |
| 11 | + <script src="../lazysizes.js"></script> |
| 12 | + <script src="../plugins/rias/ls.rias.js"></script> |
| 13 | + ``` |
| 14 | +* Add the ``lazyload`` class and the ``data-sizes="auto"`` attribute to your image and include the placeholder ``{width}`` at the point, where your image service expects the requested width of the image. |
| 15 | + ```html |
| 16 | + <img |
| 17 | + src="http://placehold.it/100" |
| 18 | + data-src="http://placehold.it/{width}" |
| 19 | + data-sizes="auto" |
| 20 | + class="lazyload" |
| 21 | + alt="" /> |
| 22 | + ``` |
| 23 | + |
| 24 | +##[Demo](http://afarkas.github.io/lazysizes/rias/) |
| 25 | +A [demo with markup and code examples can be seen here](http://afarkas.github.io/lazysizes/rias/). |
| 26 | + |
| 27 | +##Configuration/Options |
| 28 | + |
| 29 | +The rias plugin can be configured through the ``lazySizesConfig.rias`` option object, which should be configured before the lazysizes script. |
| 30 | + |
| 31 | +```js |
| 32 | +window.lazySizesConfig = window.lazySizesConfig || {}; |
| 33 | +window.lazySizesConfig.rias = window.lazySizesConfig.rias || {}; |
| 34 | + |
| 35 | +window.lazySizesConfig.rias.maxdpr = 1.8; |
| 36 | +window.lazySizesConfig.rias.encodeSrc = true; |
| 37 | +``` |
| 38 | + |
| 39 | +or element specifc with a corresponding ``data-*`` attribute: |
| 40 | + |
| 41 | +```html |
| 42 | +<img |
| 43 | + data-maxdpr="1.6" |
| 44 | + data-encodesrc="false" |
| 45 | + src="http://placehold.it/100" |
| 46 | + data-src="http://placehold.it/{width}" |
| 47 | + data-sizes="auto" |
| 48 | + class="lazyload" |
| 49 | + alt="" /> |
| 50 | +``` |
| 51 | + |
| 52 | +All rias options, which represent primitive data types (i.e.: string, numbers or boolean) can also be used as ``data-*`` attributes. |
| 53 | + |
| 54 | +###URL generation and {placeholder}s |
| 55 | + |
| 56 | +The url is dynmically generated by replacing placeholder values, which are enclosed by curly brackets. |
| 57 | + |
| 58 | +Most usefull placeholders are: |
| 59 | + |
| 60 | +* ``{width}`` represents the width of the image multiplyed by the devicePixelRatio |
| 61 | +* ``{height}`` represents the height of the image multiplyed with devicePixelRatio |
| 62 | +* ``{quality}`` represents the quality (mostly for JPEG compression) |
| 63 | +* ``{dpr}`` represents the current devicePixelRatio (Note: You won't need this often, because {width} already includes this information.) |
| 64 | + |
| 65 | +```html |
| 66 | +<img |
| 67 | + data-quality="80" |
| 68 | + src="http://placehold.it/100x50" |
| 69 | + data-src="http://placehold.it/{width}x{height}?quality={quality}" |
| 70 | + data-sizes="auto" |
| 71 | + class="lazyload" |
| 72 | + alt="" /> |
| 73 | +``` |
| 74 | + |
| 75 | +All rias options, which represent primitive data types (i.e.: string, numbers or boolean) can also be used as {placeholder} inside the url. |
| 76 | + |
| 77 | +###List of Options |
| 78 | + |
| 79 | + |
| 80 | +* ``lazySizesConfig.rias.srcsetAttr`` (default: ``"data-src"``): The attribute, which should be transformed to ``src``. |
| 81 | +* ``lazySizesConfig.rias.quality`` (default: 85): The default quality value for replacing the {quality} placeholder. |
| 82 | +* ``lazySizesConfig.rias.formats`` (``number``|``array of numbers`` or ``false``): The formats option reduces the calculated ``width`` to the allowed formats. In case of a ``number`` (i.e.: ``100``) the rias plugin will round the calculated ``width`` number. In case of an ``array`` the rias plugin will take the nearest number inside of this array. |
| 83 | +* ``lazySizesConfig.rias.hdQuality`` (default: 70): On higher resolutions it is often possible to use heavier compressed images without reducing the perceived image quality. If a retina device is used the {quality} placeholder is replaced by the ``hdQuality`` option instead of the normal ``quality`` option. |
| 84 | +* ``lazySizesConfig.rias.maxdpr`` (default: ``2``): Some images do not gain perceived image quality on higher resolution. With the ``maxdpr`` option the calculated ``width`` can be constrained. |
| 85 | +* ``lazySizesConfig.rias.absUrl`` (default: ``false``): Wether the value of the ``data-src``/``srcsetAttr`` attribute should be resolved to an absolute url. |
| 86 | +* ``lazySizesConfig.rias.encodeSrc`` (default: ``false``): Wether the value of the ``data-src``/``srcsetAttr`` should be encoded using ``encodeURIComponent`` |
| 87 | +* ``lazySizesConfig.rias.modifyOptions`` (default: ``function`` noop ): A ``function`` that gets the option as first and the corresponding ``img`` elment as the second argument. Can be used to modify existing options/placholder values or to add new placeholder values. |
| 88 | + |
| 89 | + ```js |
| 90 | + window.lazySizesConfig = window.lazySizesConfig || {}; |
| 91 | + window.lazySizesConfig.rias = window.lazySizesConfig.rias || {}; |
| 92 | + |
| 93 | + window.lazySizesConfig.rias.formats = [320, 640, 940]; |
| 94 | + window.lazySizesConfig.rias.modifyOptions = function(opts, img){ |
| 95 | + var widthMap = { |
| 96 | + 320: 'small', |
| 97 | + 640: 'medium', |
| 98 | + 940: 'large' |
| 99 | + }; |
| 100 | + return widthMap[opts.width]; |
| 101 | + }; |
| 102 | + ``` |
| 103 | + |
| 104 | +* ``lazySizesConfig.rias.modifySrc`` (default: ``function`` noop ): A function that gets passed the generated src, the ``img``/``source`` element and the option object. The function can modify/change the generated src and return it. |
| 105 | +* ``lazySizesConfig.rias.prefix`` (default: ``""``): A string, which is prepended to the generated src. |
| 106 | + ```html |
| 107 | + <script> |
| 108 | + window.lazySizesConfig = window.lazySizesConfig || {}; |
| 109 | + window.lazySizesConfig.rias = { |
| 110 | + prefix: 'http://placehold.it/' |
| 111 | + }; |
| 112 | + </script> |
| 113 | + <img |
| 114 | + src="http://placehold.it/100" |
| 115 | + data-src="{width}" |
| 116 | + data-sizes="auto" |
| 117 | + class="lazyload" |
| 118 | + alt="" /> |
| 119 | + ``` |
| 120 | +* ``lazySizesConfig.rias.postfix`` (default: ``""`` ): A string, which is appended to the generated src. |
0 commit comments