Skip to content

Latest commit

 

History

History

rias

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
README.md
README.md
 
 
ls.rias.js
ls.rias.js
 
 
ls.rias.min.js
ls.rias.min.js
 
 

README.md

lazySizes RIaS extension (Responsive image as a service / Responsive image on demand)

The RiaS plugin enables lazySizes to generate the best suitable image source based on an URL pattern. It works with pre-build images (i.e. grunt-responsive-images) as also with any third party (ReSrc, Pixtulate, mobify, WURFL's Image Tailor ...) or self hosted restful responsive image services (responsive image on demand).

In general the RIaS plugin combines the simplicity of the famous Imager.js solution with the future power of native responsive images implementations and the webcomponent-like working of lazySizes' .lazyload elements (self-initialization, self-configuration and self-destroying).

In case the browser does support srcset the RIaS plugin will also produce a list of source candidates so that any current and future improvements (low bandwidth, metered bandwidth, user preferences, browser zoom etc.) to the native responsive image support is automatically exploited.

The RiaS plugin also allows art direction by combining placeholder URLs with a picture element.

Basic/quick usage

  • Add the RiaS plugin right before the lazySizes script or concat those scripts into your script bundle:
<!-- include lazysizes + rias extension -->
<script src="../plugins/rias/ls.rias.js"></script>
<script src="../lazysizes.js"></script>
  • 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.
<img
	data-src="http://placehold.it/{width}"
	data-sizes="auto"
	class="lazyload"
	alt="" />

<img
    data-src="http://wit.wurfl.io/w_{width}/http://wurfl.io/assets/sunsetbeach.jpg"
	data-sizes="auto"
	class="lazyload"
	alt="" />

Demo

A demo with markup and code examples can be seen here.

Configuration/Options

The RIaS plugin can be configured through the lazySizesConfig.rias option object, which should be configured before the lazySizes script.

window.lazySizesConfig = window.lazySizesConfig || {};
window.lazySizesConfig.rias = window.lazySizesConfig.rias || {};

// configure available widths to replace with the {width} placeholder
window.lazySizesConfig.rias.widths = [320, 480, 640, 960];
window.lazySizesConfig.rias.absUrl = true;

or element specific and declarative with corresponding data-* attributes:

<img
    data-widths="[160, 320]"
    data-absurl="false"
    data-src="http://placehold.it/{width}"
    data-sizes="auto"
    class="lazyload"
    alt="" />

or element specific and functional using the lazyriasmodifyoptions event.

<script>
document.addEventListener('lazyriasmodifyoptions', function(event){
    // event.detail referes the placeholders/options and event.target the corresponding element
    event.detail.quality = (window.devicePixelRatio || 1) > 1.9 ? 50 : 80;
});
</script>
<img
    data-src="image-w{width}-q{quality}.jpg"
    data-sizes="auto"
    class="lazyload"
    alt="" />

All rias options can also be used as data-* attributes.

URL generation and {placeholder}s

The url is dynamically generated by replacing placeholder values, which are enclosed by curly brackets.

All RiAS options can also be used as a {placeholder} inside the url.

List of Options

  • lazySizesConfig.rias.srcAttr (default: "data-src"): The attribute, which should be transformed to src/srcset. (The extension will also automatically check the lazySizesConfig.srcsetAttr and lazySizesConfig.srcAttr)

  • lazySizesConfig.rias.widths (array of numbers): The widths option reduces the calculated width to the allowed widths. The numeric width can also be simply mapped to a string (i.e.: small, medium, large) using the widthmap option. The default value is the following array: [180, 360, 540, 720, 900, 1080, 1296, 1512, 1728, 1944, 2160, 2376, 2592, 2808, 3024].

  • lazySizesConfig.rias.widthmap ({}): The widthmap option allows you to simply transform a numeric width to a string.

    window.lazySizesConfig = window.lazySizesConfig || {};
window.lazySizesConfig.rias = window.lazySizesConfig.rias || {};

window.lazySizesConfig.rias.widths = [320, 640, 940];
window.lazySizesConfig.rias.widthmap = {
    320: 'small',
    640: 'medium',
    940: 'large'
};

  • lazySizesConfig.rias.modifyOptions (default: function noop ): A function that gets an data object passed with the options as the details and the corresponding img element as the target. Can be used to modify existing options/placeholder values or to add new placeholder values. An event with the name lazyriasmodifyoptions is also fired at the element.

    <script>
window.lazySizesConfig = window.lazySizesConfig || {};
window.lazySizesConfig.rias = window.lazySizesConfig.rias || {};
window.lazySizesConfig.rias.modifyOptions = function(data){
    //create higher compressed images on HighDPI devices:
    data.detail.quality = (window.devicePixelRatio || 1) > 1.9 ? 50 : 80;
};
</script>
<img
    data-src="image-w{width}-q{quality}.jpg"
    data-sizes="auto"
    class="lazyload"
    alt="" />

  • lazySizesConfig.rias.absUrl (default: false): Wether the value of the data-src attribute should be resolved to an absolute url. The value must not contain any placeholders in this case. Use in conjunction with prefix and/or postfix option.

    <script>
    window.lazySizesConfig = window.lazySizesConfig || {};
    window.lazySizesConfig.rias = {
        prefix: 'http://wit.wurfl.io/w_{width}/',
        absUrl: true
    };
</script>

<img
    data-src="assets/sunsetbeach.jpg"
    data-sizes="auto"
    class="lazyload"
    alt="" />

  • lazySizesConfig.rias.prefix (default: ""): A string, which is prepended to the generated src.

    <script>
window.lazySizesConfig = window.lazySizesConfig || {};
window.lazySizesConfig.rias = {
    prefix: 'http://placehold.it/'
};
</script>
<img
    data-src="{width}"
    data-sizes="auto"
    class="lazyload"
    alt="" />

  • lazySizesConfig.rias.postfix (default: "" ): A string, which is appended to the generated src.

With lazySizes + RIaS extension you have a script to rule them all. You won't need to include a script provided by a third party image on demand service.

Dynamically calculating the height of image elements

You can provide a apsectratio option which then will be used to dynamically replace {height} placeholders.

<img
    data-src="{width}x{height}}"
    data-aspectratio="2"
    data-sizes="auto"
    class="lazyload"
    alt="" />

In case your image has CSS defined width and height dimensions you can provide this dynamically:

document.addEventListener('lazyriasmodifyoptions', function(e) {
    e.detail.aspectratio = e.target.offsetWidth / e.target.offsetHeight;
});

Advanced Examples

Embedding via CDN and combohandler

In case you want to use a CDN you can use jsDelivr's combohandler service:

<script src="http://cdn.jsdelivr.net/g/lazysizes(lazysizes.min.js+plugins/rias/ls.rias.min.js)" async=""></script>

Using art direction

In case you want to use art direction simply also use placeholder urls inside of your source[data-srcset] or source[data-src] attributes.

<picture>
    <!--[if IE 9]><audio><![endif]-->
    <source
            data-srcset="http://placehold.it/{width}/1111ee/fff"
            media="(max-width: 500px)" />
    <source
            data-srcset="http://placehold.it/{width}/e8117f/fff"
            media="(max-width: 1090px)" />
    <source
            data-srcset="http://placehold.it/{width}/7D26CD/fff"
            media="(min-width: 1224px)" />
    <source
            data-srcset="http://placehold.it/{width}"
             />
    <!--[if IE 9]></audio><![endif]-->
    <img
        src="http://placehold.it/100"
        data-sizes="auto"
        class="lazyload"
        alt="" />
</picture>

Using different widths options for different images

Often you will have different image formats with different allowed available widths. This can be configured in two ways:

Descriptive way the data-widths attribute

<img
        data-srcset="http://placehold.it/{width}"
        data-widths="[320, 480, 640]"
        data-sizes="auto"
        class="lazyload"
        alt="" />

<img
        data-srcset="http://placehold.it/{width}"
        data-widths="[640, 800, 960]"
        data-sizes="auto"
        class="lazyload"
        alt="" />

Scripted way using the lazyriasmodifyoptions event

<script>
document.addEventListener('lazyriasmodifyoptions', (function(){
    var formats = {
        full: [640, 800, 960, 1280, 1600],
        content: [320, 480, 640]
    };
    return function(e){
       var format = e.target.getAttribute('data-format');
       if(formats[format]){
           e.detail.widths = formats[format];
       }
   };
})());
</script>

<img
    data-src="http://placehold.it/{width}"
    data-format="full"
    data-sizes="auto"
    class="lazyload"
    alt="" />

<img
    data-src="http://placehold.it/{width}"
    data-format="content"
    data-sizes="auto"
    class="lazyload"
    alt="" />

Overriding existing placeholders or Extending new placeholders

The RIaS plugin is highly flexible in extending possible {placeholder} values. Each {placeholder} will be tried to be replaced by searching it in the lazySizesConfig.rias option object or by searching for a corresponding data-* attribute.

Additionally the modifyOptions callback or the equivalent lazyriasmodifyoptions event can be used to generate new or modify existing placeholders:

Using data-* to override an existing placeholder:

<img
    data-widths="[160, 320]"
    data-src="http://placehold.it/{width}"
    data-sizes="auto"
    class="lazyload" />

Using data-* to define a new placeholder:

<img
    data-custom="foo"
    data-src="http://placehold.it/{width}/{custom}"
    data-sizes="auto"
    class="lazyload" />

Using the lazySizesConfig.rias object to define a new placeholder:

<script>
window.lazySizesConfig = window.lazySizesConfig || {};
window.lazySizesConfig.rias = {
    custom: 'test',
    dynCustom: function(elem, opts){
        return 'computed-something';
    }
};
</script>
<img
    data-src="http://placehold.it/{width}/{custom}/{dynCustom}"
    data-sizes="auto"
    class="lazyload"
    alt="" />

Using the lazyriasmodifyoptions event to define or change a placeholder object:

<script>
document.addEventListener('lazyriasmodifyoptions', function(e){
    // change available widths and widthmap for .special-widths elements
    if($(e.target).is('.special-widths')){
        // (Note: With version 1.1.0 the ``details`` property will be renamed to ``detail``.)
        e.detail.widths = [320, 480, 600];
        e.detail.widthmap = {
              320: 'small',
              480: 'medium',
              600: 'large'
         };
    }

    //add new custom property with value 'foo'
    e.detail.custom = 'foo';

    e.detail.quality = (window.devicePixelRatio || 1) > 1.9 ? 50 : 80;
});
</script>
<img
    data-src="image-w{width}-w{custom}-q{quality}.jpg"
    data-sizes="auto"
    class="lazyload special-widths"
    alt="" />

Tip: Constraining the pixel density for a generated srcset attribute.

In case you don't want to generate additional compressive images for high resolution displays you can combine the RIaS extension with the optimumx extension to constrain the maximum pixel density for the generated srcset list.

<script src="http://cdn.jsdelivr.net/g/lazysizes(lazysizes.min.js+plugins/rias/ls.rias.min.js+plugins/optimumx/ls.optimumx.min.js)" async=""></script>


<img
    data-src="image-width-{width}.jpg"
    data-optimumx="1.6"
    data-sizes="auto"
    class="lazyload" />