W3C home > Mailing lists > Public > public-device-apis@w3.org > November 2009

Re: [FileReader API, ProgressEvents] Design patterns, FileWriter API

From: Arun Ranganathan <arun@mozilla.com>
Date: Tue, 17 Nov 2009 17:30:16 -0800
Message-ID: <4B034E28.6020004@mozilla.com>
To: Marcin Hanclik <Marcin.Hanclik@access-company.com>
CC: WebApps WG <public-webapps@w3.org>, "public-device-apis@w3.org" <public-device-apis@w3.org>
Greetings Marcin,

Thanks for the thoughtful feedback.  My comments below:

> In my opinion some part of the design from ProgressEvents is taken over in FileReader API too directly.
> Specifically the event names are the same as within the ProgressEvents, but I assume they should be adjusted to the FileReader API.
> Therefore instead of (forgetting the above issue with the callback model for now):
>   attribute Function onloadstart;
>   attribute Function onprogress;
>   attribute Function onload;
>   attribute Function onabort;
>   attribute Function onerror;
>   attribute Function onloadend;
> we could have:
>   attribute Function onreadstart;
>   attribute Function onprogress;
>   attribute Function onread;
>   attribute Function onabort;
>   attribute Function onerror;
>   attribute Function onreadend;

What's in a name? [Floral poetry reference elided :-) ].

You are right to point out that there's some inconsistency in the naming 
convention.  This discussion came up with the discussion of readyState 
[1] state name changes, when READING was considered as a potential 
readyState, were it not for consistency with the progress events in 
question (loadstart, load, loadend... ).  We elected to stick to LOADING 
to match the names of existing progress events with 'load' in them.

I'll note that 'onload' is very ubiquitous on the web platform, and has 
been for a while now.  These progress events are also used within XHR.  
This kind of consistency is very desirable for developer convenience, 
and in my opinion, trumps the "perfect name" consideration.  We've used 
consistency in naming before in this specification.  Here are a few 
other examples:

1. INTIAL --> EMPTY, for closer name similarity to HTMLMediaElement's 
network status.
2. mediaType --> type, for closer name similarity with <style>.type
3. Error conditions like NOT_FOUND_ERR, SECURITY_ERR, and ABORT_ERR are 
used in DOMException codes and XHR's error codes respectively, including 
with the same error code.

Essentially, the argument here is to reuse what developers are familiar 
with.  *In particular* I'm swayed by the pervasive use of 'onload' on 
the web.  However, I like your next point:

> Assuming that we will have an interface like FileWriter in the (near) future, we could already now anticipate that the interface would include e.g. the following:
>   attribute Function onwritestart;
>   attribute Function onprogress;
>   attribute Function onwrite;
>   attribute Function onabort;
>   attribute Function onerror;
>   attribute Function onwriteend;

To date, you'll note that progress event nomenclature reflects "loading" 
or "reading" operations, since there are very few "write" metaphors on 
the web that have affiliated events bound to them.  If the design of the 
FileWriter is similar to the design of the FileReader (which is 
something we're currently working on), then I think your names make sense.

> Then, the ProgressEvents spec could act as a design pattern definition for lengthy, asynchronous operations.
> To make it happen, the names of the events there could be changed to be generic:

I think that just as the names 'load*' were chosen for generic data 
transfer events (either networked or within a document), and are used 
within documents loaded in the DOM, XHR, and FileReader, we'll need 
reusable 'write*' events.  Without bikeshedding too much, I like your 
proposal above, but wonder whether we should use the name 'write*' or 
something else.  Since we already have document.write, 'write' is 
probably the most vetted string to use here :)

> loadstart -> start
> progress
> stalled
> suspend
> error
> abort
> load -> done
> loadend -> end

Sure.  On this question I'm less opinionated.
> Additionally the ProgressEvents spec could be divided (or split into two documents? ) to contain the section specific to the design pattern definition and to the section specific to data transfer / loading.

I like the proposal to have a section specific to data transfer and 
loading, but am wary of splitting specs.  Input and feedback from the 
author of the ProgressEvents specification would be welcome here.

-- A*

[1] http://lists.w3.org/Archives/Public/public-webapps/2009OctDec/0691.html
Received on Wednesday, 18 November 2009 01:30:51 UTC

This archive was generated by hypermail 2.4.0 : Friday, 17 January 2020 19:32:13 UTC