Re: comments no the web notifications spec

On Mon, 26 Sep 2011, John Gregg wrote:
> On Thu, Jun 30, 2011 at 1:47 PM, Ian Hickson <ian@hixie.ch> wrote:
> >
> > Why would you create a notification but not show it? Unless there's a 
> > use case that requires notifications to be created ahead of time 
> > (including setting the message and icon, since you can't change those) 
> > but not shown til later, I recommend removing the show() method and 
> > making it implicit at creation.
> 
> This structure is more motivated by practicalities of programming using 
> the API.  Setting up event listeners needs to happen before show(), 
> particularly if you want to listen to the show event, but IMHO it is 
> cumbersome to ask for these optional parameters at creation time.

Unless show() is synchronous, in which case there's a whole other problem 
to raise here, there is no need to register the event listeners before 
show() (or before the constructor). Events are usually fired in a task, 
and tasks are queued on the event loop and therefore cannot fire until the 
current script has finished, by which time any necessary event listeners 
will have been attached.


> I would cite XMLHttpRequest as a very similar pattern.

XMLHttpRequest is widely regarded as being horribly designed; I wouldn't 
look to it for inspiration.


> > An example suggests that notifications timing out should be done from 
> > script. That's bad for accessibility, where you don't want things 
> > timing out automatically since people with slower ability to consume 
> > content (e.g. because the screen reader hasn't gotten to it yet) will 
> > miss notifications. Better, IMHO, to have a way to say whether a 
> > notification is ephemeral or should be kept until acknowledged, then 
> > let the OS decide what the former's timeout is. (Of course you'd still 
> > need .cancel(), but it would be only for when the notification is no 
> > longer useful, not for a timeout.)
> 
> Since we will have .cancel() in any event, nothing prevents an author 
> from writing their own timeout.
>
> The spec is still written with the intent to allow the notification 
> platform (or OS) to close notifications as it sees fit -- perhaps this 
> is not sufficiently explicit although the description of the onclose 
> event handler mentions it.  The problem with exposing ambient vs. 
> persistent in the API is that it could lead to abuse of persistent 
> notifications (in fact the requirements section for the spec explicitly 
> states that we should not require implementations to support persistent 
> notifications).
> 
> Perhaps the best spec change is to improve the clarity that 
> notifications may be closed according to UA or platform logic after 
> being shown, and to remove the example or provide a disclaimer.

At a minimum, all the examples in the spec should show best practices, 
since they are going to be copied and pasted all over the Web.


> > As currently specced, it seems a notification can only be used once 
> > ("must be invoked after the "show" event" e.g. implies there's only 
> > ever one show event), which doesn't make sense if you do keep show() 
> > rather than changing it to autoshow the notification when it is 
> > created.
> 
> It's the intent that a notification can only be used once.  There's no 
> particular reason a notification couldn't be reused (and I could change 
> the wording accordingly), although I don't see a use case for this and I 
> believe it complicates implementation.

I strongly recommend getting rid of the show() method, which would solve 
this problem implicitly, but if you don't, you need to make it clear what 
happens the second time the method is called.


> > The API is partly defined in terms of event listeners being called, 
> > not in terms of events firing.
> >
> > 'show' is defined to fire "at the point when the notification actually 
> > becomes visible to the user" which seems to contradict the next 
> > statement "the notification will never become visible before this 
> > event is dispatched".
> 
> No distinction was intended between dispatched and fired.  The paragraph 
> was designed to explain what happens if the OS queues notifications, but 
> I suppose in all cases the event precedes the listener, so I have 
> rewritten this and the other event descriptions.

Tasks on the Web are queued on the event loop task queue, as specced in 
the HTML spec:

   http://whatwg.org/html

I strongly recommend using this model, as it otherwise is highly 
ambiguous what the order of events is.


> > The spec is partly phrased in terms of a processing model and partly 
> > in terms of constraints. This makes it ambiguous and contradictory in 
> > various ways. For example, looking at the constraints: what happens if 
> > you change replaceId after calling show() to something that conflicts 
> > with an existing notification?
> 
> Indeed -- the intent is that replaceId can not be modified after show() 
> has been called.  I have changed the API from an attribute to a method 
> which allows for the UA to enforce this rule by throwing an exception, 
> in the same way XMLHttpRequest throws if setRequestHeader is invoked 
> after send().

That is one specific case, but my comment was intended to convey a concern 
regarding the general approach used in the spec's language: that it 
mixes an imperative "processing model" approach with a constraint-based 
approach. You should pick one and use it. :-)


> The latest editor's draft is at 
> http://dev.w3.org/2006/webapi/WebNotifications/publish/Notifications.html

Cool. A few more comments:

The constructor should be described using the WebIDL syntax.

The constructor is another example of something described in descriptive 
terms without really good conformance criteria. For example, nothing in 
the constructor's description actually requires that the constructor 
returns a Notification object configured according to the arguments of the 
constructor.

In fact, I highly encourage you to move away from the old DOM spec model 
of method descriptions (the "Parameters", "No Return Value", etc, bits) as 
it tends to encourage a rather ambiguous style. In general a simple 
imperative paragraph per method or attribute is sufficient and tends to 
lead to text with much clearer conformance criteria.

"Using the algorithm defined in [HTML5]" is a bit ambiguous given how many 
algorithms are defined there. :-) I presume it means the fetch algorithm, 
but in that case a bunch of arguments need to be passed to that algorithm 
that are currently not mentioned. For example, assuming things are 
happening asynchronously, you probably want the synchronous flag set, you 
probably want to give an explicit origin, and you need to say what URL to 
fetch. I recommend looking at some examples of uses of the algorithm in 
the HTML spec.

-- 
Ian Hickson               U+1047E                )\._.,--....,'``.    fL
http://ln.hixie.ch/       U+263A                /,   _.. \   _\  ;`._ ,.
Things that are impossible just take longer.   `._.-(,_..'--(,_..'`-.;.'

Received on Tuesday, 27 September 2011 03:08:59 UTC