Developer Tips & Tricks - Controlling Gadget Playback from a Presentation

February 29, 2012

One of the lesser-known, but nonetheless important, changes that went out with the last release of our digital signage software was adding support for controlling the playback of a Gadget from within a Presentation itself. This functionality enables Gadgets to be started and stopped from Javascript inside the Presentation's HTML, and is especially useful when building multi-page Presentations. Now you'll know once a Gadget has loaded and is about to play, and you'll be able to pause that Gadget before it has a chance to start.

Get started with Rise Vision

In a nutshell, here's what you'll need to do to accomplish this:

  1. Create an array of JSON objects which contain the IDs of all Gadgets for which you want to control playback.
  2. Bind the document object to the gadgetReady event. This event will fire every time an Image Item, Gadget, Video or embedded Presentation reports that it is Ready and is about to start playing. The id of the item is passed as an argument.
  3. Compare the id parameter to each of the ids in the array. If a match is found, pause the Gadget by calling pauseCmd.

A Real-World Example

Let's step through a more concrete example. Let's assume that we have a two-page Presentation. The first page contains the Twitter List and RSS List Gadgets, while the second page has a Youtube Gadget. When the Presentation first loads, we want to pause the Youtube Gadget so that the audio is not heard.

Getting the Gadget IDs

The first hurdle is in figuring out what the Gadget IDs are. The easiest way to determine that is to add the following temporary code:

$(document).bind("gadgetReady", function(e, id) {
console.log(id); //Temporary code for getting the Gadget IDs.
});

Now when you preview the Presentation, the id for all Images, Gadgets, Presentations and Videos will be displayed in the console. To distinguish between them, you can look at the last character. Image IDs end with i, Gadgets with g, Presentations with p and Videos with v. If you have given your Placeholders meaningful names, you should be able to distinguish the Gadgets from each other. In my example, the Gadget IDs are: sc0_pre0_RSS_0gsc0_pre0_twitter_0g, and sc0_pre0_youtube_0g.

The Dynamic Nature of Gadget IDs

We are now ready to create our array of JSON objects, or are we? There is a further complication, and that is that the Gadgets will be renamed when changes are made and published to the Display. When that happens, the IDs will become sc1_pre0_RSS_0gsc1_pre0_twitter_0g, and sc1_pre0_youtube_0g. The next time changes are made, they will be sc2_pre0_RSS_0gsc2_pre0_twitter_0g, and sc2_pre0_youtube_0g, and so on. Nuts. Now what?

Well, we know that only the first part of the Gadget ID will change, so let's store the part that won't change:

var pages = [];

pages.push({
"id": "_pre0_twitter_0g",
"page": "1"
});
pages.push({
"id": "_pre0_RSS_0g",
"page": "1"
});
pages.push({
"id": "_pre0_youtube_0g",
"page": "2"
});

Pausing Gadgets when the Presentation Loads

Now we can go ahead and provide a new implementation for the gadgetReady event handler:

$(document).bind("gadgetReady", function(e, id) {
var newId = id.substring(3);
  for (var i = 0; i < pages.length; i++) {
if (newId == pages[i].id) {
pages[i].id = id;
break;
}
}
  for (var i = 0; i < pages.length; i++) {
if ((pages[i].page == "2") && (id == pages[i].id)) {
pauseCmd(id);
return;
}
}
});

We start by removing the first 3 characters of the id that gets passed to the callback function so that we will be able to compare it with our JSON values (which we have already removed the first 3 characters from). Next, we iterate over all of the Gadget IDs. When we find a match, we simply re-assign the id parameter back into the JSON object. We do this because the id parameter will contain the full Gadget ID (e.g. sc0_pre0_RSS_0gsc1_pre0_RSS_0g etc.). This will make it easier to work with them later on. Finally, we check if the current id matches any of the ids that are on page 2 of the Presentation. If a match is found, we pause the Gadget.

If we were to preview the Presentation at this point, the Youtube Gadget would be paused while the RSS and Twitter Lists would happily scroll away. But what about if a user were to navigate to the second page of the Presentation? We would need to start the Youtube Gadget and pause both the RSS List and Twitter List Gadgets.

Controlling Gadget Playback

To pause a Gadget, we already know that we should call pauseCmd. Let's write a function that takes the page number as a parameter, and pauses all Gadgets that are on that page:

function pause(page) {
for (var i = 0; i < pages.length; i++) {
if (pages[i].page == page) {
pauseCmd(pages[i].id);
}
}
}

Similarly, we can write a function to play all Gadgets that are on a certain page:

function play(page) {
for (var i = 0; i < pages.length; i++) {
if (pages[i].page == page) {
playCmd(pages[i].id);
}
}
}

From here, all we would need to do is call these functions at the appropriate times, passing in the proper page numbers.

Think you have a better way of doing this? Let's discuss in the forum.