Gadgets XML reference

[Lane LiaBraaten]

I've been working on the Gadgets XML reference (99% from Kevin's doc circa v0.8).  Right now it's in svn in it's own file here:
http://opensocial-resources.googlecode.com/svn/spec/draft/OpenSocial-Gadget-XML.xml

My next step will be to incorporate it into the main gadgets spec which might require rearranging things a bit, so I'd like to get a few eyes on the content while its still separated.

Thanks,
Lane

 

[Jon]

Some quick comments:

I wonder if we can get rid of the "extended XSD"? Seems if someone
wants to use it, the specific container can use it and document it.

Doing a simple parity check between the XML Specification and the
Canonical Gadget XSD:

1) There's an element "Rating" under OAuth that is missing from the
XML Spec.
2) The height and width under ModulePrefs (2.4.1) do not exist in
extended XSD

There is some discussion about events, but didn't find them in in the
Gadgets API spec, and there's not enough here to do anything about
them.

On Oct 28, 11:54 am, Lane LiaBraaten <lliab...@google.com> wrote:
> I've been working on the Gadgets XML reference (99% from Kevin's doc circa

> v0.8).  Right now it's in svn in it's own file here:http://opensocial-resources.googlecode.com/svn/spec/draft/OpenSocial-...

[Lane LiaBraaten]

On Fri, Oct 30, 2009 at 1:27 PM, Jon <jon.we...@gmail.com> wrote:

Some quick comments:

I wonder if we can get rid of the "extended XSD"? Seems if someone
wants to use it, the specific container can use it and document it.

+1 for moving to a single XSD.  I've outlined the deltas below and I think the best way to make progress here is to have people provide feedback on my proposals inline below.

Doing a simple parity check between the XML Specification and the
Canonical Gadget XSD:

 1) There's an element "Rating" under OAuth that is missing from the
XML Spec.

I think this is supposed to be under ModulePrefs (not OAuth) and represent a rating like ESRB.  I propose we remove this.
 

 2) The height and width under ModulePrefs (2.4.1) do not exist in
extended XSD

They are in the extended XSD, just not the canonical one, right? See item 7 below.

3) Difference in /OAuthResourceType/@param_location
Canonical uses: auth-header, uri-query, post-body
Extended uses:  header, url, body

I propose we use the values in the canonical spec since they align with the OAuth discovery spec: http://oauth.net/discovery/#request_parameter_types

4) /Content/@type
Canonical uses: url, html
Extended uses: url, html, html-inline

I propose we keep html-inline

5) /UsePref/@datatype
Extended has "location" as a value, but I think we removed support for that.

I propose we remove the "location" datatype

6) /UserPref attributes
Extended has these extra attributes:

<xs:attribute name="urlparam" type="xs:string" use="optional"/>


<xs:attribute name="autocomplete_url" type="xs:string" use="optional"/>
<xs:attribute name="num_minval" type="xs:double" use="optional"/>
<xs:attribute name="num_maxval" type="xs:double" use="optional"/>


<xs:attribute name="str_maxlen" type="xs:int" use="optional"/>
<xs:attribute name="restrict_to_completions" type="xs:boolean" use="optional"/>


<xs:attribute name="prefix_match" type="xs:boolean" use="optional"/>
<xs:attribute name="publish" type="xs:boolean" use="optional"/>
<xs:attribute name="listen" type="xs:boolean" use="optional"/>


<xs:attribute name="on_change" type="xs:string" use="optional"/>
<xs:attribute name="group" type="xs:string" use="optional"/>

Do we need to keep any of these?  I'm not even sure what they're used for.

I propose we remove these extra attributes

7) /ModulePrefs attributes
Extended has these extra attributes:

<xs:attribute name="directory_title" type="xs:string" use="optional"/>


<xs:attribute name="author_affiliation" type="xs:string" use="optional"/>
<xs:attribute name="author_location" type="xs:string" use="optional"/>


<xs:attribute name="author_photo" type="xs:string" use="optional"/>
<xs:attribute name="author_aboutme" type="xs:string" use="optional"/>
<xs:attribute name="author_quote" type="xs:string" use="optional"/>


<xs:attribute name="author_link" type="xs:string" use="optional"/>
<xs:attribute name="show_stats" type="xs:boolean" use="optional"/>
<xs:attribute name="show_in_directory" type="xs:boolean" use="optional"/>


<xs:attribute name="string" type="xs:string" use="optional"/>
<xs:attribute name="width" type="xs:int" use="optional"/>
<xs:attribute name="height" type="xs:int" use="optional"/>


<xs:attribute name="category" type="xs:string" use="optional"/>
<xs:attribute name="category2" type="xs:string" use="optional"/>
<xs:attribute name="singleton" type="xs:boolean" use="optional"/>


<xs:attribute name="render_inline" type="xs:string" use="optional"/>
<xs:attribute name="scaling" type="xs:boolean" use="optional"/>
<xs:attribute name="scrolling" type="xs:boolean" use="optional"/>

I propose we keep width, height, and category but the rest can probably be dropped.

Thanks,
Lane

There is some discussion about events, but didn't find them in in the
Gadgets API spec, and there's not enough here to do anything about
them.

On Oct 28, 11:54 am, Lane LiaBraaten <lliab...@google.com> wrote:
> I've been working on the Gadgets XML reference (99% from Kevin's doc circa

> v0.8).  Right now it's in svn in it's own file here:http://opensocial-resources.googlecode.com/svn/spec/draft/OpenSocial-...

>
> My next step will be to incorporate it into the main gadgets spec which
> might require rearranging things a bit, so I'd like to get a few eyes on the
> content while its still separated.
>
> Thanks,
> Lane

--

You received this message because you are subscribed to the Google Groups "OpenSocial and Gadgets Specification Discussion" group.
To post to this group, send email to opensocial-an...@googlegroups.com.
To unsubscribe from this group, send email to opensocial-and-gadg...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/opensocial-and-gadgets-spec?hl=en.

[Jon]

> I propose we keep width, height, and category but the rest can probably be
> dropped.

I would propose we drop the width and height, since we have
preferred_width, preferred_height as part of the views. It seems
redundant and/or not specific enough, to have it in ModulePrefs.

[Lane LiaBraaten]

Agreed...it makes more sense to use the per-Content values.

Any opinions on my other proposals?

-Lane

[Jon]

> 4) /Content/@type
> Canonical uses: url, html
> Extended uses: url, html, html-inline
>
> I propose we keep html-inline

Are there any good implementations of "html-inline"? I know it was
used on iGoogle for a while, but no longer.

Also, if this spec is to be the contract between the gadget author and
the container/server developer, what would be the difference between
html and html-inline for the gadget developer?

From iGoogle, it seems the only place where gadget authors HAD to use
inline, was when they wanted to modify the page outside of the gadget.
Not sure we want to even go there with this spec, plus it seems most
efforts for inlines (e.g. caja) would disable this behavior.

[Lane LiaBraaten]

Ah - I got his mixed up with html-sanitized....did anyone ever implement support for that?

http://groups.google.com/group/opensocial-and-gadgets-spec/browse_thread/thread/514c9a7d9bb4fd92/

-Lane

[Kevin Brown]

On Mon, Nov 2, 2009 at 12:10 PM, Lane LiaBraaten <llia...@google.com> wrote:

On Mon, Nov 2, 2009 at 11:00 AM, Jon <jon.we...@gmail.com> wrote:

> 4) /Content/@type
> Canonical uses: url, html
> Extended uses: url, html, html-inline
>
> I propose we keep html-inline

Are there any good implementations of "html-inline"? I know it was
used on iGoogle for a while, but no longer.

Also, if this spec is to be the contract between the gadget author and
the container/server developer, what would be the difference between
html and html-inline for the gadget developer?

From iGoogle, it seems the only place where gadget authors HAD to use
inline, was when they wanted to modify the page outside of the gadget.
Not sure we want to even go there with this spec, plus it seems most
efforts for inlines (e.g. caja) would disable this behavior.

Ah - I got his mixed up with html-sanitized....did anyone ever implement support for that?

http://groups.google.com/group/opensocial-and-gadgets-spec/browse_thread/thread/514c9a7d9bb4fd92/

Shindig implemented the code, but I don't remember if we actually triggered it on the html-sanitized content type. We could certainly do it with minimal effort if the spec required it though.
 

[Tim Moore]

On Nov 2, 10:42 am, Lane LiaBraaten <lliab...@google.com> wrote:
>
> 7) /ModulePrefs attributes
> Extended has these extra attributes:
>
> <xs:attribute name="directory_title" type="xs:string" use="optional"/>

We use this. It's useful to have a directory title that is separate
from the gadget title, because the gadget title often uses user pref
substitution, so can't really be used in a directory without doing
something ugly.

I'd be OK with removing this if we add an extension that defines a
directory feature.

>
> <xs:attribute name="author_affiliation" type="xs:string" use="optional"/>
> <xs:attribute name="author_location" type="xs:string" use="optional"/>
>
> <xs:attribute name="author_photo" type="xs:string" use="optional"/>
> <xs:attribute name="author_aboutme" type="xs:string" use="optional"/>
> <xs:attribute name="author_quote" type="xs:string" use="optional"/>
>
> <xs:attribute name="author_link" type="xs:string" use="optional"/>
> <xs:attribute name="show_stats" type="xs:boolean" use="optional"/>
> <xs:attribute name="show_in_directory" type="xs:boolean" use="optional"/>

> <xs:attribute name="category" type="xs:string" use="optional"/>
> <xs:attribute name="category2" type="xs:string" use="optional"/>

More candidates for a directory feature extension. It would be nice,
of course, to support more than two categories as well.

> <xs:attribute name="scrolling" type="xs:boolean" use="optional"/>

Scrolling is useful for gadgets that might consume an unusably large
vertical height if they were to use adjustHeight instead. Although,
frankly, it might be more useful if most containers supported
scrolling by default.

+1 on everything else (except for html-inline, as discussed below)

I'd also add one more request: the XSD currently uses xs:sequence
around the child elements of /ModulePrefs/OAuth/Service where I think
using xs:all would be more author-friendly (the difference being
whether child elements must appear in the prescribed order or not). In
fact, because AFAICT most containers do not actually validate against
the schema, there exists documentation & tutorials out there on the
web that use examples that would not validate. Not to mention all of
the gadgets out there that do not validate. For example,
http://code.google.com/apis/gadgets/docs/oauth.html contains an
example gadget spec that specifies Access, Request, and Authorization
in an order that does not validate against the schema.

I might think about changing the xs:sequence around ModulePrefs,
UserPref, and Content, as well, but maybe that would create issues for
implementors if there is metadata in ModulePrefs that might affect how
Content is interpreted, for example.

-- Tim

[Lane LiaBraaten]

Thanks for the feedback everyone....I'll start incorporating this doc into the main gadgets spec today.

On Mon, Nov 2, 2009 at 2:25 PM, Tim Moore <tmo...@atlassian.com> wrote:

On Nov 2, 10:42 am, Lane LiaBraaten <lliab...@google.com> wrote:
>
> 7) /ModulePrefs attributes
> Extended has these extra attributes:
>
> <xs:attribute name="directory_title" type="xs:string" use="optional"/>

We use this.  It's useful to have a directory title that is separate
from the gadget title, because the gadget title often uses user pref
substitution, so can't really be used in a directory without doing
something ugly.

I'd be OK with removing this if we add an extension that defines a
directory feature.

Let's just keep it in for now.

>
> <xs:attribute name="author_affiliation" type="xs:string" use="optional"/>
> <xs:attribute name="author_location" type="xs:string" use="optional"/>
>
> <xs:attribute name="author_photo" type="xs:string" use="optional"/>
> <xs:attribute name="author_aboutme" type="xs:string" use="optional"/>
> <xs:attribute name="author_quote" type="xs:string" use="optional"/>
>
> <xs:attribute name="author_link" type="xs:string" use="optional"/>
> <xs:attribute name="show_stats" type="xs:boolean" use="optional"/>
> <xs:attribute name="show_in_directory" type="xs:boolean" use="optional"/>

> <xs:attribute name="category" type="xs:string" use="optional"/>
> <xs:attribute name="category2" type="xs:string" use="optional"/>

More candidates for a directory feature extension.  It would be nice,
of course, to support more than two categories as well.

Let's keep these too.  In the future we could support @categories that takes a csv or something.

> <xs:attribute name="scrolling" type="xs:boolean" use="optional"/>

Scrolling is useful for gadgets that might consume an unusably large
vertical height if they were to use adjustHeight instead.  Although,
frankly, it might be more useful if most containers supported
scrolling by default.

Should scrolling be moved to the <Content> section then, since that's where the developer specifies the preferred_height?

+1 on everything else (except for html-inline, as discussed below)

I'd also add one more request: the XSD currently uses xs:sequence
around the child elements of /ModulePrefs/OAuth/Service where I think
using xs:all would be more author-friendly (the difference being
whether child elements must appear in the prescribed order or not). In
fact, because AFAICT most containers do not actually validate against
the schema, there exists documentation & tutorials out there on the
web that use examples that would not validate.  Not to mention all of
the gadgets out there that do not validate.  For example,
http://code.google.com/apis/gadgets/docs/oauth.html contains an
example gadget spec that specifies Access, Request, and Authorization
in an order that does not validate against the schema.

This sounds good to me.

I might think about changing the xs:sequence around ModulePrefs,
UserPref, and Content, as well, but maybe that would create issues for
implementors if there is metadata in ModulePrefs that might affect how
Content is interpreted, for example.

This seems less important so let's leave the top-level elements as a xs:sequence.

Thanks,
Lane

-- Tim

[Tim Moore]

On Nov 4, 11:04 am, Lane LiaBraaten <lliab...@google.com> wrote:
> Thanks for the feedback everyone....I'll start incorporating this doc into
> the main gadgets spec today.
>

Great! Is it OK to assume, then, that the extended XSD will be
removed? My proposal will add new attributes, and it would be nice if
I could focus on just the standard.

> On Mon, Nov 2, 2009 at 2:25 PM, Tim Moore <tmo...@atlassian.com> wrote:
> > On Nov 2, 10:42 am, Lane LiaBraaten <lliab...@google.com> wrote:
>
> > > 7) /ModulePrefs attributes
> > > Extended has these extra attributes:
>
> > > <xs:attribute name="directory_title" type="xs:string" use="optional"/>
>
> > We use this.  It's useful to have a directory title that is separate
> > from the gadget title, because the gadget title often uses user pref
> > substitution, so can't really be used in a directory without doing
> > something ugly.
>
> > I'd be OK with removing this if we add an extension that defines a
> > directory feature.
>
> Let's just keep it in for now.

OK sounds good.

> > > <xs:attribute name="author_affiliation" type="xs:string" use="optional"/>
> > > <xs:attribute name="author_location" type="xs:string" use="optional"/>
>
> > > <xs:attribute name="author_photo" type="xs:string" use="optional"/>
> > > <xs:attribute name="author_aboutme" type="xs:string" use="optional"/>
> > > <xs:attribute name="author_quote" type="xs:string" use="optional"/>
>
> > > <xs:attribute name="author_link" type="xs:string" use="optional"/>
> > > <xs:attribute name="show_stats" type="xs:boolean" use="optional"/>
> > > <xs:attribute name="show_in_directory" type="xs:boolean" use="optional"/>
>
> > > <xs:attribute name="category" type="xs:string" use="optional"/>
> > > <xs:attribute name="category2" type="xs:string" use="optional"/>
>
> > More candidates for a directory feature extension.  It would be nice,
> > of course, to support more than two categories as well.
>
> Let's keep these too.  In the future we could support @categories that takes
> a csv or something.

Maybe. I still think that a directory feature extension could be
useful, as it would allow for more flexibility without having to
change the format of the gadget spec XML. In particular, now that it's
been clarified that feature params can appear multiple times, that
seems like a good way to support multiple categories.

> > > <xs:attribute name="scrolling" type="xs:boolean" use="optional"/>
>
> > Scrolling is useful for gadgets that might consume an unusably large
> > vertical height if they were to use adjustHeight instead.  Although,
> > frankly, it might be more useful if most containers supported
> > scrolling by default.
>
> Should scrolling be moved to the <Content> section then, since that's where
> the developer specifies the preferred_height?

Great idea.

> > I might think about changing the xs:sequence around ModulePrefs,
> > UserPref, and Content, as well, but maybe that would create issues for
> > implementors if there is metadata in ModulePrefs that might affect how
> > Content is interpreted, for example.
>
> This seems less important so let's leave the top-level elements as a
> xs:sequence.

Agreed.

Thanks,
-- Tim

[Jon]

While doing other work, it occurred to me, is there any discussion on
what the values are for the view attributes?

Seem the Gadget Spec has things like "gadgets.views.ViewType.CANVAS",
and in Shindig it is "canvas". Not sure there is any real
specification on case sensitivity for view names.

[Kevin Brown]

This is another one of those items that got buried. The constants were essentially scrapped at some point, but I honestly don't remember the discussion any more.

[Tim Moore]

I'm reviewing the full document now, and I have a few further
comments:

Section 2.2 Parsing

"Containers MUST NOT reject XML documents that are not valid (as
mandated by the canonicaland extendedschema definitions), as long as a
valid document can be derived from the markup that exists. This means
that Containers MUST ignore any attributes or tags that they can not
interpret. This requirement is included to facilitate extensions to
the schema for Container-specific uses."

This requirement limits the usefulness of the schema. If it is a
requirement we need, I'd suggest that it might be better to include
wildcards in the schema:

http://www.w3.org/TR/xmlschema-1/#Wildcards
http://www.w3.org/TR/xmlschema-0/#any

This would allow implementations to use a schema validator to ensure
that the parts of the document that *are* part of the schema are
correct, while still allowing additional elements and attributes.

Additionally, it would allow the validator to automatically enforce
the requirement that "Containers MAY support non-standard tags and
attributes, but they MUST be enclosed in a separate XML namespace."

The drawback is that if we want to allow additional elements and
attributes everywhere, then it would clutter up the schema a lot,
because we'd have to add wildcards all over the place. It would be
easy to miss places, too, especially as the format evolves in the
future.


But I wonder whether this is something we really want to allow in the
first place. If a gadget depends on some container-specific extension
to the spec format, and it's installed in some other container that
silently ignores the requirement, it could break in some subtle,
confusing, and perhaps even dangerous way. This extension method
doesn't have any standard way to gadgets to declare whether they
depend on a particular extension or simply make use of it when
available, and doesn't provide a way for gadgets to even know whether
the container supports the extension. On the other hand, features
satisfy all of these requirements. IMO containers should be encouraged
to use features rather than changes to the spec format whenever
possible.

Are there existing examples of where containers other than iGoogle
have extended the spec format? Can these be migrated to feature
extensions?

This does create a backwards-compatibility issue, so maybe it's too
late to change...

Section 2.4 Module

General comment on this whole section: I think it would be good to be
explicit about which child elements and attributes are required and
which are optional for each element.

Section 2.4.1 /ModulePrefs

The Google Gadgets XML reference at http://code.google.com/apis/gadgets/docs/reference.html
includes some additional guidelines for screenshot and thumbnail:
---
screenshot

Optional string that gives the URL of a gadget screenshot. This must
be an image on a public web site that is not blocked by robots.txt.
PNG is the preferred format, though GIF and JPG are also acceptable.
Gadget screenshots should be 280 pixels wide. The height of the
screenshot should be the "natural" height of the gadget when it's in
use.

thumbnail

Optional string that gives the URL of a gadget thumbnail. This must be
an image on a public web site that is not blocked by robots.txt. PNG
is the preferred format, though GIF and JPG are also acceptable.
Gadget thumbnails should be 120x60 pixels.
---
I think it would be good to preserve that text.


Section 2.4.1.5 /ModulePrefs/Link

"Containers MAY support additional values, but they MUST be namespaced
to avoid collisions."

I think it could use additional detail explaining what's meant by
"namespaced" (is it just prefixed with the vendor name like
"google.foo" or "atlassian.bar"?)


Section 2.4.3 /Content

I think it would be helpful to note that the text within this element
is typically wrapped in CDATA to allow you to use HTML tags without
them being interpreted by the XML parser, and without having to
explicitly escape them.


Section 3. Variable Substitution

Looks like it's missing some line breaks in the MSG description.

"Containers MUST perform substitution on all elements and attributes
defined in Elements and Attributes (Section 2.3), with the exceptions
of /ModulePrefs/Locale (and children), or any element with an explicit
enumeration. Containers MUST NOT perform substitution on the raw text
of the XML."

This isn't totally clear to me. The intent is that all attribute
values and text content should be substituted (except where noted),
right? The second sentence is meant to require that element and
attribute names themselves aren't substituted?


Section 8.2 Optional Features

This is missing setprefs. That's always been a weird one, though,
since it adds methods to gadgets.Prefs rather than defining its own
namespace. I'd be pretty happy to make that API core & required, and
define the behavior if the container can't save prefs (which might be
the case in some situations for containers where the feature is
available, too).

On Oct 28, 10:54 am, Lane LiaBraaten <lliab...@google.com> wrote:
> I've been working on the Gadgets XML reference (99% from Kevin's doc circa

> v0.8).  Right now it's in svn in it's own file here:http://opensocial-resources.googlecode.com/svn/spec/draft/OpenSocial-...

[Lane LiaBraaten]

Thanks for the thorough review, Tim.  All your comments make sense...I've been tracking the laundry list of TODOs for this proposal on this page: http://wiki.opensocial.org/index.php?title=Add_gadgets_XML_reference_to_the_spec#TODO

I think we should continue to support arbitrary markup and allow the containers to ignore it.  Containers can still use the "feature" mechanism to extend the markup.  For example <Require feature="SpecialTag"/> would guarantee that the gadget can use the <Special> element.  A container that doesn't support <Special> wouldn't render the gadget because it doesn't support "SpecialTag"

I'll look into adding wildcards/any to the schema :/

-Lane

[Mark W.]

Re: Schema validation of the gadget definition...
When I first started learning about OpenSocial, it surprised me that
there were no extension elements in the schema. My initial thought was
since we were not a 1.0, it was probably easier anyway b/c you didn't
have to worry about validating a gadget doc. You could change things
more easily/quickly and as long and you could derive the "old" stuff,
life was good.

Tim rightly points out that this gets messy quickly. Other specs,
notedly OVF, have struggled with this issue as well. Not only does it
get messy in terms of schema and document readability, but forward/
backward compatibility and schema evolution becomes more difficult. I
used to be a big believer in schema validation--it helps with tools,
processing, et.--but having gone through this, I'm much more open to
"relaxed schema validation". Container specific extensions start to
become a slippery slope and really defeat the purpose of an open spec.
Gadgets, should not be forced to depend on an extension, and providers
should not be forced to implement something that they don't need, so
it makes sense that no extension can be a MUST.

Would a reasonable approach be to provide a single "extension point"
at the end of the schema that contains a wrapper element with an xml
wild card in it? Essentially, try to encapsulate/compartmentalize
extensions to their own documents. Implementors (e.g. shindig) could
then provide a handler/strategy approach based on the namespace of the
extension that would provide processing/validation of the content.

On Nov 5, 5:53 pm, Lane LiaBraaten <lliab...@google.com> wrote:
> Thanks for the thorough review, Tim.  All your comments make sense...I've

> been tracking the laundry list of TODOs for this proposal on this page:http://wiki.opensocial.org/index.php?title=Add_gadgets_XML_reference_...

> > opensocial-and-gadg...@googlegroups.com<opensocial-and-gad gets-spec%2Bunsu...@googlegroups.com>
> > .