Proposal Details

Overview

The goal is to compile requirements and use cases that belong in the formal specification, and to identify authors of the original Common Container code, and developers who are interested in contributing to formalizing the specification. This proposal is the starting point to gather the use cases, and existing documentation around the common container, which while existing in implementation, has little public documentation available.

There was discussion at the Open Social 2.0 kickoff meeting that there was a need for a formal specification around the new Common Container JS code, before new proposals of additional container services could be made as addendums to a formal spec Common-Container.xml

Requirements

The framework lives in the container page and be the user-facing API to container developers. It provides functionalities at the top-most-level giving all abstraction of work needed to make gadget navigation (insertion/deletion) happen and to ensure that navigated gadgets continue to work. The framework insulates containers from releases that require simultaneous changes to the container and changes affecting the gadget render. Additionally, the framework allows container pages to be silently-updated by a new version of Shindig, ie: one release upgrades all containers. The framework should also provide a "common" ground for future container-and-gadget related improvements. The framework does not provide a layout mechanism in which multiple gadgets are draw on the page; this is left to the container developer to do whatever via element containing the gadget iframe.

Use Cases

To provide insert/open and remove/close a gadget into/from a container page, given all customizable parameters.
To provide automatic setup for container-and-gadget interaction , via gadgets.rpc.
To ensure inserted gadgets continue to work, in light of expiring security tokens.
To instantaneously insert a gadget, via pre-loading mechanism.
To facilitate latency timing.

Authors

Evan Gilbert, evangelist, evan@apache.org
Michael Hermanto, lead, mhermanto@apache.org
John Hjelmstad, contributor, johnh@apache.org
Ziv Horest, contributor, zhoresh@apache.org

Motivations, Features

Refer to [this|https://cwiki.apache.org/confluence/display/SHINDIG/Common+Container].

API: shindig.container.Container

This represents the container, including:

the operations that a container can do (opening/closing a gadget, creating a new gadget site, registering RPC services).
internal management of opened gadgets, refreshing security tokens.

Its lifespan starts from time when it is instantiated to time when the page is navigated away. AJAX-y pages will tend to have longer lifespan of common containers.

There is exactly one instance of this in any common-container enabled pages; it makes use of global resources that can result in race-conditions by multiple instances of shindig.container.Container.

This is defined in prototype style to allow extensibility by overrides.

// import shindig.container.* here.
foo.container = shindig.container;
foo.container.Container.prototype.onConstructed = function(config) { ... }
foo.container.Container.prototype.bar = function(...) { ... }

Configuring common container is done at instantiation, by passing a bag-style JSON upon construction. The configurable options are listed and key'ed by shindig.container.ContainerConfig.

shindig.container.Container = function(opt_config) { ... }

The rest of APIs.

// to preload / unload (un-preload) gadgets
container.preloadGadget(...)
container.preloadGadgets(...)
container.unloadGadget(...)
container.unloadGadgets(...)

// to navigate / close gadget sites
container.navigateGadget(...)
container.closeGadget(...)

// to get gadget metatadata
container.getGadgetMetadata(...)

// to register gadgets.rpc service in container
container.rpcRegister(...)

// useful constants
shindig.container.ContainerConfig.*
shindig.container.RenderParam.*
shindig.container.ViewParam.*

API: shindig.container.GadgetSite

This represents the gadget, including:

the HTML element containing the gadget (supplied by callee).
the operations that can be performed on the gadget (adjusting its size, sending RPC call).
the gadget iframe itself.

A instance can have exactly one opened gadget at a time. It can switch to another gadget, by first closing the first one.