Cooliris Developers

Javascript API Reference

The embeddable wall comes with a JavaScript API that allows programmers to build dynamic behavior into the webpage containing the wall, allowing bidirectional control between the wall and the page. These documents assume that the programmer is familiar with basic JavaScript and DHTML programming practices, including event callbacks and DOM manipulation.

cooliris.*

When the embeddable wall is loaded onto a page, a cooliris Javascript object is created. You can control the wall programmatically by using the API exposed by this object. The functions described in this section can be accessed by calling cooliris.functionName(...).

hasClient()
Returns true if the user visiting the site has the Cooliris client installed.
launchClient(feedURL, GUID (optional))
Launches the full Cooliris client displaying the specified feed URL, optionally selecting a particular item by its GUID.
onEmbedInitialized

When the embeddable wall is finished loading, an event is fired. You can set a function on the cooliris object that will be called when the embeddable wall is finished loading, to do any additional setup needed for the cooliris.embed API below.

The code below declares the cooliris object and its onEmbedInitialized function. When onEmbedInitialized is called, this means that the embeddable wall has finished loading. (This happens after the webpage has completed loading.) You can then start using the API calls described below. 

<script type="text/javascript">
var cooliris = {
    onEmbedInitialized : function() {
        alert("cooliris.embed is now available");
    }
};
</script>

cooliris.embed.*

Once the embeddable wall is loaded, (i.e., after cooliris.onEmbedInitialized has been called), the functions described in this section can be accessed by calling cooliris.embed.functionName(...).

getEmbedCode()
This function returns the object/embed code needed to share this wall. The string it returns can be pasted directly into an HTML document.
setFeedContents(mediaRSS)
Reloads the embeddable wall with Media RSS data, if, for instance, the feed was dynamically generated as a Javascript string. This is an unusual case; in most situations you will want to use setFeedURL() with a feed address.
setFeedURL(url)
Reloads the embeddable wall with the specified feed. The feed argument should be just like one supplied to the feed FlashVar.
selectItemByGUID(uniqueID)
Selects an item based on its unique identifier as specified in the MediaRSS feed. If the GUID cannot be found, the function will do nothing.
selectItemByIndex(absolutePosition)
Selects an item in the feed based on its absolute position. For example, calling cooliris.embed.selectItemByIndex(0) will select the first item in the feed.
selectItemNearby(relativePosition)

Selects an item in the feed based on its position relative to the currently selected item. For example, these links would implement custom navigation on the page outside of the embeddable wall: 

<a href="#" onclick="cooliris.embed.selectItemNearby(-1); return false;">
  Previous Item
</a>
<a href="#" onclick="cooliris.embed.selectItemNearby(+1); return false;">
  Next Item
</a>
setCallbacks(callbacksObject)

Binds callback functions to particular events fired by the embeddable wall. Currently the only event supported is selected which is fired when an element is selected or unselected on the wall. This function takes a mapping of event names to functions. For example, to bind the function onItemSelected to the selected event:

cooliris.embed.setCallbacks({
    select: onItemSelected
});

Handling Item Selects

The Cooliris JS API can inform your web application when the user selects or deselects an item on the wall. To do this, include the following Javascript on your webpage (this code must appear before the object/embed or swfobject code that loads the embeddable wall): 

<script type="text/javascript">
function onItemSelected(item) {
    if (item == null) {
        // nothing selected...place your code here
    } else {
        alert(item.content); // replace with your own code
    }
}

var cooliris = {
    onEmbedInitialized : function() {
        cooliris.embed.setCallbacks({
            select: onItemSelected
        });
    }
};

</script>

This is based on the code above, using onEmbedInitialized for event setup. In this example, we call cooliris.embed.setCallbacks to tell cooliris to use the onItemSelected function as the select callback. This means that when the user selects or deselects an item on the wall, we will notify you by calling the onItemSelected function with a single parameter (a JSON-encoded representation of the selected item). When an item is deselected, either when zooming out or when another item is selected, the function will be called with null rather than a JSON object.

The item object has the following properties, which correspond to the similiarly-named fields in Media RSS:

guid
unique identifier
title
a short title
description
a longer caption
link
the containing web page
thumb
media:thumbnail URL
content
media:content URL, which points to the full resolution photo or video
data
a Cooliris RSS extension to allow you to include extra metadata for each item

For example, when an item is changed this code will display the title inside the div with an id of titleField:

function onItemSelected(item) {
    if (item != null) {
        var t = document.getElementById("titleField");
        t.innerHTML = item.title;      
    }
}

item.cooliris:data – a Cooliris RSS Extension

You may wish to display extra metadata whenever a user selects an item. The cooliris:data element allows you to store this information inside the <item>...</item> tags in your Media RSS feed. When your onItemSelected(item) callback is called, you can access the information by inspecting item.data.

To enable this, your RSS feed must include the cooliris namespace declaration as follows:

<rss version="2.0"
    xmlns:media="http://search.yahoo.com/mrss/"   
    xmlns:atom="http://www.w3.org/2005/Atom"
    xmlns:cooliris="http://schemas.cooliris.com/syndication/2009">
    ...
</rss>

Inside each of your item tags, include a JSON object that describes the extra information:

<item>
    <title>Pine Trees #2</title>
    <link>http://www.flickr.com/photos/konaboy/2328596309/</link>
    ...
    <cooliris:data><![CDATA[
    {
        "waveHeight" : "3.5 feet",
        "priceOfPhoto" : "$1.99"
    }
    ]]></cooliris:data>
</item>
When your onItemSelected handler is called, you will be provided with an item object. Retrieve the extra information by accessing item.data.key. For example, item.data.priceOfPhoto will return "$1.99" in the example above.