Resource Priorities

Editor's Draft April 16, 2014

Latest Editor's Draft:
http://dvcs.w3.org/hg/webperf/raw-file/tip/specs/ResourcePriorities/Overview.html
Latest published version:
http://www.w3.org/TR/resource-priorities/
Editors:
Tobin Titus, Microsoft Corp., <>
James Simonsen, Google Inc., <>
Jatinder Mann, Microsoft Corp., <> (Until February 2014)

Abstract

This specification defines a means for site developers to programmatically give the User Agent hints on the download priority of a resource. This will allow User Agents to more efficiently manage the order in which resources are downloaded.

Status of this document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This is an editor's draft and may change without any notices.

Please send comments to public-web-perf@w3.org (archived) with [ResourcePriorities] at the start of the subject line.

This document is produced by the Web Performance Working Group.

Table of Contents

  1. 1 Introduction
    1. 1.1 Executing scripts sooner
    2. 1.2 Optimizing download priority during network contention
    3. 1.3 Proactively loading resources
  2. 2 Conformance requirements
  3. 3 Terminology
  4. 4 Resource Priorities
    1. 4.1 Introduction
    2. 4.2 The lazyload attribute
    3. 4.3 Elements capable of downloading resources
      1. 4.3.1 The img element
      2. 4.3.2 The audio element
      3. 4.3.3 The video element
      4. 4.3.4 The script element
      5. 4.3.5 The link element
      6. 4.3.6 The embed element
      7. 4.3.7 The iframe element
      8. 4.3.8 The object element
      9. 4.3.9 The svg feImage filter primitive
      10. 4.3.10 The svg image element
      11. 4.3.11 The svg use element
      12. 4.3.12 The svg script element
      13. 4.3.13 The svg tref element
    4. 4.4 The Events
      1. 4.4.1 The load event
      2. 4.4.2 The lazyloaded event
  5. 5 References
  6. Acknowledgements

1 Introduction

This section is non-normative.

The Resource Priorities specification defines a means for site developers to programmatically give the User Agent hints on the download priority of a resource. Without knowing the download priority of a resource, the User Agent will typically download resources in document order. However, the download order may not be best optimized for improving both the perceived and real page load performance. By specifying lower priority resources using the lazyload attribute, the User Agent is able to better optimize download order when the User Agent is in a resource constrained environment and sooner execute scripts triggered by the load event of the Document.

1.1 Executing scripts sooner

Today, most developers trigger script execution based on the load event of the Document. However, the load event can be delayed by resources that are not necessary for page load visuals and do not interact with script. For example, a site may have images well below the fold that are delaying how long it takes the load event of the document to fire, delaying scripts from executing. Specifying the lazyload attribute on an element downloading a resource allows the User Agent to not block the load event of the Document on those resources. By specifying the lazyload attribute on resources that have no interaction with script or are not necessary for above the fold visuals, scripts can execute sooner, improving real world page load performance.

1.2 Optimizing download priority during network contention

Site developers can improve the perception of page load performance by optimizing the download of resources when there is network resource contention such that downloads for resources not required to create the above the fold visuals are prioritized lower. However, determining which resources are required to create the above the fold visuals for a web page is something the User Agent cannot easily determine on its own. Instead, the site developer is in the best position to let the User Agent know the relative priorities of resources on their web application.

The following example shows a theoretical web page that doesn't specify the download priority of resources. In this example, the site developer will use Stylesheets from Styles.css and script within Visuals.js to re-layout the page such that Logo.png, Header.png, and MainContent.mp4 will be shown above the fold, whereas AdditionalImages1.png and AdditionalImages2.png will be shown below the fold. Animations.css is used to display an animation when a user clicks on an image and Analytics.js is used to collect analytics information, both not executed during the page load.

<!DOCTYPE html>
<html>
 <head>
     <link rel="stylesheet" type="text/css" src="Styles.css" />
     <link rel="stylesheet" type="text/css" src="Animations.css" />
 </head>
 <body>
    <img id="Logo" src=".../images/Logo.png"/>
    <img id="Header" src=".../images/Header.png"/>
    <img id="AdditionalImages1" src=".../images/AdditionalImages1.png"/>
    <img id="AdditionalImages2" src=".../images/AdditionalImages2.png"/>
    <video id="MainContent"><source src=".../videos/MainContent.mp4"></video>
    <script src="Visuals.js" ></script>
    <script src="Analytics.js" ></script>
 </body>
</html>

As the example page has been specified, a User Agent may download resources in the following order: root document, CSS in document order, JavaScript in document order, and everything else in document order. In this case, AdditionalImages1.png and AddtionalImages.png will be downloaded before MainContent.mp4, even though they will not be displayed above the fold when the page loads. Additionally, Animations.css and Analytics.js will be downloaded prior to the visual aspect of the page, even though they won't be used in the page load sequence.

Using the lazyload attribute on a resource will signal to the User Agent that in cases of network resource contention, it may lower the download priority of that resource.

The following example shows the same theoretical web page but with the lazyload attribute set for resources whose download priority can be reduced, as they do not impact the visual appearance of the page above the fold.

<!DOCTYPE html>
<html>
 <head>
     <link rel="stylesheet" type="text/css" src="Styles.css" />
     <link rel="stylesheet" type="text/css" src="Animations.css" lazyload />
 </head>
 <body>
    <img id="Logo" src=".../images/Logo.png"/>
    <img id="Header" src=".../images/Header.png"/>
    <img id="AdditionalImages1" src=".../images/AdditionalImages1.png" lazyload />
    <img id="AdditionalImages2" src=".../images/AdditionalImages2.png" lazyload />
    <video id="MainContent"><source src=".../videos/MainContent.mp4"></video>
    <script src="Visuals.js" ></script>
    <script src="Analytics.js" lazyload ></script >
 </body>
</html>

In this example page, using the lazyload attribute User Agent may instead download resources in the following order: root document, Styles.css, Visuals.js, Logo.png, Header.png, MainContent.mp4, Animations.css, Analytics.js, AdditionalImages1.png and AdditionalImages2.png.

1.3 Proactively loading resources

Some applications require a large number of resources that may not be required immediately. For example, a Canvas game may have multiple game levels with different assets required for each level. Instead of slowing down the initial application loading experience by loading all assets during the page load, developers can use the lazyload attribute on resources that they do not need immediately. These resources won't block script execution, as the load event of the Document will not be delayed, and in cases of network resource contention, the User Agent will optimize downloading the higher priority resources.

The following example shows a theoretical game application that is using lazyload to differentiate between assets that are required more immediately and assets that are not required immediately.

<!DOCTYPE html>
<html>
 <head>
 </head>
 <body onload='init()'>
 <canvas id='GameCanvas'></canvas>
 <img class='Backgrounds' id='BackgroundLevel1' src='Background1.png' />
 <img class='Backgrounds' id='BackgroundLevel2' src='Background2.png' lazyload />
   <script>
    var assets = [];
    var NUM_ASSETS_LEVEL1 = 100;
    var NUM_ASSETS_LEVEL2 = 100;
    var NUM_ASSETS_GENERAL = 100;
    var URL_LEVEL1_ASSETS = "assets\\level1\\";
    var URL_LEVEL2_ASSETS = "assets\\level2\\";
    var URL_GENERAL_ASSETS = "assets\\general\\";

   function init() {
      // Load game assets 
      loadGameAssets();
	  
      // Play game
   }

   function loadGameAssets() { 
      var i, j, k;
   
      // Load assets required for Level 1
      for (i = 0; i < NUM_ASSETS_LEVEL1; i++) {
         assets[i] = new Image();
         assets[i].src = URL_LEVEL1_ASSETS + i + ".png";
      }
      
      // Lazyload assets required for Level 2
      for (j = 0; j < NUM_ASSETS_LEVEL2; j++) {
         assets[i + j] = new Image();
         assets[i + j].setAttribute('lazyload');
         assets[i + j].src = URL_LEVEL2_ASSETS + j + ".png";
      }
	  
      // Load additional assets required for all levels
      for (k = 0; k < NUM_ASSETS_GENERAL; k++) {
         assets[i + j + k] = new Image();
         assets[i + j + k].src = URL_GENERAL_ASSETS + k + ".png";
      }
   }
  </script>
 </body>
</html>

In the previous example, downloading the Background2.png specified in markup does not block the load event of the page as it has been marked with lazyload. Similarly, for the dynamically loaded resources, if there had been a network resource contention, the User Agent would have prioritized the downloads for level 1 and general assets over level 2 assets.

2 Conformance requirements

All diagrams, examples, and notes in this specification are non-normative, as are all sections explicitly marked non-normative. Everything else in this specification is normative.

The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this document are to be interpreted as described in RFC 2119. For readability, these words do not appear in all uppercase letters in this specification.

Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and abort these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.

Some conformance requirements are phrased as requirements on attributes, methods or objects. Such requirements are to be interpreted as requirements on user agents.

Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent. (In particular, the algorithms defined in this specification are intended to be easy to follow, and not intended to be performant.)

The IDL fragments in this specification must be interpreted as required for conforming IDL fragments, as described in the Web IDL specification. [Web IDL]

3 Terminology

The construction "a Foo object", where Foo is actually an interface, is sometimes used instead of the more accurate "an object implementing the interface Foo".

Network resource contention is defined as when the User Agent determines there is a conflict over access to network resources. An example of network resource contention is when a User Agent is unable to start downloading a resource because the User Agent has exhausted all available TCP connections.

4 Resource Priorities

4.1 Introduction

This section is non-normative.

This specification defines a means for site developers to programmatically give the User Agent hints on the download priority of a resource. This will allow User Agents to more efficiently manage the order in which resources are downloaded when there is network resource contention or when the resource is not visible to the user, and allow the load event of the Document to fire sooner as it will not be blocked for lower priority resources.

4.2 The lazyload attribute

The lazyload attribute is a boolean and IDL attribute that indicates the priority order in which the User Agent should download the resource associated with the element in cases of network resource contention.

If the User Agent determines that there is network resource contention, the User Agent SHOULD delay downloading resources associated with elements that have the lazyload boolean attribute specified on the element until all other resources associated with elements that do not have the lazyload boolean attribute specified on the element have started downloading.

Note

An example of network resource contention can be if there is a connection contention where the User Agent is using all available connections. A User Agent may give available TCP connections, or give a more optimized TCP connection if there is a choice between available connections, to resources that don’t have the lazyload attribute.

The lazyload IDL attribute MUST reflect the lazyload boolean attribute value.

The lazyload boolean and IDL attributes are supported on the following HTML elements and SVG elements capable of fetching resources: img, audio, video, script, link, embed, iframe, object, svg feImage, svg image, svg use, svg script, and svg tref.

4.3 Elements capable of downloading resources

4.3.1 The img element

Content attributes:
lazyload
DOM interface:
partial interface HTMLImageElement {
     attribute boolean lazyload;
};

The img element supports the lazyload attribute.

4.3.2 The audio element

Content attributes:
lazyload
DOM interface:
partial interface HTMLAudioElement {
     attribute boolean lazyload;
};

The audio element supports the lazyload attribute.

4.3.3 The video element

Content attributes:
lazyload
DOM interface:
partial interface HTMLVideoElement {
     attribute boolean lazyload;
};

The video element supports the lazyload attribute.

4.3.4 The script element

Content attributes:
lazyload
DOM interface:
partial interface HTMLScriptElement {
     attribute boolean lazyload;
};

The script element supports the lazyload boolean attribute, along with the defer and async boolean attributes, to indicate the order in which the user agent will download and execute the script.

There are a few possible modes that can be selected using these attributes:

Content attributes:
lazyload
DOM interface:
partial interface HTMLLinkElement {
     attribute boolean lazyload;
};

The link element supports the lazyload attributes.

The User Agent MUST NOT block rendering on stylesheets that have the lazyload boolean attribute specified on the associated link element or the lazyload IDL attribute set to true on the associated link element.

The User Agent parser MUST NOT block launching new script contexts on stylesheets that have the lazyload boolean attribute specified on the associated link element or the lazyload IDL attribute set to true on the associated link element.

4.3.6 The embed element

Content attributes:
lazyload
DOM interface:
partial interface HTMLEmbedElement {
     attribute boolean lazyload;
};

The embed element supports the lazyload attribute.

4.3.7 The iframe element

Content attributes:
lazyload
DOM interface:
partial interface HTMLIFrameElement {
     attribute boolean lazyload;
};

The iframe element supports the lazyload attribute.

4.3.8 The object element

Content attributes:
lazyload
DOM interface:
partial interface HTMLObjectElement {
     attribute boolean lazyload;
};

The object element supports the lazyload attribute.

4.3.9 The svg feImage filter primitive

Content attributes:
lazyload
DOM interface:
partial interface SVGFEImageElement {
     attribute boolean lazyload;
};

The svg feImage primitive supports the lazyload attribute. If the externalResourcesRequired attribute is set to true, the lazyload attribute will have no effect.

4.3.10 The svg image element

Content attributes:
lazyload
DOM interface:
partial interface SVGImageElement  {
     attribute boolean lazyload;
};

The svg image element supports the lazyload attribute.

4.3.11 The svg use element

Content attributes:
lazyload
DOM interface:
partial interface SVGUseElement {
     attribute boolean lazyload;
};

The svg use element supports the lazyload attribute.

4.3.12 The svg script element

Content attributes:
lazyload
DOM interface:
partial interface SVGScriptElement {
     attribute boolean lazyload;
};

The svg script element supports the lazyload attribute.

4.3.13 The svg tref element

Content attributes:
lazyload
DOM interface:
partial interface SVGTRefElement {
     attribute boolean lazyload;
};

The svg tref element supports the lazyload attribute.

4.4 Events

4.4.1 The load event

The load event of the Document MUST NOT be blocked by any element with the lazyload content attribute specified or the lazyload IDL attribute set to true. The load event of an element with the lazyload attribute MUST continue to be blocked until the resource is loaded.

The lazyload attribute MUST not change when the DOMContentLoaded event is fired or the behavior of the loading, interactive, and complete states of the Document's readyState IDL attribute.

4.4.2 The lazyloaded event

Immediately after all elements with the lazyload content attribute specified or lazyload IDL attribute set to true have their resources downloaded, the User Agent MUST queue a task to fire a simple event lazyloaded at the Document. If there are no elements with the lazyload content attribute specified or with the lazyload IDL attribute set to true, the User Agent MUST queue a task to fire the lazyloaded event at the Document immediately after the load event of the Document has been fired.

5 References

[IETF RFC 2119]
Key words for use in RFCs to Indicate Requirement Levels, Scott Bradner, Author. Internet Engineering Task Force, March 1997. Available at http://www.ietf.org/rfc/rfc2119.txt.
[HTML5]
HTML5, Robin Berjon, et al, Editors. World Wide Web Consortium, August 2013. This version of the HTML5 is available from http://www.w3.org/TR/html5/. The latest editor's draft of HTML is available at http://www.w3.org/html/wg/drafts/html/master/.
[Web IDL]
Web IDL, Cameron McCormack, Editor. World Wide Web Consortium, April 2012. This version of the Web IDL specification is available from http://www.w3.org/TR/2012/CR-WebIDL-20120419/. The latest version of Web IDL is available at http://www.w3.org/TR/WebIDL/.
[CSS]
CSS 2.1, Bert Box, et al, Editors. World Wide Web Consortium, June 2011. This version of the CSS 2.1 specification is available from http://www.w3.org/TR/2011/REC-CSS2-20110607/. The latest version of CSS 2.1 is available at http://www.w3.org/TR/CSS2/.
[SVG]
SVG 1.1, Erik Dahlström, et al, Editors. World Wide Web Consortium, August 2011. This version of the SVG 1.1 specification is available from http://www.w3.org/TR/2011/REC-SVG11-20110816/. The latest version of SVG 1.1 is available at http://www.w3.org/TR/SVG/.

Acknowledgements

We would like to sincerely thank Bruno Racineux, Jake Archibald, Jason Weber, Josh Tumath, Tony Ross, Travis Leithead, Yoav Weiss, Marcos Caceres, Brian Birtles, Ivan Kotenkov, Erik Dahlstrom, Boris Zbarsky, William Chan, and Shwetank Dixit to acknowledge their contributions to this work.