Progress will discontinue Telerik Platform on May 10th, 2018. Learn more

Processing HTML Elements

Processing HTML Elements

After setting up HTML tags for use with offline files, you need to process them. Processing outputs standards-based HTML elements that point to updated resources depending on the processed HTML tag.

The Backend Services JavaScript SDK provides methods for these operations:

The article also covers these topics:

Processing the Whole Document

Requesting the processing of the entire document searches for every element that has custom HTML 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. It 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.
}

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.

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;
});

Best Practices

Following certain principles when processing HTML elements for offline usage can save you work and troubleshooting time.

Preventing Multiple Processing

Invoking processAll repeatedly on already processed elements can lead to downgraded performance and unwanted UI behavior.

This can happen, for example, in a list view that loads images on demand as the user scrolls down. If you invoke processAll every time a new batch of items loads, all previous elements are processed in addition to the new elements.

Repeated processing can be prevented by marking previously processed elements. For example:

el.helpers.html.processAll().then(function(results) {
    results.processed.forEach(function(result) {
        var element = result.element;
        element.dataset.offline = false;
        element.dataset.responsive = false;
        //these elements will not be reprocessed by processAll
    });
});

Always Use Loading and Error Images Together

Although you can specify data-loading-image and data-error-image separately, 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

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