Page Comparison

Reference Implementation Demo Video:    selection_actions_declarative2.swf

OSGS Thread Discussion:   http://groups.google.com/group/opensocial-and-gadgets-spec/browse_thread/thread/a4b4fcf9d3b02bc8/1d2fd87929fda943?lnk=gst&q=Declarative+actions#1d2fd87929fda943

...

Note gadgets must opt in to publish data via selection and should be aware it is a broadcast event.

Selection's distinct value over pub-sub methods of container-gadget and gadget-gadget communication exists in the context of executing gadget provided actions.  When an action is executed the selection service is used to provide the specific container selection to the action.  In a pub-sub model multiple events can be firing simultaneously and since it is not a singleton, the container cannot guarantee the object provided is the same one the action was invoked upon.  Furthermore, when using declarative actions, the gadget receiving the action may not even be loaded/rendered when the action occurs, so it is not possible for it to listen to pub-sub type events.

Compatibility with the Inter-gadget Event Common Namespace Proposal is intended so that the current selection is surfaced as org.opensocial.container.selection.  This compatibility will be implemented by a pub-sub-container.selection feature so that core selection service does not depend on all of pub-sub2 and associated OAHub.  gadgets.selection will only depend on gadgets.rpc for core communication

...

When a user clicks on an action provided by declarative actions, the container renders the gadget if it is not already visible, navigates to the optionally specified view. Note containers have full control over how the gadget is rendered.  As the gadget is rendered, it contributes the JS callback for the action by calling actions.updateAction() with the action:id attribute, providing the javascript callback handler for the action.  When the container receives the actions.updateAction() call it is then able to invoke the provided action via gadget.rpc.  As part of the gadget rendering, the corresponding selection is always available via gadgets.selection.getSelection(); 

...

<Module>
<ModulePrefs title="Sample VOIP">
<Optional feature="actions">
<Param name="action-contributions">
   <action id="org.samplevoip.callbyperson" dataObject="opensocial.Person" 
      label="Call using VOIP Phone" view="DialByPerson" icon="http://ww.samplervoip.org/phone.gif"/>
   <action id="org.samplervoip.navLink" path="container/navigationLinks" label="Phone" />
</Param>

var myaction = {
    id: "org.samplevoip.callbyperson",
    callback: mycallback
}

container.actions.updateAction(myaction);

...

Action contribution to an Open Social Data type  
Containers may choose to render actions bound to data type as either context menus, buttons, etc, where the implementation of the UI is left up entirely to the container. When the action is invoked, the gadgets.selection.getSelection() will return the corresponding data type as defined in [ http://opensocial-resources.googlecode.com/svn/spec/1.1/Social-Data.xml|http://opensocial-resources.googlecode.com/svn/spec/1.1/Social-Data.xml].

1. Gadget contributes an action to container's Person object. Example, a gadget providing SMS capability can bind to a container's list of active contacts/buddy list.
2. Gadget contributes an action to a container's Message. Example, a new button or action is added to the forward, reply, delete list when displaying a message.
3. Same holds true for all Open Social defined data types Group, Activity… etc
4. Gadgets may bind to any container specific types that are defined.  Containers shall make all efforts to use types in shared namespace and to contribute back new types to the spec to maintain cross-container abilities of gadgets.

...

  TODO: get more feedback on common shared action paths multiple containers already want to expose from existing specs

Types

Containers should use the following type attributes when biding actions to OpenSocial Data types: [http://opensocial-resources.googlecode.com/svn/spec/1.1/Social-Data.xml|http://opensocial-resources.googlecode.com/svn/spec/1.1/Social-Data.xml] 

Question: Is this the correct namespace ids as the spec seems to imply but is not explicit

 opensocial.Person
 opensocial.Message
 opensocial.Activity
 opensocial.Group

...

//an array of 2 people who are currently selected
var selection = [ 
{type: "opensocial.person", dataObject: bob}, {type: "opensocial.person", dataObject: joe} ];
gadgets.selection.setSelection(selection);

...

Description: Adds the specified action to the container. May be called from the container or gadget.

var myaction = {

    id: "com.acme.action",
    label: "My Action",    callback: mycallback,
    path: "container/navigationLinks"    
    tooltip: "My Action Tooltip",
    icon: "images/myicon.png",
    iconOffset: {x: "13", y: "15"}, 
    size: {w: "13", h: "15"},
    style: "ICON_AND_LABEL"
}

gadgets.actions.addAction(myaction);

...

* Either path or dataType MUST be specified.

var mycallback = function(){
	//get the person object from the selection
	var sel = container.selection.getSelection();
	if(selection.type == "opensocial.Person"){
        	//call them by email address using my fiction VOIP service
 		var person = selection.dataObject;
		myVOIP.call(person.displayName,person.emails[0]);
	}
};


var myaction = {

    id: "com.acme.mycallaction",
    tooltip: "My Action Tooltip",
    label: "Call Person",
    icon: "images/myicon.png",
    iconOffset: {x: "13", y: "15"},
    style: "ICON_AND_LABEL",
    callback: mycallback,
    dataType: "opensocial.Person"
}

gadgets.actions.addAction(myaction);

...

Description: Updates the specified action in the container with the specified callback function. 

var myaction = {
    id: "com.acme.action",
    callback: myCallbackFunction
}

gadgets.actions.updateAction(myaction);

...

Description: Allows the container to implement its specific UI to draw actions for any dataType or path as specified in the actionObject.  The container registers the handler, and the actions feature calls the handler upon preloading of a gadget when its metadata containing declarative actions is read.

var handler = function(actionObject){
       // draw the UI, toolbars menus, etc using your containers JS library
       // to do the invocation of the action, call the following API:
       // container.actions.runAction(actionObject.id);  
}
container.actions.registerShowActionHandler(handler);

...

Description: Allows the container to implement its specific code for removing actions from the UI.  The container registers the handler, and the actions feature calls the handler upon unloading of a gadget.

var handler = function(actionObject){
       // hide the UI, toolbars menus, etc using your containers JS library
}
container.actions.registerHideActionHandler(handler);

...

Description: Allows the container to implement its specific UI to show a requested gadget as requested by a declarative action.  The container registers the handler, and the actions feature calls the handler upon execution of an action, if the gadget is not yet rendered. The container may re-use the gadget if it is already visible on the page, or may choose to render it in a new or existing gadget view site.  For example some containers could choose to render the gadget for these actions in a floating div area while others do so on a sidebar.

var handler = function(gadgetUrl, opt_params){
    // invoke common container APIs to show the appropriate gadget
    // ie. wrapper around call to CommonContainer.navigateGadget(site, gadgetUrl, viewParams, renderParams, opt_callback);
    // or return the gadgetID of an existing visble gadget navigatingTo the optional viewId.
    return gadgetId;
}
container.actions.registerNavigateGadgetHandler(handler);