Homescreen "embedding" api

[Fabrice Desré]

In b2g we have a need for bi-directionnal communication between the
chrome and the homescreen application. Use cases include currently the
notification API and some calls of the open web apps API (at least the
install() and launch() calls).

In bugs 736312 and 735947 we use custom events dispatched to the
homescreen window and carry information in the event.detail property.
While this works, we're not thrilled by this approach, and don't want to
keep adding event types this way.

Another option is to design a proper "embedding" API.

It could look like:

interface NotificationEvent : Event {
Notification notification;
}

interface mozEmbed : EventTarget {
attribute DOMEventListener onnotification; // fired when the
homescreen must show a notification.
void notificationClicked(in Notification notification);
void notificationClose(in Notification notification);
}

Should we keep a flat structure in mozEmbed, or go with something like:

interface mozEmbedd {
readonly attribute mozEmbedNotifications notifications;
readonly attribute mozEmbedApps webapps;
}

interface mozEmbedNotifications : EventTarget {
attribute DOMEventListener onnotification; // fired when the
homescreen must show a notification.
void notificationClicked(in Notification notification);
void notificationClose(in Notification notification);
}

interface mozEmbedApps : EventTarget {
attribute DOMEventListener onapplaunch; // fired when the homescreen
must launch an app.
attribute DOMEventListener onappinstall; // fired when the homescreen
must show an install dialog for an app.
void appInstallGranted(in DOMApplication app);
void appInstallDenied(in DOMApplication app);
}

Thoughts?

Fabrice
-- Fabrice Desré b2g Team Mozilla Corporation

[Jonas Sicking]

I like the approach of keeping things flat. That'll make it easier to
add more notification types in the future. However I think we need to
pass more complex information around.

First of all we need to pass information from Gecko to the homescreen
app regarding what to show in the notification. For example for a "Do
you want to allow this application to have access to your camera"
there are several pieces of UI that needs to be rendered:

* The origin of the page displaying the prompt (and if we have an EV
cert, the name of the company which owns the cert).
* The text which describes that camera access is being granted
* Text from the website describing why it's requesting camera access
* The text in the "allow" button
* The text in the "deny" button
* Whether the "remember this decision" checkbox should be checked by
default or not (and possibly whether it should be displayed at all).
* The text for the "remember this decision" checkbox
* An icon
* A title

That is assuming we go with the two-button+checkbox approach.
Currently in Firefox we have a slightly different UI which results in
slightly different set of strings.

For the data passed back to gecko we need the following:

* Which button was pushed
* Whether the "remember this decision" checkbox was checked


Other notifications have other pieces of information. For example the
HTML window.prompt() function causes a notification to be displayed
which has a textbox where the user can enter some information. This
information is then passed back to the page. For that notification we
need the following information:

* The origin of the page displaying the prompt
* The text to display in the dialog

And then we need to pass back to gecko the string that was typed.


Finally there are things like the getUserMedia which will display a
notification similar to the one described here:
http://people.mozilla.com/~jboriss/specs/first_spec.png

This is a significantly different type of notification with
significantly different data being passed back and forth.

The point is that the data we're going to need to pass back and forth
is significantly different based on what type of dialog it is. So we
need to keep the API pretty flexible so that we can pass JSON-objects
back and forth which different type of data for different types of
notifications.

/ Jonas

[Chris Jones]

----- Original Message -----
> From: "Fabrice Desré" <fab...@mozilla.com>
> To: dev-w...@lists.mozilla.org
> Sent: Friday, March 16, 2012 2:03:02 PM
> Subject: Homescreen "embedding" api
>
> Should we keep a flat structure in mozEmbed, or go with something
> like:
>

I favor making the "embedding APIs" orthogonal, since there'll likely be separate apps/components that implement them in the long run.

I'm not too enthralled with the name "embed", but I like the approach. Mirroring the content API where possible (content events |foo| become |void foo(...)|, content functions |bar(...)| become |onbar| events), seems righteous.

Cheers,
Chris

[Mounir Lamouri]

On 03/17/2012 02:53 AM, Jonas Sicking wrote:
> The point is that the data we're going to need to pass back and forth
> is significantly different based on what type of dialog it is. So we
> need to keep the API pretty flexible so that we can pass JSON-objects
> back and forth which different type of data for different types of
> notifications.

I think we need an API that would look like:
void notify(DOMString type, DOMString data);

and in the other side:
void listen(DOMString type, Function callback);
(listen is a placeholder name)

That should be flexible enough.

However, I'm wondering if we could merge this API and the Browser API.
Both are about sending events from an inner content to a top level
window and get events back, right?

--
Mounir

[Jim Straus]

I'm re-opening this tread as I have need of this API. We seem to have to different styles here, a very generic API and more directed (set of ) APIs. I'm personally in favor of being generic and letting a receiver dispatch biased on type as needed, but I know Fabrice is concerned about it. This email is to see if we can reach a consensus quickly.
Jim Straus

> _______________________________________________
> dev-webapi mailing list
> dev-w...@lists.mozilla.org
> https://lists.mozilla.org/listinfo/dev-webapi

[Jonas Sicking]

I'm personally fine either way. I think we'll need to do a lot of
experimenting and testing before we have a solution we like enough to
submit for standardization, so I think we should simply do that
experimenting.

/ Jonas

[Chris Jones]

Concerned here about "Homescreen" here. Not trying to pick nits with names too much, but I want to make sure we don't unduly bias the discussion based on one possible UX/UI design.

----- Original Message -----
> From: "Mounir Lamouri" <mou...@lamouri.fr>
> To: dev-w...@lists.mozilla.org
> Sent: Wednesday, March 21, 2012 10:52:42 AM
> Subject: Re: Homescreen "embedding" api
>
> On 03/17/2012 02:53 AM, Jonas Sicking wrote:
> > The point is that the data we're going to need to pass back and
> > forth
> > is significantly different based on what type of dialog it is. So
> > we
> > need to keep the API pretty flexible so that we can pass
> > JSON-objects
> > back and forth which different type of data for different types of
> > notifications.
>
> I think we need an API that would look like:
> void notify(DOMString type, DOMString data);
>
> and in the other side:
> void listen(DOMString type, Function callback);
> (listen is a placeholder name)
>
> That should be flexible enough.
>

I don't like this approach. My preference is for privileged "mirror" APIs allowing content to implement the "backend" of other content interfaces, specific to each interface being mirrored. For an API Foo exposed to content

Foo:
void bar(a, b);
listener onbaz; /* for event with data {x} */

have

MirrorFoo:
listener onbar; /* for event with data {a, b} */;
baz(x);

That way we have a clearer sense of what we're exposing to content and finer-grained permissions.

But maybe we need more use cases to figure this out.

> However, I'm wondering if we could merge this API and the Browser
> API.
> Both are about sending events from an inner content to a top level
> window and get events back, right?
>

No thank you! :) However, a browser app would need to implement some of these mirror APIs.

Cheers,
Chris

[Mounir Lamouri]

On 03/29/2012 02:15 PM, Jim Straus wrote:
> I'm re-opening this tread as I have need of this API. We seem to have to different styles here, a very generic API and more directed (set of ) APIs. I'm personally in favor of being generic and letting a receiver dispatch biased on type as needed, but I know Fabrice is concerned about it. This email is to see if we can reach a consensus quickly.

Given that this API is experimental, I would prefer to reduce the
footprint. In addition, it is very likely that we will end up with a lot
of message types to send between the homescreen and the apps so having
two generic methods seem way better than a few dozens of listenFoo() and
notifyFoo() methods.

--
Mounir

[Mounir Lamouri]

On 03/21/2012 10:52 AM, Mounir Lamouri wrote:
> However, I'm wondering if we could merge this API and the Browser API.
> Both are about sending events from an inner content to a top level
> window and get events back, right?

Any opinion about this?

--
Mounir