clearspring - the widget network.

Platform Services Developers About Us Sign In Create Account

Platform

You are here: Docs → Technical Documentation → Clearspring APIs → In-Widget API → Menu
 

Menu

Sharing UI

menu enables the invocation and configuration of our Flash-based service menu at run-time. This means you don't have to use our "get & share" button if you don't want to--instead, you can use your own custom button for launching our services.

 

API Reference

Name Type Description
menu.addEventListener method Subscribes listener to menu event broadcasts.
menu.event.OPEN string Constant code for menu 'open' event. Broadcast when menu.show is invoked.
menu.event.CLOSE string Constant code for menu 'close' event. Broadcast when menu.hide is invoked.
menu.event.SHARE string Constant code for menu 'share' event. Broadcast when user completes a share, with metadata indicating which destination was used.
menu.configure method Reconfigures your parameters in the service menu. (Only relevant for configurable widgets.) Useful when you want to change an internal parameter before a share occurs.
menu.hide method Hide our service menu
menu.load method Loads our service menu into an arbitrary HTML element (only needed for JavaScript)
menu.setContent method Sets the content to be shared (kernel only).
menu.setOptions method Updates the service menu's settings (e.g., what widget to share, what homepage to use for emailing, etc.)
menu.show method Display our service menu

menu.addEventListener

method

Adds listener to menu events. Three events are broadcast: menu.event.OPEN, menu.event.CLOSE, and menu.event.SHARE.

Parameters
Name Type Required Purpose
Event String yes Indicates which event code to listen for. One of menu.event.OPEN, menu.event.CLOSE, or menu.event.SHARE.
Callback Function yes Method called on event broadcast. For convenience, the event is passed as its only argument. In AS2, the event is either a string (for historical reasons, the OPEN> and CLOSE> events are passed as strings; this will be rectified in an upcoming release) or a plain object, with its code stored as the member '''type'''. In AS3, the event is a standard Flash event.
Return
None
Example Usage

AS2

// Adds listeners to menu open and close events.

var OPEN:String = _level0.cs.menu.event.OPEN;
var CLOSE:String = _level0.cs.menu.event.CLOSE;
var SHARE:String = _level0.cs.menu.event.SHARE;

// For historical reasons, the OPEN and CLOSE events in AS2 are actually strings.
function openCloseHandler(event:Object):Void
{
	switch (event)
	{
		case OPEN:
			trace('Menu opened!');
			break;
		case CLOSE:
			trace('Menu closed.');
			break;
		default:
			trace('Unknown menu event: ' + event);
			break;
	}
}

function shareEventHandler(event:Object):Void
{
	// Sharing destination stored in event.destination. For a list of destination 
	// codes, see http://www.clearspring.com/docs/tech/apis/in-widget/share 
	trace('User shared to ' + event.destination);
	break;
}

_level0.cs.menu.addEventListener(OPEN, openCloseHandler);
_level0.cs.menu.addEventListener(CLOSE, openCloseHandler);
_level0.cs.menu.addEventListener(SHARE, shareEventHandler);

AS3

import flash.events.*;

// Adds listeners to menu open and close events.

var OPEN:String = _api.menu.event.OPEN;
var CLOSE:String = _api.menu.event.CLOSE;
var SHARE:String = _api.menu.event.SHARE;

function menuEventHandler(event:Object):void
{
	switch (event.type)
	{
		case OPEN:
			trace('Menu opened!');
			break;
		case CLOSE:
			trace('Menu closed.');
			break;
		case SHARE:
			// Sharing destination stored in event.destination. For a list of destination 
			// codes, see http://www.clearspring.com/docs/tech/apis/in-widget/share 
			trace('User shared to ' + event.destination);
			break;
	}
}
_api.menu.addEventListener(OPEN, menuEventHandler);
_api.menu.addEventListener(CLOSE, menuEventHandler);
_api.menu.addEventListener(SHARE, menuEventHandler);

JavaScript

Not available.
back to table

menu.configure

method

Updates configuration pushed by menu. If you wanted to generate placements with a configuration different than the current placement, you'd call menu.configure() to do so. For example, let's say you have a widget that draws a colored rectangle. You use a configuration parameter color to determine the hex value of the rectangle. The default, arbitrarily, is yellow. By calling menu.configure({color: 0xff0000}) before displaying the menu, all placements generated by our share menu during this session will be red.

All configuration parameters must have been registered ahead of time in our console.

Parameters
Name Type Required Purpose
Configuration Object yes Maps parameter names to new values; e.g., if 'foo' and 'bar' are parameters, you might pass {foo: 'newfoo'} to update foo. bar will remain unchanged.
Return
None
Example Usage

AS2

// Sets 'color' to red; sets 'number' to 6.
// As long as this is called before a share takes place (ideally before
// the service menu is shown at all), any new placements generated by 
// the service menu will have this new configuration.
_level0.cs.menu.configure({color: 0xff0000, number: 6});

AS3

// Sets 'color' to red; sets 'number' to 6.
// As long as this is called before a share takes place (ideally before
// the service menu is shown at all), any new placements generated by 
// the service menu will have this new configuration.
_api.menu.configure({color: 0xff0000, number: 6});

JavaScript

// Note: Not available in JS container. // Menu must be loaded before configure can be called. _api.menu.configure({color: 0xff0000});
back to table

menu.event.OPEN

string

Constant code for menu 'open' event. Broadcast when menu.show is invoked. Only meaningful in conjunction with menu.addEventListener.

Example Usage

See menu.addEventListener.

back to table

menu.event.CLOSE

string

Constant code for menu 'close' event. Broadcast when menu.hide is invoked. Only meaningful in conjunction with menu.addEventListener.

Example Usage

See menu.addEventListener.

back to table

menu.load

method

Loads our service menu into the given HTML element. Only available in JavaScript. In the future we hope to directly support attaching the menu to MovieClips or Sprites that you specify. We truly apologize for the inconvenience, and hope that it at least makes you a stronger person.

Parameters
Name Type Required Purpose
where HTML element yes Loads the menu in the specified element (generally a <div>).
Return
None
Example Usage

JavaScript

<div id="menu"></div>
<script type="text/javascript">
// Kernel load callback
function onLibLoad(lib)
{
	lib.menu.load(document.getElementById('menu'));
}
</script>

AS2

Only applicable in JavaScript.

AS3

Only applicable in JavaScript.
back to table

menu.show

method

Shows our service menu. You may optionally specify a service to pre-open, and an x/y location.

Parameters
Name Type Required Purpose
service string no Opens the menu to the specified service. Pass null to ignore this parameter. Sharing services:
  • blogger
  • email
  • eons
  • facebook
  • freewebs
  • friendster
  • google
  • live
  • myspace
  • netvibes
  • pageflakes
  • tag
  • typepad
  • webwag
  • xanga

Other:

  • about - about this widget (normally accessible through the about option in the * menu)
  • edit - placement configuration management (normally accessible through the settings option in the * menu)
xy object {x: integer, y: integer} no Shows the menu at the given x, y coordinate pair. By default it appears centered on the widget.
Return
None
Example Usage

AS2

// opens menu with 'email' service started at (25, 25).
_level0.cs.menu.show("email", {x: 25, y: 25});

AS3

// opens menu with 'email' service started at (25, 25).
_api.menu.show("email", {x: 25, y: 25});

JavaScript

Only applicable in Flash kernels, since menu.load() directly loads the menu for your positioning.
back to table

menu.hide

method

Hides our service menu, if it's shown.

Parameters
None
Return
None
Example Usage
_level0.cs.menu.hide();
back to table

menu.setContent

method

Sets the content to be shared. (Kernel only.) Normally, we use your content template (stored in your widget record) to determine what to share when using the menu from any of our kernels. (You likely would have set this using our widget console, or programmatically using widget.update.) If you want to use our sharing menu to push arbitrary content, use setContent() to determine what to share.

Parameters
Name Type Required Purpose
content string yes Sets the content to be shared on all subsequent shares using the menu during this session. Can be called multiple times per session.
unique boolean yes If true, content will be only stored at the placement level -- in other words, future invocations of the share menu, in subsequent sessions, will share the original content. Useful for one-time shares. If false, userId is required to authenticate you.
userId string no Your Clearspring user ID; available when logged in under Settings tab. We strongly encourage you not to include your user ID in any production application, as it can be used to update any of your widgets.
Return
None
Example Usage

AS2

// All sharing via our menu from now on will post "interesting content"
_level0.cs.menu.setContent("interesting content", true);
_level0.cs.menu.show();

// ...later on, we'll post different content
_level0.cs.menu.setContent("even more interesting content", true);
_level0.cs.menu.show();

AS3

// All sharing via our menu from now on will post "interesting content"
_api.menu.setContent("interesting content", true);
_api.menu.show();

// ...later on, we'll post different content
_api.menu.setContent("even more interesting content", true);
_api.menu.show();

JavaScript

// Note: Not available in JS container // All sharing via our menu from now on will post "interesting content" _api.menu.setContent("interesting content", true); _api.menu.show(); // ...later on, we'll post different content _api.menu.setContent("even more interesting content", true); _api.menu.show();
back to table

menu.setOptions

method

Updates the service menu's settings (e.g., what widget to share, what homepage to use for emailing, etc.)

Parameters
Name Type Required Purpose
options object yes Sets any of the following options:
  • customHomepage (url): your own widget homepage; if not provided, we'll use our boilerplate http://www.clearspring.com/widget/widgetId link
  • useFacebookLink (boolean): if true, we'll share a link to your widget homepage instead of attempting to place your widget in our Facebook widget container application
  • placementId (string): the placement ID to use for the parent placement of the next placement; must be a valid ID in our system
  • widgetId (string): the widget ID to share
Return
None
Example Usage

AS2

// All sharing via our menu from now on will post singing horses
// and use example.org for the widget homepage
_level0.cs.menu.setOptions({widgetId: "472b633e7225b6e3",
			    customHomepage: "http://www.example.org"});
_level0.cs.menu.show();

AS3

// All sharing via our menu from now on will post singing horses
// and use example.org for the widget homepage
_api.menu.setOptions({widgetId: "472b633e7225b6e3",
		      customHomepage: "http://www.example.org"});
_api.menu.show();

JavaScript

// Note: Not available in JS container // All sharing via our menu from now on will post singing horses // and use example.org for the widget homepage _api.menu.setOptions({widgetId: "472b633e7225b6e3", customHomepage: "http://www.example.org"});
back to table

menu.event.OPEN

string

Event broadcast when the Clearspring sharing menu is opened, either by the user or programmatically.

back to table

menu.event.CLOSE

string

Event broadcast when the Clearspring sharing menu is closed, either by the user or programmatically.

back to table

menu.event.SHARE

string

Event broadcast when the user completes a share using the Clearspring menu. Note that for URL-exchange services (e.g., iGoogle), this event is broadcast when the user receives the URL back to the destination. Since the user may copy and paste this URL into their browser at their leisure, we can't always know during the user session that the share actually completed. Therefore, for consistency, we broadcast SHARE when all our work is done. We encourage you to use the sharing menu to understand this distinction. For both AS2 and AS3, the name of the service shared to is stored in the event object's destination field.

back to table

Overview
Docs
Forum