Re: [widgets] Interface published

On Thu, Nov 19, 2009 at 2:03 PM, Kai Hendry <hendry@aplix.co.jp> wrote:
> http://git.webconverger.org/?p=faq;a=commit;h=1f335b2997aedb034ca92d06bf815c623939179e
>
> Please forgive the informal prose.
>

Yeah, like we are soooooo serious here! :P If it makes you feel
better, I'm responding to your email in my pajamas :)

But yeah, lets keep it professional.

>
>
>
>
> This late rant is prompted by [Widget interface spec (Last
> Call)](http://twitter.com/widgetspecs/status/5799561554).
>
> Widget APIs or rather [Widgets 1.0: The widget
> Interface](http://www.w3.org/TR/widgets-apis/) is largely about exposing what's
> defined in the widget [configuration
> document](http://dev.w3.org/2006/waf/widgets/Overview.html#configuration-document)
> to the Widget developer.
>
> **WHY?** You may rightly ask. The widget developer should know his own name and
> email address whilst writing a function to mail him a [bug
> report](http://www.w3.org/TR/widgets-apis/#metadata-attribute-values). I guess
> someone has argued that slapping new `widget.` attributes makes it easier for
> library developers. [BONDI](http://bondi.omtp.org/) incidentally rightly (imo),
> didn't bother with this mapping.

I agree. Accessing all the config file metadata is kinda pointless.

> Another reason WHY pointed out by
> [robin](http://twitter.com/robinberjon/status/5825994237) is that the simple
> Widget interface exposed by the widget runtime, would implement
> [locale support](http://dev.w3.org/2006/waf/widgets/Overview.html#locale-folder0)
> and give you the localised interface. I.e. it's doing a bit of work behind the
> scenes for the convenience of Widget developers and well...  non-English
> speakers. However again, one can argue that Widget developers can implement
> their own locale support, which isn't that hard (they have probably done it
> before), but it would probably suck.
>

This is true. One is certainly free to do that, but I don't know why
you would if you get it for free in widgets.

> Ok, in an [example](http://dev.w3.org/2006/waf/widgets/Overview.html#configuration-document)
> Widget configuration file, like `config.xml`, you might find:
>
>        <widget xmlns="http://www.w3.org/ns/widgets"
> id="http://bondisdk.limofoundation.org/widget/webcmd" version="0.4.2"
> viewmodes="fullscreen">
>
> Which maps onto the [Widget interface](http://www.w3.org/TR/widgets-apis/) as:
>
>        widget.id = "http://bondisdk.limofoundation.org/widget/webcmd";
>        widget.version = "0.4.2";
>
> Though what about viewmodes? Hmm...

Viewmode attribute would be defined by the viewmode spec. Viewmode
also relates to CSS.

> Then:
>
>        <name short="WebC">Web Commander</name>
>
> Maps as:
>
>        widget.name = "Web Commander";
>        widget.shortName = "WebC";
>
> Ok, the attribute `short` was used as a prefix to `name` which has
> become capitialised in order to make it easier to distinguish. Ok,
> fine. However this is there is _an inconsistency_ with:
>
>        <author href="http://bondi.limofoundation.org/"
> email="sdk@bondisdk.org">LiMo Foundation</author>
>
> Maps to the Widget interface like so:
>
>        widget.author = "LiMo Foundation";
>        widget.authorEmail = "sdk@bondisdk.org";
>        widget.authorHref = "http://bondi.limofoundation.org/";
>
> Now the author element attributes like `email` and `href` become
> suffixed to `author`. You see how `shortName, should be **nameShort**?

do'h! Might not be too late to change that. We will put in on the
agenda for discussion. I need to check who has implemented that so far
(if anyone!). If no one has implemented, then I will change it.

> Other elements can be found on the `config.xml` such as:
>
>          <feature name="http://bondi.omtp.org/api/ui" required="true"/>
>          <license href="http://bondi.omtp.org/BONDI-LICENSE-2.0/"/>
>          <content src="index.html"/>
>          <feature name="http://bondi.omtp.org/api/appconfig" required="true"/>
>          <feature name="http://bondi.omtp.org/api/filesystem" required="true"/>
>
> However there is no mapping to the [Widget
> interface](http://www.w3.org/TR/widgets-apis/). Who decides what gets mapped
> and what doesn't? Wouldn't it be simpler and more consistent to just map
> everything?

No.
Re: license, see:
http://lists.w3.org/Archives/Public/public-webapps/2009OctDec/0515.html

Features, if they are APIs, are made available as defined by their
respective specifications (e.g., on the Window object).  And you are
looking at the content already (document.location).

> It does get tricky especially thinking about the possible multiply
> nested <http://dev.w3.org/2006/waf/widgets/Overview.html#the-param-element>.
>
> Also some punks might overload the `config.xml` with  _openURL_ which
> would clash.

No, openURL is spec'ed to ignore relative references.

> I understand some elements like the [feature
> elements](http://dev.w3.org/2006/waf/widgets/Overview.html#feature)
> and undefined (proprietary) elements like:
>
>        <access network="false" localfs="false" remote_scripts="false"/>
>        <billing required="true"/>

OMG! What's that billing thing!?!?!? and that access element does not
comply to WARP :)

> ..are perhaps only relevant and used by particular runtimes, though
> shouldn't there be convention and reasoning for why (and why **not**)
> certain interfaces are exposed in the [widget interface
> specification](http://www.w3.org/TR/widgets-apis/)?

No. That's beyond the scope of our work. Implementers are free to do
whatever they want with their proprietary extensions.

> If the <http://www.w3.org/TR/widgets-apis/#the-preferences-attribute> was
> mandatory, which I think it should be since many widgets I've come across rely
> on **setPreferenceForKey** and **preferenceForKey** conventions, wouldn't it be
> sensible to put the interfaces all into this **preference** [Web
> storage](http://www.w3.org/TR/webstorage/) mechanism?
>
> Consider read-only keys like:
>
>        widget.getItem("name")
>        widget.getItem("nameShort")
>        widget.getItem("authorEmail")
>        widget.getItem("licencseHref")

I think I have misunderstood what you said, but polluting the
widget.preferences object would be wrong because one would expect it
to be clean from the start. Any time you wanted to iterate over the
keys, you would need to have code to skip over those preset keys (that
would be bad). Also, it would be confusing when calling
preferences.clear(), etc.

However, a generic "getItem" might have been nice (and extensible)
means at getting at the metadata of the config doc. However, it's a
bit late to be having this discussion 3 years after this spec has been
on the table.

> Though perhaps ideally when you did a `widget.getItem`, you received the JSON
> representation of the XML fragment. Though I'm not entirely sure if there is a
> standard way to map XML onto JSON. You might as well canonicalise the whole
> `config.xml` as a JSON string bound to **widget.config**. There, simple.  Or
> `innerXML` if a JSON translation isn't possible.

Don't go crazy :) I think it would be fine to just pass back the
textContent, or value if it is an attribute.

> Btw the Widget interface as it stands are all readonly except for
> [preferences](http://www.w3.org/TR/widgets-apis/#the-preferences-attribute) and
> [openURL](http://www.w3.org/TR/widgets-apis/#the-openurl-method).
>
> # widthxheight
>
> It's unclear to me if
> [width](http://www.w3.org/TR/widgets-apis/#the-width-attributes) and
> [height](http://www.w3.org/TR/widgets-apis/#the-height-attribute) map to the
> `config.xml` or the real actual viewport size.

The P&C spec sez:

"A numeric attribute greater than 0 that indicates the preferred
viewport height of the instantiated custom start file in CSS pixels
[CSS21].

    Authoring Guidelines: It is optional for authors to use the height
attribute with a widget element. This value is only applicable to
particular view modes, meaning that for certain view modes this value
is ignored. The view modes that honor the value of the height
attribute are defined in the [Widgets-Views] specification.
"

In other words, <widget width/height> are just a sizing hints.

The TWI spec sez:
"Upon getting the width/height  attribute, a user agent must return an
number that represents the width of the widget instance’s viewport in
[CSS21] pixels."

That is, the pixels that represent the size of the view port (the area
that is being rendered).

> Surely one can defer to
> `window.screen.width` and `window.screen.height` instead? I know it says
> `screen`, but just imagine it says `viewport`?

No, screen.width and screen.height means the screens width and height
(like 640x480)! not the viewport's width and height (apples and
oranges).

Also, HTML5's Window interface does not define the screen object... if
the bible does not says it exists, then it does not exist :)

> # My final proposal Widget interface proposal after thinking about it
> for two hours
>
>
>        interface Widget {
>                readonly attribute DOMString     config; // innerXML or rather JSON
> representation of configuration document
>                readonly attribute Storage       preferences; // key value
>                void openURL(in DOMString iri);
>        };

I like the last two :)

Kind regards,
Marcos


-- 
Marcos Caceres
http://datadriven.com.au

Received on Wednesday, 25 November 2009 14:52:58 UTC