Applying Responsive Images Automatically

Applying Responsive Images Automatically

The Backend Services JavaScript SDK extends the features of Responsive Images for a more automated experience. It detects the target container size and determines the image resize parameters for you.

If you need to, you can still use the manual approach.

The automatic approach assumes that each of your images is served using an HTML tag or a style="background-image" tag attribute. It relies on adding non-standard attributes to tags that are later used for automatic processing of the tags.

This article contains these topics:

Setting Up an IMG Tag

To make an image specified through the <img> tag use the Responsive Images service, you need to modify its tag as follows:

  • Rename the src attribute to data-src, leaving the original link address unchanged
  • Add the data-responsive attribute

You can also add optional attributes. See Table of Attributes for details.

<img data-src="http://example.com/images/image.jpg" data-responsive />

When the <img> tag is processed, the standard src attribute is added, pointing to the optimized image.

Setting Up a CSS Background Image

HTML elements using the background-image CSS property can also take advantage of Responsive Images. Simply add the data-responsive attribute:

<div style="background-image: url(http://...)" data-responsive />

When the HTML tag is processed, the url is replaced with a new one pointing to the optimized image.

Table of Attributes

The next table provides detailed information about each HTML attribute that you can use in conjunction with Responsive Images:

Attribute Description
data-src The URL of the image that you want to display
data-responsive* Specifies if the tag supports responsive images
data-offline* (Optional) Specifies if the tag supports offline mode
data-loading-image (Optional) An URL of an image that is displayed until the actual image is available. Overrides the loading URL specified in the global settings. For hybrid mobile apps this should be a local image bundled with the app package. Example: data-loading-image="http://example.com/img.jpg"
data-error-image (Optional) An URL of an image that is displayed whenever there is an error downloading or processing the actual image. Overrides the error URL specified in the global settings. For hybrid mobile apps this should be a local image bundled with the app package. Example: data-error-image="http://example.com/img.jpg"
data-dpi (Optional) Disables the Retina/HiDPI support if set to "false" or sets a custom DPI value. Example: data-dpi="1.75"
* The `data-offline` and `data-responsive` attributes can be set explicitly to true or false. For example: data-offline="true". The empty string, as well as any other string that differs from "false", are evaluated as true.

All attribute names can be configured while initializing the SDK. For more information see Configuring HTML Attributes.

Processing Images

After you set the HTML elements, you need to process them. Processing outputs standards-based HTML elements that point to updated resources depending on the processed HTML tag.

You can use these processing methods:

Processing the Whole Document

Requesting the processing of the entire document searches for every element that has custom attributes and applies the requested behavior. Use the helpers.html.processAll method to process the whole document:

el.helpers.html.processAll(
    settings,
    success,
    error
);

where:

The error callback is only invoked when an exception is thrown while processing an element. In contrast, a failure to load an image appears in the result of the success callback.

Processing a Single Element

If you need to, you can process a single HTML element using the helpers.html.process method:

el.helpers.html.process(element, settings, success, error);

where:

  • element can be:

    • Any HTML DOM element
    • A result of a jQuery selector
  • settings is an object described in Specifying Processing Settings

  • success is a success callback
  • error is an error callback

The error callback is only invoked when an exception is thrown while processing an element. In contrast, a failure to load an image appears in the result of the success callback.

Example:

var imgs = document.querySelectorAll('img');
el.helpers.html.process(imgs, settings, success, error);

JQuery Selector example:

el.helpers.html.process($('#selectMe img'), settings, success, error);

Processing a List of Elements

You can specify a list of HTML elements to process in a single request:

el.helpers.html.process(elements, settings, success, error);

where:

  • elements can be:

    • An array of HTML DOM elements
    • An HTMLCollection
    • A result of a jQuery selector
  • settings is an object described in Specifying Processing Settings

  • success is a success callback
  • error is an error callback

The error callback is only invoked when an exception is thrown while processing an element. In contrast, a failure to load an image appears in the result of the success callback.

Specifying Processing Settings

All the methods for processing HTML elements accept a settings object. Using the settings object you can turn off processing for Responsive Images or for Offline Mode, overriding the individual element settings. This is helpful when you want to avoid unnecessary processing and improve performance.

The settings object has the following structure:

settings = {
    offline: true, //Whether to process data-offline attributes. Default is TRUE.
    responsive: true //Whether to process data-responsive attributes. Default is TRUE.
}

Inserting Logic After Processing Elements

As an alternative to providing success and error callbacks when invoking the process methods, you can insert custom logic after the processing logic on a global level.

To do that, catch the processed event as follows:

el.helpers.html.on('processed', function(result) {

});

The result function parameter is a result object as described in Result Object Structure.

Result Object Structure

The result of the success callback contains lists of the items processed and the failed items. It has the following structure:

{
    processed: [
        {
            element: <HtmlNode>, //The HTML DOM element that was processed
            responsive: true | false, //Whether Responsive Images were processed on the element,
            offline: true | false //Whether Offline Mode was processed on the element
        },
        ...
    ],
    failed: [
        {
            element: <HtmlNode>, //The HTML DOM element that was processed
            error: <EverliveError> //An error Everlive code
        },
        ...
    ]
}

The following is an example of accessing the result's properties:

el.helpers.html.processAll().then(function (results) {
results.processed;
results.failed;
});

Always Use Loading and Error Images Together

HTML Helpers allows you to specify data-loading-image and data-error-image separately. Nevertheless, it is recommended to always use them in conjunction.

Assume you have specified a data-loading-image but you haven't specified a data-error-image. If the original image (or file) fails to load, the data-loading-image will continue to display, implying that the original image is still loading. Specifying an error image in this case lets the users know that the image will not be loaded at all.

See Also

Start a free trial Request a demo
Contact us: +1-888-365-2779
sales@telerik.com
Copyright © 2016-2017, Progress Software Corporation and/or its subsidiaries or affiliates. All rights reserved.