Core-Gadget - Action Contributions
This is a DRAFT ...
<!-- ///////////////////////////// -->
<section title="The Action Contributions Feature (gadgets.actions)" anchor="gadgets.actions">
<t>Some container implementations reserve portions of their user
interface for providing links, menus, buttons, etc that are
distinct from the gadgets they host. The "Action Contributions"
feature allows gadgets to contribute functionality to these reserved
areas.</t>
<t>Additionally, gadgets can use the feature to associate actions with
specific types of OpenSocial objects. In traditional desktop applications,
such actions are often rendered as options on context menus when you
click on an object such as a person or file. For instance, selecting
a Person object might display options like "Start a Chat" or
"View Contact Information". With the "Action Contributions" feature,
a gadget can notify the container of which such actions it can provide
so that when a user selects the action, the container can direct the
appropriate gadget to carry it out.</t>
<t>Containers SHOULD support the "Action Contributions" feature.</t>
<t>The "Action Contributions" feature is enabled by specifying the
"actions" feature name with either an <Optional>
or <Require> element within the <ModulePrefs>. The
actions contributed by the gadget are specified using a <Param>
element with the name "action-contributions" within the feature declaration.</t>
<figure><preamble>The following example defines an optional dependency
on the "Action Contributions" feature and contributes a single action
to the set of "Navigation Links" provided by the container. The "path"
property on the <action> element specifies where the action is
being contributed. When the item is selected, the container will
invoke the callback handler provided by the JavaScript in the
<Content> element.</preamble><artwork>
<Module>
<ModulePrefs title="Sample VOIP">
<Optional feature="actions">
<Param name="action-contributions"><![CDATA[
<action id="org.samplervoip.navLink"
path="container/navigationLinks"
label="Phone" />
]]></Param>
</Optional>
</ModulePrefs>
<Content type="html"><![CDATA[
<script>
function navLink(selection) { ... }
gadgets.util.registerOnLoadHandler(
function() {
if (gadgets.actions) {
gadgets.actions.updateAction({
id: "org.samplervoip.navLink",
callback: navLink
});
}
}
);
</script>
]]></Content>
</Module>
</artwork></figure>
<figure><preamble>Contributing actions to specific OpenSocial data
types is similar. Rather than specifying the location to which the
action is to be added, the <action> element specifies the
data type. In either case, a callback function provided by the
gadget is registered and invoked to handle the action:</preamble><artwork>
<Module>
<ModulePrefs title="Sample VOIP">
<Require feature="actions">
<Param name="action-contributions"><![CDATA[
<action id="org.samplevoip.callbyperson"
dataObject="opensocial.Person"
label="Call using VOIP Phone" />
]]></Param>
</Require>
</ModulePrefs>
<Content type="html"><![CDATA[
<script>
function dial(selection) { ... }
gadgets.util.registerOnLoadHandler(
function() {
if (gadgets.actions) {
gadgets.actions.updateAction({
id: "org.samplevoip.callbyperson",
callback: dial
});
}
}
);
</script>
]]></Content>
</Module>
</artwork></figure>
<figure><preamble>Actions can also be contributed programmatically by calling the
<spanx style="verb">gadgets.actions.addAction</spanx> API and passing
in an "action" object. For instance:</preamble><artwork>
var mycallback = function(){
...
};
var myaction = {
id: "com.acme.mycallaction",
tooltip: "My Action Tooltip",
label: "Call Person",
icon: "images/myicon.png",
callback: mycallback,
dataType: "opensocial.Person"
}
gadgets.actions.addAction(myaction);
</artwork></figure>
<figure><preamble>In some simple cases, an action provided by a gadget might simply
be handled by navigating to an IRI. It such cases, a callback function
is not required and the gadget developer can simply provide the IRI
in the action declaration. For instance, in the example below, the
container will display the provided IRI in a new tab when the "Contact US"
navigation action is selected:</preamble><artwork>
<Module>
<ModulePrefs title="Sample VOIP">
<Require feature="actions">
<Param name="action-contributions"><![CDATA[
<action id="org.example.goSomewhere"
path="container/navigationLinks"
label="Contact Us!"
url="http://www.example.org/contact"
viewTarget="TAB" />
]]></Param>
</Require>
</ModulePrefs>
...
</Module>
</artwork>
<t>TODO: What happens is viewTarget is not specified and url is provided??</t>
<t>When registering actions, gadget developers need only provide basic
information about the action such as a unique identifier, text label,
icon and callback function. Containers are responsible for determining
how contributed actions are to be rendered.</t>
<section title="The <action> Element">
<t>The <action> element, as illustrated in the previous
examples, is used within the value of <Param name="action-contributions">
elements to declaratively define the actions provided by a gadget. The
"action-contributions" parameter value can have any number of
<action> elements, each of which MUST specify a unique "id"
attribute. Each actions ID MUST be unique within the scope of the
container -- that is, if multiple gadget's are rendered by
the container, all of the actions contributed by each of the gadgets
MUST specify different IDs.</t>
<t>There is no XML namespace defined for the <action> element.</t>
<figure><artwork>
BaseAction = {
attribute id { text },
attribute label { text },
attribute tooltip { text }?,
attribute icon { IRI }?,
attribute iconSize { text }?,
attribute iconOffset { text }?,
attribute view { text }?,
attribute viewTarget { "TAB" | "DIALOG" | "MODALDIALOG" | "FLOAT" | "SIDEBAR" }?,
attribute url { IRI }?,
undefinedAttribute*
}
PathAction = element action {
BaseAction,
attribute path { text }
}
TypeAction = element action {
BaseAction,
attribute type { text }
}
action = PathAction | TypeAction
</artwork></figure>
<t>The <action> element MUST contain the "id" and "label"
attributes and either the "path" or "type" attributes. The "label"
specifies the plain-text label that a container SHOULD display
when rendering the action. The "path" attribute specifies a
location with the container's user interface where the action
is to be rendered. Possible values for the "path" attribute
are discussed below. The "type" attribute specifies the OpenSocial
data type for which an action is to be associated. The value
MUST be a valid OpenSocial Data Type as specified by
[TODO: New Core Data Reference].</t>
<t>The following additional attributes MAY be specified:
<list style="hanging">
<t hangText="tooltip">Additional text that provides additional
information about the action. Such text is typically displayed
when the user hovers their mouse cursor over the action item.</t>
<t hangText="icon">An IRI to an image resource that the container
can display when rendering the action item. For instance, when
rendering the action as a menu item, the contain can display the
icon next to the label. If a relative path is provided, it MUST
be resolved relative to the URL of the gadget specification document.</t>
<t hangText="iconSize">TODO: Need more info</t>
<t hangText="iconOffset">TODO: Need more info</t>
<t hangText="view">The name of the gadget view the container
SHOULD render when the action is invoked.</t>
<t hangText="viewTarget">Specifies where the specified view is
to be rendered. Different container implementations MAY support
the ability for individual gadget views to be displayed outside
the main area allocated to the gadget by the container. Examples
include rendering within a modal dialog box, or within a
"sidebar" area provided by the container. Acceptable values for
the viewTarget attribute are "TAB", "DIALOG", "MODALDIALOG",
"FLOAT" and "SIDEBAR". If not specified, the view will be rendered
within the area already allocated to the gadget.</t>
<t hangText="url">An IRI to use in place of a callback function.
When used, the container will display the content of the URL
when the action is selected rather than invoking a JavaScript
callback to handle the action. TODO: Need more info</t>
</list>
</t>
</section>
<section title="Action Contribution Paths" anchor="gadgets.actions.paths">
<t>When a gadget contributes actions to the container's user interface,
the intended location where the action is to be rendered is specified
using a "path". The collection of available paths for which actions
can be contributed is specific to each individual container implementation.
Some containers might not support user interface action contributions
at all.</t>
<t>The following common paths MAY be supported by a container:
<list style="hanging">
<t hangText=""container/navigationLinks"">
Identifies the area provided by the container for
"top-level navigation". These are typically links
or menu items that provide users with an overall
ability to navigate through the various available
services provided by an application.
</t>
<t hangText=""container/menus>">
Identifies the area provided by the container for
menu options. These are typically hierarchically
nested actions that provide access to a variety
of options and tools currently available to the user.
</t>
<t hangText=""container/toolbars"">
Identifies the area provided by the container for
toolbars. These are typically shortcuts to commonly
used options or tools currently available to the user.
</t>
<t hangText=""gadget/menu"">
Identifies an "options" menu that a container might
provide for a gadget instance. Typically, such menus
provide options and tools associated with a specific
gadget instance.
</t>
</list>
</t>
<t>Contribution paths are hierarchical and container specific. For
instance, if a container supports a top level menu system such
as those typically found in many traditional desktop applications,
a gadget might use path="container/menu/File" to add items to the
containers "File" menu. The depth of the path hierarchy is entirely
determined by the container. Each segment of the path is separated
by the forward slash (/) character.</t>
</section>
<section title="JavaScript API">
<t>Gadget developers who contribute actions to the container use the
<spanx style="verb">gadgets.actions</spanx> JavaScript API to work
with contributed actions.</t>
<t>The API is used, for instance, to register callback functions to
handle actions, register or modify actions programmatically, or
work with contributions provided by other gadget specifications.</t>
<section title="The Action Object" anchor="gadgets.actions.actionobjects">
<t>The <spanx style="verb">Action</spanx> object is a JavaScript
representation of a contribution action. The properties available
on the object correlate to each of the attributes on the <action>
element. An additional "callback" property is provided that specifies
the callback function the container will invoke when the action is
selected.</t>
<texttable align="left">
<ttcol>Attribute</ttcol>
<ttcol>Description</ttcol>
<c>id</c>
<c>Unique identifier</c>
<c>label</c>
<c>Text string to display for this action</c>
<c>path</c>
<c>The container-defined location for this action, as described in <eref target="#gadgets.actions.paths">Action Paths</eref>. Example: path=container/menus/Edit</c>
<c>dataType</c>
<c>The Open Social Data type with which to associate this action. Example: opensocial.Person</c>
<c>tooltip</c>
<c>Tooltip to display on hovering over an icon</c>
<c>icon</c>
<c>Path to image icon. Absolute URL or URL relative to gadget URL</c>
<c>iconSize</c>
<c>TODO: need more info</c>
<c>iconOffset</c>
<c>TODO: need more info</c>
<c>view</c>
<c>The view ID the gadget should navigate to when the action is invoked.</c>
<c>viewTarget</c>
<c>The target area to render the view.</c>
<c>url</c>
<c>Simple actions that are just links can specify a url instead of a callback function.</c>
</texttable>
<t>As is the case with the <action> element, the "id" and "label"
properties are both required and values for either the "path" or "type"
MUST be provided. All other properties are optional.</t>
</section>
<section title="gadgets.actions.addAction" anchor="gadgets.actions.addAction">
<t>Programmatically registers an action with the container.</t>
<figure><artwork>
<static> gadgets.actions.addAction(action)
</artwork></figure>
<t>Input Parameters:
<texttable align="left">
<ttcol>Name</ttcol>
<ttcol>Type</ttcol>
<ttcol>Description</ttcol>
<c>action</c>
<c><xref target="gadgets.actions.actionobjects">Action Object</xref></c>
<c>The action to be added to the container</c>
</texttable>
</t>
<figure><preamble>For example:</preamble><artwork type="code">
var mycallback = function(){
...
};
var myaction = {
id: "com.acme.mycallaction",
tooltip: "My Action Tooltip",
label: "Call Person",
icon: "images/myicon.png",
callback: mycallback,
dataType: "opensocial.Person"
}
gadgets.actions.addAction(myaction);
</artwork></figure>
</section>
<section title="gadgets.actions.updateAction" anchor="gadgets.actions.updateAction">
<t>Modifies the specified action contributed to the container.
TODO: Question: any action or just actions provided by this one gadget?</t>
<figure><artwork>
<static> gadgets.actions.updateAction(action)
</artwork></figure>
<t>Input Parameters:
<texttable align="left">
<ttcol>Name</ttcol>
<ttcol>Type</ttcol>
<ttcol>Description</ttcol>
<c>action</c>
<c><xref target="gadgets.actions.actionobjects">Action Object</xref></c>
<c>A partial representation of the action to be updated within the container</c>
</texttable>
</t>
<t>The Action object passed in to the <spanx style="verb">gadgets.actions.updateAction</spanx>
method can be a partial representation of the action that contains
the "id" of the action being modified and only the properties that
need to be updated.</t>
<figure><preamble>For instance, to specify the callback function
for an action contributed using the <action> element, a developer
would invoke <spanx style="verb">gadgets.actions.updateAction</spanx>
with an object that specifies only the "id" and "callback" properties:</preamble>
<artwork>
var mycallback = function(){
...
};
var myaction = {
id: "com.acme.mycallaction",
callback: mycallback
}
gadgets.actions.updateAction(myaction);
</artwork></figure>
</section>
<section title="gadgets.actions.removeAction" anchor="gadgets.actions.removeAction">
<t>Removes the specified action from the container.
TODO: I assume a gadget can only remove it's own actions
</t>
<figure><artwork>
<static> gadgets.actions.removeAction
</artwork></figure>
<t>Input Parameters:
<texttable align="left">
<ttcol>Name</ttcol>
<ttcol>Type</ttcol>
<ttcol>Description</ttcol>
<c>id</c>
<c>String</c>
<c>The ID of the action to be removed.</c>
</texttable>
</t>
<figure><preable>For example,</preable><artwork>
gadgets.actions.removeAction("com.acme.mycallaction");
</artwork></figure>
</section>
<section title="gadgets.actions.getActionsByPath" anchor="gadgets.actions.getActionsByPath">
<t>Retrieves the collection of actions registered at the specified
path and passes the result to the provided callback function as
a JavaScript Array. TODO: is this all actions for the container,
or just this gadgets?? TODO: is this hierarchical</t>
<figure><artwork>
<static> gadgets.actions.getActionsByPath(path, callback)
</artwork></figure>
<t>Input Parameters:
<texttable align="left">
<ttcol>Name</ttcol>
<ttcol>Type</ttcol>
<ttcol>Description</ttcol>
<c>path</c>
<c>String</c>
<c>The String representation of the path to the actions</c>
<c>callback</c>
<c>Function</c>
<c>A callback function to handle the returned actions array</c>
</texttable>
</t>
<figure><preamble>For example,</preamble><artwork>
function listActions(actions) { ... }
gadgets.actions.getActionsByPath("container/navigationLinks", callback);
</artwork></figure>
</section>
<section title="gadgets.actions.getActionsByDataType" anchor="gadgets.actions.getActionsByDataType">
<t>Retrieves the collection of actions registered for the specified
data type and passes the result to the provided callback function
a JavaScript Array. TODO: is this all actions for the container or
just this gadgets??</t>
<figure><artwork>
<static> gadgets.actions.getActionsByDataType(dataType, callback)
</artwork></figure>
<t>Input Parameters:
<texttable align="left">
<ttcol>Name</ttcol>
<ttcol>Type</ttcol>
<ttcol>Description</ttcol>
<c>dataType</c>
<c>String</c>
<c>The String representation of the associated data type</c>
<c>callback</c>
<c>Function</c>
<c>A callback function to handle the returned actions array</c>
</texttable>
</t>
<figure><preamble>For example,</preamble><artwork>
function listActions(actions) { ... }
gadgets.actions.getActionsByType("opensocial.Person", callback);
</artwork></figure>
</section>
<section title="gadgets.actions.runAction" anchor="gadgets.actions.runAction">
<t>Invokes the specified actions callback function; or, if the
"url" property is specified in place of a callback, causes the
container to navigate to the specified IRI. Gadget's can use
this method to programmatically invoke an action.</t>
<figure><artwork>
<static> gadgets.actions.runAction (id, opt_selection)
</artwork></figure>
<t>Input Parameters:
<texttable align="left">
<ttcol>Name</ttcol>
<ttcol>Type</ttcol>
<ttcol>Description</ttcol>
<c>id</c>
<c>String</c>
<c>The ID of the action to execute.</c>
<c>opt_selection</c>
<c><xref target="gadgets.selection">Selection Object</xref></c>
<c>An optional object that identifies the currently selected object as
defined by <xref target="gadgets.selection"/>.</c>
</texttable>
</t>
<figure><preamble>For example,</preamble><artwork>
gadgets.actions.runAction("com.acme.mycallaction");
</artwork></figure>
</section>
<section title="gadgets.actions.registerShowActionsListener" anchor="gadgets.actions.registerShowActionsListener">
<t>Registers a callback function that the container will call whenever
new actions are added to the container. A gadget can use this listener
to provide a rendering of any action contributed to the container
by any other gadget.</t>
<figure><artwork>
<static> gadgets.actions.registerShowActionsListener (listener)
</artwork></figure>
<t>Input Parameters:
<texttable align="left">
<ttcol>Name</ttcol>
<ttcol>Type</ttcol>
<ttcol>Description</ttcol>
<c>listener</c>
<c>Function</c>
<c>The gadgets's function to render actions in its UI. The
function will be invoked with one parameter which is an array
of action objects to render.</c>
</texttable>
</t>
<figure><preamble>For Example:</preamble><artwork type="code">
var listener = function(actionObjs){
// draw the UI, toolbars menus, etc
// to do the invocation of the action, call the following API:
// gadgets.actions.runAction(actionObjs[0].id);
}
gadgets.actions.registerShowActionsListener(listener);
</artwork></figure>
</section>
<section title="gadgets.actions.registerHideActionsListener" anchor="gadgets.actions.registerHideActionsListener">
<t>Registers a callback function that the container will call whenever
the a gadget that contributes actions is removed from the container.</t>
<figure><artwork>
<static> gadgets.actions.registerHideActionsListener (listener)
</artwork></figure>
<t>Input Parameters:
<texttable align="left">
<ttcol>Name</ttcol>
<ttcol>Type</ttcol>
<ttcol>Description</ttcol>
<c>listener</c>
<c>Function</c>
<c>The gadgets's function to render actions in its UI. The
function will be invoked with one parameter which is an array
of action objects to hide.</c>
</texttable>
</t>
<figure><preamble>For Example:</preamble><artwork type="code">
var listener = function(actionObjs){
// remove the UI elements associated with the listed actions
}
gadgets.actions.registerHideActionsListener(listener);
</artwork></figure>
</section>
</section>
</section> <!-- END CONTRIBUTED ACTIONS FEATURE -->