gadget manifest proposal

[goosemanjack]

This is a new resurrection of the gadget manifest proposal. It is
very thin at start, so will need a bit of work to flesh out.

Purpose: As the OpenSocial spec matures and containers begin to
support multiple versions, there needs to be a way for gadgets to
specify multiple source gadget XML files for various situations. This
will be handled by a single manifest file that identifies to the
container which gadget XML file to utilize based on supported
features.

Objective: This proposal should satisfy the need for a manifest while
allowing for backwards compatibility of existing gadgets already
deployed in production.

Specifics:
=================

Location of the manifest:

When uploading a gadget, the developer may specify either the URL of a
gadget XML file OR the URL of a gadget manifest file. The manifest
file will point to the actual gadget XML file URL based on version and
features required/supported. For backwards compatibility purposes,
the gadget XML file may also contain a reference back up to its
manifest file URL. In this way containers that do not support the
manifest feature will still function with their existing gadget XML
sources, and newer containers that do support the manifest feature can
take advantage of its ability to specify multiple gadgets for
different scenarios. This will be done via an optional "gadget-
manifest" feature specified in ModulePrefs.

example:

(an existing gadget in production referenced at: http://example.org/samplegadget/gadget.xml)

<Module>
<ModulePrefs title="Manifest sample gadget" description="Example
showing usage of manifest">
<Require feature="opensocial-1.0"/>
<Optional feature="gadget-manifest">
<Param name="manifest">http://example.org/samplegadget/
manifest.xml</Param>
</Optional>
</ModulePrefs>
...
<Module>


(manifest file at http://example.org/samplegadget/manifest.xml

<GadgetManifest>

<Gadgets>
<Gadget os-version="1.0" gadget-version="2.1" status="released"
src="http://example.org/samplegadget/gadget.xml" />
<Gadget os-version="1.0" gadget-version="2.2" status="development"
src="http://example.org/samplegadget/gadget-dev.xml" />
<Gadget os-version="0.8" src="http://example.org/samplegadget/
gadget.os08.xml" />
<Gadget os-version="1.1" src="http://example.org/samplegadget/gadget.
11.xml">
<Features>
<feature name="templates" required="true" />
<feature name="html-6" required="false" />
</Features>
</Gadget>
</Gadgets>

</GadgetManifest>




Processing:

If the container supports the gadget-manifest feature, it attempts to
download the manifest file from the referenced location. It then
selects the source most appropriate to its supported opensocial
version and features. This is true if the manifest file is directly
referenced as the source, or if a gadget file is referenced which
contains a gadget-manifest features. Older containers which do not
support the gadget-manifest feature will simply ignore this directive
and utilize the referenced gadget XML file.

[rbaxter85]

I think having version numbers for gadgets is a great idea, and I
agree it is necessary. However I am not convinced there needs to be a
separate manifest for this. Can you explain why this is necessary?

> (manifest file athttp://example.org/samplegadget/manifest.xml

[Matthew Marum]

This proposal seems to be related to the View level feature proposal.
http://docs.opensocial.org/display/OSD/View+Level+Feature+Proposal

With view level features you could have multiple views that use different features, rather than having different gadgets using different features.  View level features allows for more granularity.  For example, you could have a mobile view that uses different features than a canvas view for the same gadget.  My initial thinking is to allow optional ViewPrefs elements in the Gadget XML.

<Module>
    <ModulePrefs>
        <Require feature="opensocial-1.1" />
        <Require feature="views" />
    </ModulePrefs>
    <ViewPrefs view="mobile">
       <Require feature="mobile_feature" />
    </ViewPrefs>
    <Content type="html" view="mobile">
       <![CDATA[ ... ]]>
    </Content>
</Module>

Support of different opensocial versions could be accomplished by having different views (or subviews?) that support each version into the gadget.  (I haven't yet looked at how difficult implementing this in the container could be.)

<Module>
    <ModulePrefs>
        <Require feature="views" />
    </ModulePrefs>
    <ViewPrefs view="canvas.os11">
        <Require feature="opensocial-1.1" />
    </ViewPrefs>
    <Content type="html" view="canvas.os11">
       <![CDATA[ ... ]]>
    </Content>
</Module>

Do you think this could be made to accomplish the same goals as a gadget manifest?  Any thoughts?

[Matthew Marum]

fwiw, the view level feature proposal is currently much simpler than what was specified below.  The wiki is updated with the latest.

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

[rbaxter85]

While I agree you could use view level features to accomplish
versioning, in my opinion it is not as clean as introducing versioning
to the spec. Plus you may want to version your gadgets for other
reasons than the gadget leveraging new versions of features.

On Jan 13, 11:22 pm, Matthew Marum <mgma...@gmail.com> wrote:
> fwiw, the view level feature proposal is currently much simpler than what
> was specified below.  The wiki is updated with the latest.
>

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

[goosemanjack]

(added proposal as a doc page: http://docs.opensocial.org/display/OSD/Gadget+Manifest+File)

I do see some overlap with the View Level Features proposal, but I
think the use cases are very different. As I understand it, the value
of view-level features is that the container can optimize the client
code being sent down the wire and restrict the server-side processing
if a particular feature is only needed on a specific view(s).

The manifest proposal is more targeted to authors who are trying to
deploy the same gadget across multiple containers and/or who want to
manage gadget source code versions.

Use Case 1: Multiple container deployment

Gadget developer wants their gadget available on a number of
containers. Container A currently only supports spec level 1.0.
Container B currently supports spec level 2.0. Gadget is already
deployed to both Container A and Container B. Author updates gadget
to add features only available in 2.0 spec. Original (1.0) gadget has
gadget-manifest features added in module prefs to point to new
manifest file. Container B, being a 2.0 container, recognizes the
manifest file and traces back through the manifest to start using the
newer 2.0 gadget source automagically. Container A, being a 1.0
container, ignores the optional "gadget-manifest" feature and
continues to serve the older version that it supports.

Use Case 2: Gadget source versioning

Gadget developer wants to be able to switch back and forth between a
live and development version of their gadget. Instead of registering
and managing 2 distinct gadgets with the container, operating under
two different OAuth keys (as we currently see), developer specifies
the location of the live and development version of their gadget
source with the manifest file.

[rbaxter85]

I still don't see why we need a separate manifest file to introduce
versioning. Could you elaborate more on this design?

[Matthew Marum]

Ok, I understand your scenario a bit better.

I agree with Ryan though that defining a new XML file isn't necessarily required, you could accomplish the same thing by introducing new elements to the existing Gadget XML.  I don't think this should cause problems as far as compatibility since Shindig simply ignores unknown elements in the Gadget spec and I would expect most other containers to do the same.

For example...

<Module>
  <ModulePrefs title="Manifest sample gadget" description="Example showing usage of manifest">

    <Gadget os-version="1.0" gadget-version="2.1" status="released" src="http://example.org/samplegadget/gadget.xml" />
    <Gadget os-version="1.0" gadget-version="2.2" status="development" src="http://example.org/samplegadget/gadget-dev.xml" />

    <Gadget os-version="0.8" src="http://example.org/samplegadget/gadget.os08.xml" />
    <Gadget os-version="1.1"  src="http://example.org/samplegadget/gadget.11.xml"/>
  </ModulePrefs>
  ...
</Module>

And you could still use the Optional "gadget-manifest" feature your proposed to indicate where to find the manifests.

[goosemanjack]

That does seem like a more elegant solution than having a new XML
file. Let me see about re-working the proposal with your suggestions
to eliminate the external manifest. I'll post when I have an updated
doc.
--
clc

[rbaxter85]

Matt, I guess I am still stuck on the need to specify each version of
the gadget. Even if everything is in the gadget definition I still
don't see the value of each gadget definition containing a list of
other versions. I agree the concepts of versions is a great idea,
mainly for maintenance and installation of newer gadgets into the
container.

I think we need to define the use cases a little more....

Are we trying to accomplish something similar to what an update site
accomplishes with Eclipse features? Eclipse can check an update site
for newer versions of features that may or may not already be
installed into the platform. If the update site contains a newer
version of a feature thats already installed than it will allow you to
install the newer version. I could imagine a similar concept for
containers and gadgets. If this is something you are trying to
accomplish, than yes I can imagine having a gadget manifest. However
we also need to define this concept of an update site...

[Matthew Marum]

As I understand it,  the idea is to have a single entry point and allow context to select the appropriate gadget to be rendered.  This wouldn't necessarily always be the "latest" version of the gadget, so maintaining version information and other metadata may be important.

I see the advantage of a stable entry point for maintainability and ease of use.  I think view level features cover this in part since a single gadget definition could be developed for different kinds of containers, but that puts the responsibility on the gadget developer to build their gadget in way that is compatible many containers.  But if you already have old gadgets that work on outdated containers, why not reuse them rather than build backwards compatible gadgets?

Maybe what's really needed is a common gadget catalog format that could support programmatic or user driven selection of gadgets.  So something like an "update site."

Matt

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

[Mark W.]

There are a few areas of the spec that talk about versioning. The ones that come to mind are section 7 of core gadget
and section 4.1.1.1. In here, we talk about the @specificationVersion="1.0" , which seems analogous to "os-version". As we think through this, we should make sure that we are consistent with what we've already defined.

That said.... One of the really nice things about OpenSocial is it's simplicity. Having multiple gadget specs and a manifest seems to increase the overall management burden of the app developer. I'd like to keep this app simple.

[goosemanjack]

Yes, the "Update Site" a la Eclipse is a specific use case envisioned
in this. I've updated the proposal to include both embedded and
external manifest information. I tried to merge Matthew's proposal
with the existing Require/Optional/Param syntax used for other
features. The downside is that the Param element must be extended to
support several new attributes, so it's not a completely clean
proposal.

In reviewing all this I still see the need for a single, stable entry
point as a master record. The downside of embedding this information
is that it requires copy-and-paste code synchronization, which will be
error prone.

While the view-level features proposal has overlap, I don't see the
two as being mutually exclusive. Rather, I see them as complementary
and solving different use cases. View-level features really seems
tuned for allowing the container to optimize output. The manifest
proposal is more for versioning.

--
clc

On Jan 24, 9:52 pm, "Mark W." <weitzelm.w...@gmail.com> wrote:
> There are a few areas of the spec that talk about versioning. The ones that

> come to mind are section 7 of core gadget<http://opensocial-resources.googlecode.com/svn/spec/1.1/Core-Gadget.x...>
> and section 4.1.1.1<http://opensocial-resources.googlecode.com/svn/spec/1.1/Core-Gadget.x...>.

[Randy Hudson]

>         <Optional feature="gadget-manifest">
>           <Param name="manifest">http://example.org/samplegadget/
> manifest.xml</Param>
>         </Optional>

I don't understand this pattern of putting information about the
gadget into optional features with parameters. Can't we just define
new elements and/or attributes and add them to the XSD? It might mean
there's a little more work involved in patching the Spec, but it would
make life easier for developers trying to implement the new version,
and for gadget authors who are likely to only have standard XML tools
at their disposal.

[Randy Hudson]

On Jan 24, 9:05 pm, rbaxter85 <rbaxte...@gmail.com> wrote:
> install the newer version.  I could imagine a similar concept for
> containers and gadgets.  If this is something you are trying to
> accomplish, than yes I can imagine having a gadget manifest.  However
> we also need to define this concept of an update site...

They are the same thing. The gadget manifest is the update site
(site.xml).

[Mark W.]

In 2.0, the schema is up for grabs, so we can add/remove whatever we want

[Matthew Marum]

Andy mentioned life cycle events and application sharing elsewhere and I think we need to think about how those get applied to a Gadget Manifest.

Currently they are specified per gadget, but when sharing the application wouldn't you want to share the Manifest endpoint?  It could also make sense to specify Links for life cycle events within the Manifest as well.  But then you are starting to pull in a lot of gadget logic into the manifest.

[Mark W.]

<devil's advocate>

At it's core, it seems that this proposal is about managing different versions of an app behind a single app URL. How many gadget developers are actually running into this issue? Is the cost of complexity that we'd be introducing to the container outweigh gadget management (some--maybe most--of which you have to do anyway)?

Does the developer still have to maintain multiple versions of their application? Yes.

Does the developer still need to manage those versions? Yes.

Does this add more complexity into the container to figure out and manage the manifest? Yes. 

Question: If the manifest is served up from domain A, and the actual gadget definition is on domain B, did we just introduce cross domain issues?

I agree with Matt that there should be a version number as part of the module prefs or some place similar. Given that there is still more work to be done getting beyond "buddy poke interoperability", that we might want to focus on interop before adding more complexity to the container. Especially around versioning which can be a huge rat hole.

</devil's advocate>

[rbaxter85]

I have to agree with Mark here. I can't think of an elegant solution
here which does not add a ton of complexity, either to the gadget
definition itself, or by adding a separate file. Plus I have to agree
with Mark here, there is not a huge demand for this at the moment.
With that being said I would love to see a way for end users to be
notified new versions of a gadget may be available. However I am not
sure if this is something a container should be doing or something a
"gadget catalog" should be doing instead. Maybe we just need more
time to think about a solution...

[Mark W.]

One thing that's an option is to draft this as an extension and put the implementation in the extras of shindig. This way, it's available for people to try out and can bake in the wild, but we don't have to do it a an official part of 2.0. This is what we'd like to do for the container APIs as well.