clearspring - the widget network.

Platform Services Developers About Us Sign In Create Account

Platform

You are here: Docs → Technical Documentation → Developing Widgets → Using the Clearspring Container
 

Using the Clearspring Container

For a basic overview of the Clearspring Container, check out the fundamentals.

You don't need to do anything specific to use the Container; the Clearspring Platform loads registered widgets -- widgets that are not BLOBs shared with Launchpad On-Page -- in the Container automatically. All of the Container capabilities then become part of your widget transparently, including a built-in sharing menu.

Leveraging In-Widget APIs

All widgets loaded by the Clearspring Container get access to a number of powerful APIs. Take a look at the API docs for details.

Making your Widget Compatible with the Container

As a developer, you won't typically need to do anything special to your widget to have it work properly inside the Container. There are a few possible exceptions, however.

Web-Page Widgets

Web-page widgets really do work best when they are HTML, with or without Javascript, and do not include Java Applets or Flash objects:
  • Java applets will not function when included in web-page widgets
  • If your HTML includes Flash objects, you should set your widget type to Flash and point to the SWF instead. Within web pages, Flash objects cannot overlay each other -- if you want to make a Flash object a widget, let Clearspring handle the Flash object rather than your own HTML page

Flash/Flex Widgets

For Flash widgets, the most important thing is to watch your assumptions about the Stage. For ActionScript 2, the various global levels are also affected:

  • Using relative paths:  If your widget uses relative paths to load dynamic content, those paths will refer to Clearspring and not to your SWF's location. We recommend that you use absolute paths, and use a configuration parameter if you'd like this to be configurable (for production vs. test environments, for example). This is general good practice regardless, as it allows you to move resources to a CDN at some future point if you need to.
  • Using Stage dimensions:  When your widget is loaded by our Container, if the Get and Share button is configured to appear for your widget, this will increase the height of the Stage slightly. Also, if your widget has it's shadow enabled (controlled in the Widget Console), that will similarly take up space around the edge of the widget. This is important to realize if you are performing calculations based on this height information. When your widget is loaded, a special input parameter (Flashvar) called _cs_ypad will tell you exactly the number of pixels you can subtract from the Stage height to get your own widget's height.
  • Using _level0 (ActionScript 2):  Since our Container is loaded first by the Flash runtime within the browser, it lives at _level0 (in ActionScript 2 terms). Within your own SWF, referencing _level0 will actually reference our Container data as opposed to your own. Referencing _level0 in this way is not recommended regardless, but if your widget does do it, note that it cannot assume it is itself loaded there. Note as well that our Container locks the root, to preserve your ability to reference _root.
  • ActionScript 2 vs. ActionScript 3: Your Flash/Flex widget can be built in either ActionScript 2 or 3. These languages, as you probably know, are quite a bit different. For this reason, when you register your widget in our system you'll need to tell us which technology you've used to build your widget. Specifying the incorrect language will prevent your widget from loading properly. Unfortunately, it is not possible for us to automatically detect this reliably in all cases, so that's why we ask you specifically.

Supporting Desktop Destinations

The Clearspring container supports desktop environments, as well as web environments. There are a few additional considerations to take into account when designing your widget to target desktop platforms.

Widget Content Types

The desktop platforms rely on the widget-type indication you provide in the console when you register your widget, with the same caveats as outlined above. Specifically, avoid putting Flash or other plugin-requiring content inside your web-page-type widgets. In addition, blob widgets created dynamically using the Launchpad On-Page API are handled as HTML/Javascript. Currently, the platform cannot detect what type of content is inside the blob, so if your blob includes flash with your HTML, it will probably render incorrectly on the desktop platforms. It is recommended to exclude the Desktop tab (see the On-Page API) when using Launchpad On-Page with Flash widgets.

Flash Widget Borders

On some desktop platforms, you may notice white borders on the sides or top and bottom of your Flash widget. In order to prevent these, make sure to specify the height and width in the Clearspring console to match the size of the Flash stage EXACTLY.

If you are showing the dock on the web (the default), make sure 22 pixels are added to the height of your widget in the widget console. The widget control panel should do this automatically for you.

Finally, be sure to set the Flash scale mode to ExactFit or NoBorder.

Background Transparency

Transparency between widget content and background (in this case, the desktop) is handled differently on the various desktop platforms. Therefore, you must be careful with non-square widget borders such as rounded corners - they may appear with a background depending on the platform they're installed to. Note that any transparency handled inside your widget is rendered correctly on all platforms.

  • Flash transparency between widget and background is preserved on Yahoo Widgets for PC only.
  • Javascript/HTML transparency is preserved between widget and background on Mac Dashboard only.

Handling Linkouts

The desired behavior for links in a desktop setting is to open the requested URL in the default browser. Some desktop platforms will instead replace the widget content with the content from the requested URL, or sometimes will do nothing.

In order to ensure proper linking out to the default browser on all platforms, obey the following rules.

  • For Javascript/HTML, use _top or _parent as the target for the link.
  • For Flash, use _blank or a custom target name that is not _top or _parent.
  • Linking out with no target will most likely result in undesired behavior across platforms.

Tested Browsers

It's our goal to support as many browser platforms as possible, to allow your widget to spread across the web without any limitations.

The following browser versions have been officially certified:

  • Internet Explorer: 6.* (with minor issues), 7.*
  • Firefox (all platforms): 2.0.*, 3.0.*
  • Safari (on Mac OS X): 3.*

If there are other browser versions you are interested in, please let us know

Overview
Docs
Forum