Re: comments no the web notifications spec

Thanks for the comments Ian.  Sorry to the group for the delay in addressing
these; I got through the first few quickly then was swept up in work.

 -John

On Thu, Jun 30, 2011 at 1:47 PM, Ian Hickson <ian@hixie.ch> wrote:

>
> Just some quick comments since Anne asked #whatwg to take a look:
>
> 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.  I would cite XMLHttpRequest
as a very similar pattern.


> 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.

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.  See above for the motivation for show().


>
> 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.


> 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().

Not clear what "The dir attribute of the Notification interface has has
> all the properties of the dir attribute as defined in [HTML5]" means...
> does it mean it's a content attribute, e.g.? I recommend making that just
> self-defined instead of referring to the HTML spec.
>

I have changed this.


> "may ignore any markup in this string" doesn't make any sense. If I have a
> notification whose body is "Go to meeting about the <video> element", what
> should the notification say?
>
>
This has come up several times; I've changed the spec to say that the user
agent must do whatever is necessary w.r.t. the underlying notification
platform to cause the string to show exactly as passed in.  I personally had
thought this is too demanding for all implementations on all platforms,
where some user agent might, knowing the platform allows it, pass along <b>
or <i> and get that result.  But that's what web-content Notifications are
for anyway.


> Also it would be good if there was an unambiguous URL one could visit to
> find the latest changes to this spec. Right now the editor's draft seems
> broken and the TR/ page is presumably not what's getting updated.
>

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

I think the link to editor's draft in the working draft should be changed to
point there, but I'm not sure how do to that.