Delaying of Elements

Delayed images and delayed iframes can be used to enhance the performance of websites. With delayed images enabled, the page is sent without the image source URLs in the image elements. With delayed iframes enabled, the page is sent without the iframe source URLs in the iframe elements. This way the load event is triggered earlier and the website is sooner responsive. The correct elements are loaded after the load event is fired, or after the ready event is fired for delayed images with visibility setting and delayed iframes near the viewport.

Configuration

To enable delayed images in the conf/config.xml:

<config>
  <acceleration>
    <image-delaying [ prioritization=" visibility" ] [ visibility-offset-x="disabled" ] [ visibility-offset-y="150" ] />
  </acceleration>
</config>

If delayed images are activated, all images are sent delayed by default, except for:

  • images with ai-delay="false" attribute
  • images that are inlined
  • images in CSS
  • images with a picture parent node
  • images with a noscript or template ancestor node
  • clients without js support
  • clients without client/data-uri support

To enable delayed iframes in the conf/config.xml:

<config>
  <acceleration>
    <iframe-delaying [ visibility-offset-x="disabled" ] [ visibility-offset-y="150" ] />
  </acceleration>
</config>

If delayed iframes are activated, only iframes with an ai-delay="true" attribute are sent delayed. Clients without js support do not get delayed iframes.

Note: Using the delaying feature will add a data-ai-hqsrc attribute to the img and iframe elements that are delayed.

Note: Using this feature will add the class AI_delayedHidden to the class list of all delayed elements to hide them initially. The class is removed as soon as each image and iframe has been loaded.

Note: When a document is requested via Partial Page Loading images will only be delayed in case the priority is set to visibility. Delayed iframes are not affected by Partial Page Loading.

The ai-priority Attribute

The order in which delayed images are loaded after the load event occurred is determined by their ai-priority attribute. Possible Values are 0 - 3 and the special value visibility, with 3 being the earliest and 0 the latest. The default value is visibility.

If an image has an ai-priority attribute with the value visibility, it will start loading a certain amount of pixels before or after it enters the viewport, called the offset. Images that are initially visible in the viewport are loaded when the ready event is fired.

The ai-priority atribute is only applicable to delayed images. Delayed iframes are all using the visibility delaying.

Note: Offsets are separated in a horizontal (x) and a vertical (y) value. Defaults are disabled for x-axis and 150 for y-axis. Check Visibility Offsets for more information and options.

Tip: ai-priority= 0|1|2|3 can be used to ensure images in a hidden container are loaded delayed but loading has finished before the container is shown.

For example:

<img src="logo.png" ai-priority="3">
<img src="image1.jpg" ai-priority="1">
<img src="image5.jpg">
<img src="image7.jpg" ai-priority="visibility">

The image with ai-priority="3" is loaded before the image with ai-priority="1". The image without ai-priority attribute is loaded last. The image with ai-priority="visibility" will be loaded when it enters the viewport.

The prioritization Config Setting

The config setting prioritization can override the priority of all delayed images with the value visibility, regardless of ai-priority attributes set in the source document. Allowed values are visibility and auto. The value visibility will deliver all images with the visibility setting, auto delivers the images according to the ai-priority attribute. The default is visibility.

Note: prioritization=auto is deprecated.

Note: Using prioritization=visibility will add an ai-priority attribute to all img elements that are delayed. Iframes will not get an additional attribute.

Note: The use of prioritization=visibility is discouraged for use-cases where printing documents with delayed images is a regular task. Alternatively, a means must be provided to load all delayed images before printing (see ai.images.loadHQImages()). Due to the asynchronous loading of the images the call to load delayed images must not be directly coupled with the call to print. The same applies to delayed iframes, which can be loaded with ai.iframes.loadDelayedIframes().

Visibility Offsets

For image-delaying with visibility enabled and iframe delaying you have two extended options: visibility-offset-x (optional) (default: disabled) visibility-offset-y (optional) (default: 150)

Delayed elements are loaded if their top-left corner is within a certain ‘load’ area. The edges of this area are specified as offsets (in viewport pixels) to the visible viewport. If the horizontal visibility offset is positive, the area’s right edge is located to the right of the visible viewport’s right edge; if the offset is negative, its right edge is located to the left; if the offset is 0, both edges overlap. Similarly, if the vertical visibility offset is positive, the area’s bottom edge is located to the bottom of the visible viewport’s bottom edge; if the offset is negative, its bottom edge is located to the top; again, if the offset is 0, both edges overlap. If an offset has the value ‘disabled’, the area’s dimension in the respective direction is, so to speak, unlimited.

Example for 150 pixel vertical (y-axis) offset: Assuming a viewport height of 600 pixels, the ‘load’ area’s height is 750 pixels. A delayed element located 800px from the document’s top edge will not be loaded. When scrolling down 60 pixels, the element will cross the bottom edge of the ‘load’ area and will be loaded.

Example for -150 pixel horizontal (x-axis) offset: Assuming a viewport width of 400 pixels, the ‘load’ area’s width is 250 pixels. A delayed element located 300px from the document’s left edge will not be loaded. When scrolling to the right 60 pixels, the element will cross the right edge of the ‘load’ area and will be loaded.

Example for disabled horizontal (x-axis) offset: Assuming a viewport width of 400 pixels, the ‘load’ area’s width is unlimited. A delayed element will be loaded regardless of its left edge, provided that the element’s top edge is above the ‘load’ area’s bottom edge.

  • Valid is any positive or negative integer incl 0 plus disabled
  • disabled ignores scroll position for that axis
  • Positive values and 0 affect elements before they enter the viewport (recommended)
  • Negative values affect elements that are already in the viewport

Scroll Speed Dependency

If a browser is capable of Javascript execution during scrolling, delayed elements that enter the viewport while scrolling will be loaded. However, if a user scrolls quickly, the elements would probably scroll out of the viewport before they are fully loaded. Therefore, in order to reduce data consumption and save memory, delayed loading is disabled if the user scrolls faster than 4 pixels per millisecond.

SVG placeholder images

In order to avoid the “jumping page” effect, reduce reflows in the browser and increase the browser’s render performance, FIT delivers inline SVG placeholders with the same width and height as the delayed image, if

  • the browser is capable of displaying SVG images,
  • the image-compression or image-scaling feature is enabled and
  • the source image is present in the FIT cache such that its original dimensions are known.

JavaScript API

The ai.images.loadHQImages() JavaScript Function

FIT automatically loads delayed images after page load. However, if you insert delayed images by hand (for example using Fragments), you will have to initiate the loading yourself by calling the ai.images.loadHQImages() function.

ai.images.loadHQImages(loadAll);

Loads delayed images. Whether an image is loaded depends on its priority. If it is a number the image is loaded with a corresponding delay, if it is the value ‘visibility’ the image is loaded as soon as it enters the ‘load’ area.

Arguments:

loadAll
{boolean} pass true if all delayed images should be loaded (ignoring their priority, or visibility in the ‘load’ area), false otherwise. The default is false. This parameter does not affect the loading of non-visibility-delayed images.

The ai.iframes.loadDelayedIframes() JavaScript Function

FIT automatically loads delayed iframes after page ready. However, if you insert delayed iframes by hand (for example using Fragments), you will have to initiate the loading yourself by calling the ai.iframes.loadDelayedIframes() function.

ai.iframes.loadDelayedIframes(loadAll);

Loads delayed iframes.

Arguments:

loadAll
{boolean} pass true if all delayed iframes should be loaded (even if they are not in the viewport), false otherwise. The default is false.

JavaScript Events

The hqimageloaded event

The hqimageloaded event is fired when a delayed image was loaded.

Properties:

target
{HTMLElement} The img element.

The delayedimagesloaded event

The delayedimagesloaded event is fired after all delayed images have been loaded.

This event may be fired several times if new delayed images are added to the page after the event was already fired.

All listeners registered to this event are reset by PPL requests.

The delayediframeloaded event

The delayediframeloaded event is fired when a delayed iframe was loaded.

Properties:

target
{HTMLElement} The iframe element.

The delayediframesloaded event

The delayediframesloaded event is fired after all delayed iframes have been loaded.

This event may be fired several times if new delayed iframes are added to the page after the event was already fired.

All listeners registered to this event are reset by PPL requests.