clearspring - the widget network.

Platform Services Developers About Us Sign In Create Account

Platform

You are here: Docs → Technical Documentation → Clearspring APIs → On-Page API
 

On-Page API

Launchpad On-Page is a standalone viral sharing menu that you can place anywhere on your site. It allows users to post, email or bookmark your widget to their destination of choice with a simple and intuitive interface. They can also grab your embed code, too!

You include the menu using some simple Javascript code. You can share any arbitrary piece of content you want, or you share widgets that are registered with the Clearspring platform. This guide provides detailed information on the Javascript API, and all of the different options for customizing the UI. If you're looking for basic info on what Launchpad On-Page is and where to get pre-built code, check out the following topics:

Table of Contents

Menus and buttons

The Launchpad tools come in two different visual flavors: a full menu, or a button that pops up a menu. The menu looks like this:

The button is a good choice when you want to take up just a small amount of space on your page -- it is as functional as the full menu, it just doesn't display until the user clicks it. It looks like this (go ahead, click on it!):

Including the API

Include the Launchpad API in your page with the following code: 
<script src="http://widgets.clearspring.com/launchpad/include.js" type="text/javascript"></script>

You must include this code before you make a call to any Launchpad Javascript functions. It only needs to go in the page once, and it does not need to be in the HTML head.

Note: In order for Launchpd to properly position itself on your page, you should make sure you are setting a DOCTYPE for your page. This is a best practice, though not always required in general. The DOCTYPE declaration at the top of your page might look like the following, for XHTML:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 
<html xmlns="http://www.w3.org/1999/xhtml"> 

Launchpad Javascript functions

The primary Launchpad Javascript functions are:

Name Description Return Value Example Usage
$Launchpad.ShowButton Displays the Launchpad button Menu object $Launchpad.ShowButton(options);
$Launchpad.ShowMenu Displays the Launchpad menu Menu object $Launchpad.ShowMenu(options);
$Launchpad.CreateMenu Creates the menu, but does not display it; for use with custom buttons Menu object <a href="" id="customBtnId"> Custom button </a>
$Launchpad.CreateMenu({actionElement : "customBtnId", ...});
The use of these functions is described throughout this document.

Calling the functions: dynamic and pre-registered widgets

To call any of the three primary Javascript functions, you pass a single argument: a Javascript object with certain required and optional names and values (JSON format). There are two basic ways to call the functions, and a set of options that are common to both:

  • you specify the ID of a widget (referred to as a WID) that has already been registered with the Clearspring platform
  • you specify a textarea, div, span, etc. that includes some arbitrary content you want to share dynamically, and a name for your new widget; the widget will be registered for you automatically

Creating menus to share widgets dynamically

You can create a widget on-the-fly by specifying an arbitrary blob of content and passing it to the functions. You do this by identifying a HTML element, like a textarea, that contains your blob and passing the ID of this element (or a pointer to the element if you really want), into the function via the source option. When doing this, you also need to specify your user ID (via userId) and a name for the widget (via widgetName). Your call would look like this:

<textarea id="myCode" >	
<b>This</b> is the code I want to share!
</textarea>	
<script type="text/javascript">
 $Launchpad.ShowMenu({ userId : "MY_ID", widgetName : "Cool Widget", source : "myCode" });
 </script> 

You can get your user ID (as well as the rest of this code pre-built for you), by visiting clearspring.com/services/launchpad/on-page.

Note: if you have a Flash blob it may not appear on some destinations.  This is due to your domain not being whitelisted by the service.  Please contact the service to be added to their whitelist.

All of the options relevant to these dynamically-registered widgets are listed in the following table:

Name Type Description
userId String, required The ID of the user creating the menu (you)
widgetName String, required The name of the widget as it will be seen in the Widget Console (spaces allowed)
source String ID or DOM element pointer, required The DOM element (by ID or reference) that contains the content you want to share
sources JSON object, optional A set of sourcename/source pairs ({facebook : "myFacebookDiv", myspace : "myMyspaceDiv"}); see this topic for more info
widgetWidth Integer, optional (400 by default) The width of your widget, if its constant; this helps some destinations display your content better
widgetHeight Integer, optional (300 by default) The height of your widget, if its constant; this helps some destinations display your content better
unique Boolean, optional (false by default) For widgets that change each time the page is viewed (and this call is made), set this to true to preserve old instances already shared
excludeTracking Boolean, optional (default is false) This flag disables tracking functionality for this widget being shared from this menu. Use this if your widget is also using the Launchpad In-Widget Advanced library (the Kernel) to prevent double counting in Analytics. no

A Note on dynamic content: Remember that whatever the state of your content is in the DOM at the time you share will be the content that is posted to the server. In other words, if you are including Javascript that self-modifies the content of your page, and that executes before the user shares, then the modified content will be what is actually shared. It will NOT be the original content in your page source.

Creating menus to share pre-registered widgets

You need to pass the ID of your registered widget in a wid value, like this:

var options = {};
options.wid = "465db8f226724744";
$Launchpad.ShowMenu(options);
...or just something like this: 
$Launchpad.ShowMenu({wid: "465db8f226724744"});

Note that you can get a call like this pre-built for you for a particular widget, by going to the Share It -> Launchpad tool in the Widget Console.

All of the options relevant to pre-registered widgets are listed in the following table:

Name Type Description
wid String, required The ID of the registered widget to share
config JSON, optional A set of configuration parameters, if you are using the Clearspring parameters system

Shared options

The following table lists options that are common to both kinds of calls:

Name Type Description Required?
servicesInclude array of strings Array of services to include in the menu.
Do not use with serviceExclude (see this example)		 no
servicesExclude array of strings Array of services to Exclude from the menu.
Do not use with serviceInclude (see this example)		 no
customCSS URL An absolute URL to a custom stylesheet to re-style the menu; MUST be valid.
no
actionElement string or page element reference For CreateMenu or ShowMenu, this parameter identifies an item on the page; the menu will be positioned relative to this element. This parameter can be a string ID of the element, such as "myItemId", or an actual Javascript element reference, even this. no
targetElement string or page element reference This parameter identifies a div on the page; the menu will be displayed inside this div. This parameter can be a string ID of the element, such as "myItemId", or an actual Javascript element reference, even this. no
menuHeight number The menu has default dimensions; if you want a different height, specify a number between 140 and 900 here. (see this example) no
menuWidth number The menu has default dimensions; if you want a different width, specify a number between 140 and 900 here. (see this example) no
bookmarkUrl valid URL (http://...) If you'd like the Bookmark services to post to a different page than your widget's Clearspring home page, specify that URL here.
no
useFacebookLink Boolean, optional (default is false) If you'd like to set the seed link on Facebook to be something other then the defined Clearspring link, set this value to true and set the value of bookmarkUrl.  If bookmarkUrl is not set then the seed link will be set to the Clearspring widget home page.
no
menuConfig JSON Object, optional
 A set of menu configuration parameters. Currently there is a single configuration option available, embed. The embed option is Boolean with a default value of false. When true the embed code for the widget will be display on the menu and NOT as a tab. (see this example) no

Available Service Identifiers

The set of possible service identifiers, for use in the various Launchpad On-Page Javascript calls, is:

Service Type Service Identifiers
post 'myspace', 'facebook', 'myyearbook', 'google', 'live', 'spaces', 'netvibes', 'freewebs', 'xanga', 'friendster', 'tagged', 'blackplanet', 'blogger', 'typepad', 'livejournal', 'multiply', 'eons', 'pageflakes', 'webwag', 'hi5', 'vox', 'orkut', 'typepadsidebar', 'bloggersidebar'
send 'email', 'emailtoself', 'mobile'
bookmark 'browserbookmark', 'digg', 'delicious', 'blinklist', 'furl', 'technorati', 'reddit', 'stumbleupon', 'yahoobookmark', 'yahoobookmarks', 'livefavorites', 'askmystuff', 'propeller', 'aolbookmarks', 'newsvine', 'googlebookmarks', 'twitter', 'simpy', 'blogmarks', 'spurl', 'linkagogo', 'backflip', 'diigo', 'faves', 'segnalo', 'netvouz', 'dropjack'
embed 'jscode', 'objectcode'
desktop 'dashboard', 'vista', 'yahoowidgets'

Note that if you use the service type name, like 'post', rather than an individual service, you can enable or disable whole tabs of services at once.

Menu object methods

Each of the primary Javascript functions actually returns a Menu object. There are a few different methods on this object, to give you even greater control over how the menu behaves:

Name Description Example usage
show() Shows the menu var x = $Launchpad.CreateMenu(config); x.show();
hide() Hides the menu var x = $Launchpad.CreateMenu(config); x.hide();
toggle() Hides or shows the menu, depending on current state var x = $Launchpad.CreateMenu(config); x.toggle();

Note: If using these methods, the best practice is to also specify the targetElement menu option so that the menu has a DOM element to use to position itself.

Basic usage examples

The following sections provide some general example calls.  Also check out the Guides section for additional documentation on using and configuring Launchpad On-Page.

Specifying configuration for registered widgets

If you have a registered widget that uses the Clearspring configuration system, you can use the config option to tell Launchpad to share a specific configuration of the widget. Specify arguments like this: 
 config : { "feed" : "http://www.example.com/rss.xml", "title" : "Latest updates" }

This will set a parameter feed to a specific URL, and a parameter title to a specific string. Your overall function call then would look something like this:

<script type="text/javascript">
 $Launchpad.ShowMenu({ wid : "widgetId", config : { "myfile" : "foo.mpg" }});
 </script>

Note that you cannot use this argument when sharing an dynamically-registered widget; these are not managed by the platform (other than for analytics data), and therefore don't use the configuration system.

Controlling available services

You can configure the menu to enable or disable certain viral services. For example, to enable MySpace, Facebook, and Email sharing, make the call like this:

 servicesInclude : [ 'myspace', 'facebook', 'email' ]

To exclude certain viral services use code like this:

 servicesExclude : [ 'myspace', 'facebook', 'email' ]

The full list of service identifiers is here.

Note that if you disable certain services, the Post, Bookmark, Email, etc tabs at the top of the menu will disable automatically. Further, if you select only one service, the menu will automatically go right to that service's interface, without requiring a use to press a button. For example, specifying only MySpace, the menu would look like this:

This can be useful for creating buttons for individual services, if you'd like.

For more information on configuring services check out the "Configuring the serivces on Launchpad On-Page" guide.

Specifying different content for different services

Not all destinations can accept the same code -- some sites do not allow Javascript, for example, while others do. When creating widgets on the fly, you can pass multiple different service-specific chunks of content in the sources parameter. These pieces of content will be used for the service they reference, and the standard source parameter will be used for the rest. For example:

<script type="text/javascript">

var config = {
	userId : "MY_ID",
	widgetName : "Cool Widget",
	source : "dfltSource",
	sources : {facebook : "myFacebookSource", myspace : "myMySpaceSource"}
    };
 $Launchpad.ShowMenu( config );
 </script>

Coupled with using servicesInclude and servicesExclude, you should be able to easily ensure that your code is completely portable across the web. Lastly, this list may also help you determine which types of code are supported on which destinations.

Including your widget and the Launchpad On-Page menu on the same page

For registered widgets, as you know, Clearspring can add a Get & Share menu to the bottom of your widget automatically. This allows users to easily get a copy of your widget for themselves. If you'd like to build the seeding page on your site to have both your widget and the Launchpad On-Page sharing menu, you might want to make sure that the Get & Share dock doesn't display. If it did, you would be giving users two ways to grab the widget, and it may be confusing.

You can use the Share It -> Get the code tool in the Widget Console to get the code you need to embed your widget on your site, properly configured. If you want to disable the Get & Share menu on an instance of your widget manually, you can pass a special -DBL parameter to your widget and set its value to 0. This is all done by overriding the widget URL, using the standard override scheme.

Doing this will prevent the dock from showing up on your widget when its on your seeding page, displayed from this URL, but it will still display once the widget is shared out to other locations.

Wherever the Clearspring widget URL appears in the generated code for your widget, just modify it to pass the -DBL value in the standard way, like this:

http://widgets.clearspring.com/o/WID/PID/-/-/-DBL/0/
or 
http://widgets.clearspring.com/o/WID/PID/-/-/-DBL/0/widget.js

You may need to make this change in two locations, depending on whether you are using HTML embed code or Javascript code. In either case, the URL will appear the same.

For more information on overriding configuration parameters, see the documentation on Overriding Parameters and on Widget URL Format. This special parameter is not discussed there, but is passed using the same general scheme.

Customizing the Appearance of your Menu

The Launchpad menu can be themed in a variety of ways, allowing you to make a completely custom look and feel that integrates well with the rest of your site.  For more information on customization options check out "Customizing the Launchpad On-Page Menu Guide".

Using your own button

You don't have to use any of our buttons if you don't want to. If you want to pop up the menu from a link, from your own button, or wherever, you can use the CreateMenu function to do so. The function lets you create a menu object, using the same arguments available to ShowMenu and ShowButton, attached to any arbitrary element on your page. This will make a menu that looks and acts like any other Launchpad menu, but it will not be initially visible. The menu will be automatically displayed whenever the user clicks the element you provided. So, you can make any image, text link, or anything else into a trigger for the menu!

For example, to attach a menu to a simple text link, and have it display when the link is clicked, you could do this:

<a id="myLink" href="#">My link</a>
<script type="text/javascript">
$Launchpad.CreateMenu({ wid : "46a4b57a60090fd4", actionElement : "myLink" });
</script>

This code in action would look like this: My link

The actionElement parameter represents the page element that the menu will be positioned relative to, as well as the element on which clicks will be responded to. You can specify a string ID, as in the example here, or even a Javascript object reference.

Note: You should include the CreateMenu call after you have defined the action element in your page.

Feel free to use the following button images with actionElement on your site.

    http://cdn.clearspring.com/launchpad/static/cs_button_share1.gif
    http://cdn.clearspring.com/launchpad/static/cs_favicon.png
    http://cdn.clearspring.com/launchpad/static/cs_favicon2.png
    http://cdn.clearspring.com/launchpad/static/cs_button_share1.gif

To use one of the buttons above you could do this:

<a id="csBtn" href="#"><img id="button-fav" src="http://cdn.clearspring.com/launchpad/static/cs_button_share1.gif" alt="" /></a>
<script type="text/javascript">
$Launchpad.CreateMenu({ wid : "46a4b57a60090fd4", actionElement : "csBtn" });
</script>

This code in action would look like this:

Using CSS to build a custom theme for your menu

You can specify a cascading stylesheet (CSS) of your own, and feed it into the Launchpad menu (using the customCSS parameter) for greater control over its appearance. The menu will use whatever style information you provide within this stylesheet. This is a simple and standards-compatible way to do simple things like change the color scheme of the menu, or even more advanced customization.

NOTE: You must specify a valid URL for this parameter -- if you specify an invalid URL, the menu will not appear correctly.

To use this feature, just add any simple style changes you'd like into a new stylesheet, set the CSS parameter, and your styles will combine with the default style. So, to change the color scheme, you could use code like this to point to your own stylesheet:

<script type="text/javascript">
$Launchpad.ShowMenu(
   { wid : "46a4b57a60090fd4", 
     customCSS : "http://www.example.com/mywidgets/themes/bgcolor.css" });
</script>

Within the stylesheet, you would just add the background color styling like this:

/* Main Background */
#launchpad {
   background: #ccc;
   border: 1px solid #333;
   color: #fff;
}

A commented example stylesheet is available here, if you want to copy it to your server for your own use. The resulting styled menu will look like this:

You override as much of the standard style as you want, even replacing every element with your own custom version. This gives you total control over the menu appearance, and will let you build a complete theme for the menu. For example, the following code will completely restyle the menu using a "black" style:

<script type="text/javascript">
$Launchpad.ShowMenu(
   { wid : "46a4b57a60090fd4", 
     customCSS : "http://cdn.clearspring.com/launchpad/skins/black.css" 
   });
</script>

This code will render the menu like this:

CSS examples & tips

The easiest way to get familiar with the CSS classes you can modify is to just look at the example stylesheets. Here are a few examples of themes you can use to get started; you can even copy these to your server and just use them directly, if you'd like:
The Blue theme

The Black theme

The White theme

Note: When passing in customized CSS to further personalize your Launchpad, remember to use absolute paths to reference your images and other assets.

Clue Us In!

If you develop any cool themes that you want to share, or have any questions on building your own themes, let us know in the forums!

Overview
Docs
Forum