svn commit: r1344645 - /incubator/wookie/trunk/features/wave/README

[sc...@apache.org]

Author: scottbw
Date: Thu May 31 10:48:28 2012
New Revision: 1344645

URL: http://svn.apache.org/viewvc?rev=1344645&view=rev
Log:
Added documentation for the Wave API, as the main Wave API page at Google has now been taken down.

Added:
    incubator/wookie/trunk/features/wave/README

Added: incubator/wookie/trunk/features/wave/README
URL: http://svn.apache.org/viewvc/incubator/wookie/trunk/features/wave/README?rev=1344645&view=auto
==============================================================================
--- incubator/wookie/trunk/features/wave/README (added)
+++ incubator/wookie/trunk/features/wave/README Thu May 31 10:48:28 2012
@@ -0,0 +1,80 @@
+# Wave Gadget API Feature
+
+This feature provides widgets with the ability to use a shared context with participants and shared data (state).
+
+The API is based upon the original Google Wave Gadget API, and is largely interoperable with other implementations based on the Wave protocol and related specifications such as Apache Wave.
+
+To use the Wave Gadget API, widgets must be deployed in an environment with a shared context, consisting of a shared data key linking together instances. Also, the plugin or connector should create participants for each user in the shared context.
+
+## The Wave object
+
+Widgets interact with the feature using the `wave` object in the top level browsing context. For example, accessed using `window.wave` or more simply `wave`.
+
+The methods supported for the `wave` object are:
+
+### setStateCallback(callback)	
+
+Uses the passed callback parameter to define a callback function to be run when the gadget's shared state object changes. 
+
+The setStateCallback() callback function is always called once when the state is first received by the widget, and then  subsequently whenever a new state is received by the gadget. 
+
+### setParticipantCallback(callback)	
+Uses the passed callback parameter to define a callback function to be run when there is a change to the participants of  the shared context in which the widget resides. This includes participants getting loaded when the widget first runs, participants joining or leaving the context, or changes to a participant's information, such as a name change. This does not include a participant performing an operation within the context.
+
+### getState()	
+
+Returns the widget's shared state object, which conceptually is a key-value map. Once you have the state object, you can perform operations on it like querying for the value of particular keys. 
+
+### getParticipants()
+
+Returns the participants in the shared context. 
+
+### getViewer()
+
+Returns the current viewer of the widget instance.
+
+### getHost()
+
+Returns the host of the shared context; that is, the user who is designated as the owner or creator of the context in which the widget is placed.
+
+### getHosts()
+
+Returns all participants identified as having the role of host, where multiple hosts are permitted.
+
+## The State Object
+
+### get(key)
+
+Get a single value from the state. For example, `wave.getState().get('count')` returns the value for the count key. Note that both keys and values must be strings.
+
+### submitDelta(delta)	
+
+Updates the state object with delta, which is a map of key-value pairs representing an update. For example, `wave.getState().submitDelta({'count': 5})` sets the value of the count key to '5'. All participants will see the update in the shared state
+
+### submitValue(key, value)
+
+Create or update a single key-value pair in the shared state.
+
+### reset()
+
+Clears all key-value pairs from the shared state.
+
+### toString()
+
+Returns the state information
+
+## The Participant Object
+
+Each participant - including the host and the viewer - has a basic set of user profile information available through the API:
+
+### getDisplayName()
+
+Returns a name to display for the participant.
+
+### getId()
+
+Returns a user id.
+
+### getThumbnailUrl()
+
+Returns a URL for the user's avatar or profile image.