Gadget Manifest File

Discussion thread: http://groups.google.com/group/opensocial-and-gadgets-spec/browse_thread/thread/299c75c1c2534c65

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 may be handled by a single manifest file that identifies to the container which gadget XML file to utilize based on supported features or by allowing gadgets to embed pointers to up-version or down-version implementations of themselves.

Objective

This proposal should satisfy the need for multiple gadget versions being deployed across multiple containers while allowing for backwards compatibility of existing gadgets already deployed in production.

Use Cases

Note: There is some overlap between the manifest and view-level features proposal. This manifest proposal allows for more dramatic version differences of the same gadget to be deployed in a way that is backwards compatible. View-level features will only be forwards compatible. The two proposals should be able to coexist without causing interference.

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.

Specifics:

The manifest feature may be supported either through embedded manifest information in the gadget or through an external manifest XML file. In both scenarios this will be supported through a new gadget-manifest feature available in the ModulePrefs section.

Embedded Manifest

Manifest information MAY be embedded within a gadget XML file

Embedded Manifest Example

<Module>
  <ModulePrefs title="Manifest embedded gadget" description="Example showing usage of embedded manifest">
    <Require feature="opensocial-1.0"/>
    <Optional feature="gadget-manifest">
       <Param name="gadget" os-version="1.0" gadget-version="2.1" status="released">http://example.org/samplegadget/gadget.xml</Param>
       <Param name="gadget" os-version="1.0" gadget-version="2.2" status="development">http://example.org/samplegadget/gadget-dev.xml</Param>
       <Param name="gadget" os-version="0.8" >http://example.org/samplegadget/gadget.os08.xml</Param>
    </Optional>
  </ModulePrefs>
  ...
<Module>

In cases where there are relatively few gadget files to link, this may be the most efficient option. The downside of this option is that the cross-pointers must be kept synchronized between all gadget files.

External Manifest

Scenarios where many gadget source files are associated together or a wide variety of versions and containers are supported are better served by having a single external manifest file.

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.

Manifest Example

<Module>
  <ModulePrefs title="Manifest sample gadget" description="Example showing usage of external 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.