W3C

Progress events 1.0

Editor's Draft 17 June 2008

This version:
http://dev.w3.org/cvsweb/~checkout~/2006/webapi/progress/Progress.html?rev=1.21
Latest Editor's version:
http://dev.w3.org/cvsweb/~checkout~/2006/webapi/progress/Progress.html
Previous version:
http://dev.w3.org/cvsweb/~checkout~/2006/webapi/progress/Progress.html?rev=1.20
Editor:
Charles McCathieNevile, Opera Software

Copyright © 2006-2008 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.

Abstract

This document describes event types that can be used for monitoring the progress of an operation. It is primarily intended for contexts such as data transfer operations specified by XMLHTTPRequest [XHR], or Media Access Events [MAE].

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 document is an editor's draft specification of the ProgressEvent events from the Web API group, part of the Rich Web Client Activity. It defines events which can be used to monitor a process and provide feedback to a user, particularly for network-based events. This editor's draft does not imply any consensus of or endorsement by any member of the working group, and may contain minor or major errors.

This version is published as an initial response to comments received on the third W3C Working Draft. All comments are welcome and should be sent to the new Working Group list at public-webapps@w3.org. All messages received at this address are viewable in a public archive (Please note that a different list has been used until now, so old messages will be archived there instead). Given the issues raised by review of the Public Workng Draft this specification will hopefully be published as a Last Call Working draft in the third quarter of 2008. Currently there are is at least one substantice issue unresolved by this specification: ISSUE-3: Should there be an eventType defined in this specification to allow the use of document.createEvent. There are several editorial changes expected, labelled as follows: @@Do something

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

Table of Contents

1. Conformance

The terms must, should, may, must not, should not, are used in this document in accordance with [RFC2119]. A conformant implementation of this specification meets all relevant requirements identified by the use of these terms. Except where noted otherwise, all sections of this document are normative, except examples which are informative.

There are three classes of conformance to this specification:

Specification
A specification may describe how progress events can be dispatched for some operation. A conformant specification is one which includes all the requirements identified in the section Referring to progress events from other specifications.
User agent
A user agent must implement all the requirements described for user agents throughout this specification in order to be a conforming user agent. A conforming user agent should implement all the recommendations for user agents as well.
Content
Conforming content must generate and consume progress events in accordance with the definitions of those events in this specification, and in accordance with any additional conformance requirements defined by a specification which describes an operation that can lead to progress events being dispatched. (Note that content which meets the requirements of a specification which is not conformant to this specification may still be conforming content as defined for this specification).

2. The ProgressEvent events

2.1 Event definitions

The following events are defined in this specification:

Name Description How often? When?
loadstart The operation has begun once Must be dispatched first
progress The operation is in progress zero or more May be dispatched zero or more times after a loadstart event, before any error, abort or load event is dispatched
error The operation failed to complete, e.g. as a result of a network error never or once Exactly one of these must be dispatched
abort The operation was cancelled, e.g. as a result of user interaction never or once
load The operation successfuly completed never or once

User agents must implement these events such that by default the events do not bubble, and are not be cancelable.

User agents must ensure that these events trigger event listeners attached on Element nodes for the relevant event and on the capture and target phases.

No default action is defined for these events.

These events are in "no namespace", that is for the purposes of namespaced systems they use the null namespace. Two kinds of initialisation methods are provided: one (initProgressEventNS) in which the namespace is required and must be null (any event in another namespace is not defined by this specification), and one (initProgressEvent) which assigns the null namespace automatically. This specification does not recommend use of one method over the other, and authors may choose whichever method suits them better for any given usage.

2.2 Event firing order

In short, there must be at least one loadstart event, followed by zero or more progress events, followed by one event which may be any of error, abort or load, according to the outcome of the operation.

2.3 Interface definitions

Where this specification repeats information from the DOM Level 3 Events specification [D3E], the repeated information in this section is informative. In the case of any conflict between the specifications the DOM Level 3 Events specification is normative.

IDL Definition
interface ProgressEvent : events::Event {
     readonly attribute boolean         lengthComputable;
     readonly attribute unsigned long   loaded;
     readonly attribute unsigned long   total;
     void               initProgressEvent(in DOMString typeArg,
                                          in boolean       canBubbleArg,
                                          in boolean       cancelableArg,
                                          in boolean       lengthComputableArg,
                                          in unsigned long loadedArg,
                                          in unsigned long totalArg)
     void               initProgressEventNS(in DOMString namespaceURI,
                                            in DOMString typeArg,
                                            in boolean       canBubbleArg,
                                            in boolean       cancelableArg,
                                            in boolean       lengthComputableArg,
                                            in unsigned long loadedArg,
                                            in unsigned long totalArg)
};


Attributes
readonly boolean lengthComputable
Specifies whether the total size of the transfer is known.
readonly unsigned long loaded
Specifies the number of bytes transferred since the beginning of the operation. This refers to the content, excluding headers and overhead from the transaction, and where there is a content-encoding or transfer-encoding refers to the number of bytes to be transferred, i.e. with the relevant encodings applied. For more details on HTTP see [RFC2616]. ISSUE-4: Should this be left to specifications to define?
readonly unsigned long total
Specifies the expected total number of bytes of the content transferred in the operation. Where the size of the transfer is for some reason unknown, the value of this attribute must be zero.
Methods
initProgressEvent
This method is used to initialize the value of a ProgressEvent object and has the same behavior as Event.initEventNS(), where the value of the namespace parameter is specified as null [D3E].
Parameters
typeArg of type DOMString
If the value of this parameter is not one of loadstart, progress, error, abort, or load then this specification does not define the resulting event. Refer to the Event.initEvent() method [D3E] for further description of this parameter.
canBubbleArg of type boolean
Specifies Event.bubbles. This parameter overrides the intrinsic bubbling behavior of the event and determines whether the event created will bubble
cancelableArg of type boolean
Specifies Event.cancelable. This parameter overrides the intrinsic cancel behavior of the event and determines whether the event created is cancelable
lengthComputableArg of type boolean
If the user agent has reliable information about the value of total, then this should be true. If the user agent does not have reliable information about the value of total, this should be false
loadedArg of type unsigned long
This parameter specifies the total number of bytes already transferred. If this value is not a non-negative number, the user agent must change it to zero.
totalArg of type unsigned long
This specifies the total number of bytes to be transferred. If lengthComputable is false, this must be zero. If any other parameter is passed, and lengthComputable is false, the user agent must override this and set the value to zero. If lengthComputable is true, and the value of this parameter is not a non-negative number, the user agent must set lengthComputable to false and the value of total to zero.
No Return Value
No Exceptions
initProgressEventNS
This method is used to initialize the value of a namespaced ProgressEvent object and has the same behavior as Event.initEventNS() [D3E]. Except as described below, parameters are the same as for initProgressEvent.
Parameters
namespaceURIArg of type DOMString
For all events defined in this specification, the value of this parameter is null.
No Return Value
No Exceptions

3. Referring to progress events from other specifications

A progress event occurs when the user agent makes progress in some data transfer operation, such as loading a resource from the web via XMLHttpRequest [XHR]. Conforming specifications which use progress events must define the targets on which progress events are dispatched.

Either by reference or by direct inclusion, conforming specifications must maintain and must not contradict the requirements for and definition of the events as described in the section The ProgressEvent events

Example 1: Using progress events in another specification:

This example is informative and does not necessarily illustrate best practice.

FooAPI has a sendAndRetrieve() method, which sends some content via a predefined SMTP server and retrieves some other content via HTTP HEAD from a URI given as a parameter. It specifies two event targets send and receive. Progress events as specified in the ProgressEvent events specification may be dispatched on these targets for the send and receive phases respectively. If any progress events are dispatched, then at least one start event, and one of error, abort, or load must be dispatched on each target. For the send phase, the total attribute of the progress events measures the size of the RFC822 message body. For the receive phase, the total attribute specifies the size of the content to be returned in the HTTP HEAD operation.

4. Using progress events in Web content

Scripts may use progress events in order to provide feedback on operations performed by an application.

Example 2: Using Progress events in an SVG document.

This example is informative and does not necessarily illustrate best practice.

In this example, the application uses the information in progress events emitted as an image loads in order to fill a progress bar as it receives progress events. Where the size of a download is unknown or there has been no progress yet there is simply a block moving back and forth within the progress bar to indicate that there is still some kind of activity.

<svg xmlns="http://www.w3.org/2000/svg" version="1.1"
     xmlns:xlink="http://www.w3.org/1999/xlink"
     viewBox="0 0 400 400">
   
   <script type="application/ecmascript"><![CDATA[
   var xlinkNS = "http://www.w3.org/1999/xlink"

   function showImage(imageHref) {
       var image = document.getElementById('myImage');
       image.setAttributeNS(xlinkNS, "href", imageHref);
       image.addEventListener("progress",imageLoadProgress,false);
       image.addEventListener("load",imageLoadComplete,false);
       image.addEventListener("error",imageLoadComplete,false);
       image.addEventListener("abort",imageLoadComplete,false);
   }           

   function imageLoadProgress(evt) {  
       if (evt.lengthComputable && evt.total != 0) { // we know the size, don't divide by zero
          var progressBar = document.getElementById('progressBar');
          progressBar.setAttribute("width", 100*evt.loaded/evt.total);
          var loadAnimation = document.getElementById('loadAnimation');
          loadAnimation.endElement();
       } else { // we don't know the size and we need not to divide by zero
          var progressBar = document.getElementById('progressBar');
          progressBar.setAttribute("width", 20);
          var loadAnimation = document.getElementById('loadAnimation');
          loadAnimation.beginElement();
       }   
   }
               
   function imageLoadComplete(evt) {
       var progressBar = document.getElementById('progressBar');  
       progressBar.setAttribute("width", 100);
        var loadAnimation = document.getElementById('loadAnimation');
       loadAnimation.endElement();
               
   }
   ]]></script>

   <image id="myImage" xlink:href="imageA.png" width="300" height="400"/>

   <rect onclick="showImage('imageB.png')" width="120" 
         height="30" y="400" id="button" />

   <animate id="loadAnimation" xlink:href="#progressBar" attributeName="x" 
     by="80" dur="1s" begin="button.click" repeatCount="indefinite"/>

   <g id="meter" opacity="0">
     <set attributeName="opacity" to=".7" begin="button.click" end="myImage.load"/>
     <rect width="101" fill="none" height="5" x="5" y="5" stroke-width="1"/>
     <rect id="progressBar" fill="#444" height="4" x="5.5" y="5.5"/>
  </g>
</svg>

Example 3: Using Progress events in an HTML document.

This example is informative and does not necessarily illustrate best practice.

In this example, the application creates an XMLHttpRequest [XHR], in an HTML5 [HTML5] document and checks whether it makes progress. (Note that this relies on draft specifications and may need to change)

<!DOCTYPE html>
 <html>
  <head>
   <title>Using Progress Events</title>  
   <script>
    var theTransfer = new XMLHttpRequest();
    //start up the request properly
    
    theTransfer.addEventListener("progress",updateProgress,false);
    theTransfer.addEventListener("load",worky,false);
    theTransfer.addEventListener("error",failToWorky,false);
    theTransfer.addEventListener("abort",whatForYouDoThat,false);

   theTransfer.open()

   function updateProgress(evt) {  
          var progressCount = document.getElementById('progressCount');
          progressCount.child[1].data = evt.loaded;
       if (evt.lengthComputable && evt.total != 0) {                  // show progress
          var totalCount = document.getElementById('total');
          totalCount.child[1].data = evt.total;
       } else { // we don't know the size
          var totalCount = document.getElementById('totalCount');
          totalCount.setAttribute("irrelevant", "irrelevant");
       }   
   }
               
   function worky(evt) {
       alert("Yuk! Modal dialog! But the transfer completed ;) ");
   }
               
   function failToWorky(evt) {
       alert("The horror! The transfer failed!!!");
   }
               
   function worky(evt) {
       alert("Hey! User control is not relevant here...");
   }
   </script>

  </head>
  <body>
    <p id="theProgress">So far, I have loaded <span id="progressCount">0</span> bytes
     <span id="totalCount" irrelevant="irrelevant">of the total transfer of 
     <span id="total">the total</span></span></p>
  </body>
 </html>

5. References

5.1 Normative references

[D3E] DOM Level 3 Events.
Björn Höhrmann, ed. W3C Working draft, available at http://www.w3.org/TR/DOM-Level-3-Events/
[RFC2119] Key words for use in RFCs to indicate Requirement Levels
S Bradner, 1997. The specification for how to use english to specify normatively, as if it were a technical language. Available at http://rfc.net/rfc2119.html
[RFC2616] Hypertext Transfer Protocol -- HTTP/1.1
R Fielding et al., 1999. Available at http://rfc.net/rfc2616.html

5.2 Informative references

[IEoP] onProgress event in Internet Explorer
Documentation available at http://msdn.microsoft.com/library/default.asp?url=/library/en-us/com/html/07b3e629-a558-4a0e-8307-ca922f56e00c.asp
[MAE] Media Access Events
Ola Anderson, Jean-Claude Duford, Roland Lundblad, eds. W3C Working Draft available at http://www.w3.org/TR/MediaAccessEvents/
[SVGD] The proposed progress event in SVG 1.2
Available at http://www.w3.org/TR/2006/CR-SVGMobile12-20060810/svgudom.html#events__ProgressEvent
[WPE] The progress element proposed by WHAT-WG
I Hickson, ed. Latest version available at http://www.whatwg.org/specs/web-apps/current-work/#progress0
[XHR] XMLHTTPRequest
A van Kesteren, ed.. Latest draft available at http://www.w3.org/TR/xmlhttprequest

6. Acknowledgements

The editor would like to thank the SVG working group for producing the draft [SVGD] that this was initially based on. The WHATWG's proposed progress element [WPE] and the documentation for Internet Explorer's onProgress implementation [IEoP] were also useful as an initial reference for this specification. In addition, the following individuals' comments have been invaluable in preparing this draft:

Robin Berjon, Jean-Yves Bitterlich, Marcos Caceres, Suresh Chitturi, Alex Danilo, Erik Dahlström, Jean-Claude Duford, Andrew Emmons, João Eiras, Gorm Eriksen, Ian Hickson, Bjoern Hoehrmann, Björn Hoehrmann, David Håsäther, Bj�rn Höhrmann, Bjoern H�hrmann, Anne van Kesteren, Travis Leithead, Aaron Leventhal, Jim Ley, Chrus Lilley, Cameron McCormack, Olli Pettay, Michael Antony Puls, Nandini Ramani, Robert Sayre, Alan Schepers, Doug Schepers, Rich Schwerdtfeger, Lisa Seeman, Andrew Shellshear, Ellen Siegel, Andy Sledd, Maciej Stachowiak, Boris Zbarsky, Gottfried Zimmermann

The editor apologises to anyone who has inadvertently been left off this list, and welcomes corrections.

7. Change History

http://dev.w3.org/cvsweb/~checkout~/2006/webapi/progress/Progress.html?rev=1.21 (based on proposed Third Public Working Draft)
Editorial changes designed to clarify conformance requirements for each type of conformance.
http://dev.w3.org/cvsweb/~checkout~/2006/webapi/progress/Progress.html?rev=1.20
http://dev.w3.org/cvsweb/~checkout~/2006/webapi/progress/Progress.html?rev=1.18
Copy of the Public Working Draft http://www.w3.org/TR/WD-progress-event-20071023
http://dev.w3.org/cvsweb/~checkout~/2006/webapi/progress/Progress.html?rev=1.17 (basis for Second Public Workling Draft)
Only editorial tweaks
http://dev.w3.org/cvsweb/~checkout~/2006/webapi/progress/Progress.html?rev=1.16 (intended basis for new Public Workling Draft)
http://dev.w3.org/cvsweb/~checkout~/2006/webapi/progress/Progress.html?rev=1.15 (intended basis for new Public Working Draft)
http://dev.w3.org/cvsweb/~checkout~/2006/webapi/progress/Progress.html?rev=1.12
http://dev.w3.org/cvsweb/~checkout~/2006/webapi/progress/Progress.html?rev=1.11 (Basis for first Public Working Draft http://www.w3.org/TR/2007/WD-progress-events-20070419 )
http://dev.w3.org/cvsweb/~checkout~/2006/webapi/progress/Progress.html?rev=1.10
http://dev.w3.org/cvsweb/~checkout~/2006/webapi/progress/Progress.html?rev=1.9
http://dev.w3.org/cvsweb/~checkout~/2006/webapi/progress/Progress.html?rev=1.8
http://dev.w3.org/cvsweb/~checkout~/2006/webapi/progress/Progress.html?rev=1.7
http://dev.w3.org/cvsweb/~checkout~/2006/webapi/progress/Progress.html?rev=1.4
http://dev.w3.org/cvsweb/~checkout~/2006/webapi/progress/Progress.html?rev=1.3
http://dev.w3.org/cvsweb/~checkout~/2006/webapi/progress/Progress.html?rev=1.2
First real version

Various editorial changes and corrections and modifications to the examples are made from draft to draft. These are generally not noted in the change history.