Using Javascript with Joost Widgets
To get some real interactivity in your widget you'll probably want to use some Javascript. Joost Widgets use Javascript in just the same way as web pages do, except that you only have to code for one browser (the Joost player, based on Mozilla) rather than several.
Let's suppose you've done the first tutorial and made a 'hello world' widget. You can put Javascript straight into your HTML file like this:
<html>
<head>
<style type="text/css">
* { color:white }
</style>
<script>
//your Javascript here
</script>
</head>
<body>
<div id="output"><p>My first widget</p></div>
</body>
</html>
(I've put an extra div in there for more fun later).
Or you can link to it in another file like this:
<html>
<head>
<style type="text/css">
* { color:white }
</style>
<script src="hello.js"></script>
</head>
<body>
<div id="output"><p>My first widget</p></div>
</body>
</html>
Where 'hello.js' needs to be in the same folder as your index.html.
With Javascript you can use all the usual DOM methods to change values, for example:
<script>
var div = document.getElementById("output");
div.innerHTML="<p>This is my new output</p>";
</script>
This means that once you've zipped it up and run it inside Joost as usual the text in your hello widget will look like this:
This is my new output
instead of
My first widget
Once you've got the hang of some simple Javascript you might like to try some of the Joost-specific methods. So how about this:
<script>
var div = document.getElementById("output");
div.innerHTML="<p>Hello "+Joost.firstName+"</p>";
</script>
(see here for the API calls in the Joost class; and note that the user can prevent you seeing this information).
If, like me, you're something of a copy-and-paste coder, you might want to look at Dive Into Greasemonkey, an excellent place to look for Javascript examples for common things you want to do, including DOM manipulation, or the Mozilla Javascript reference which is useful for looking up API calls. There are Joost Widget code examples available for you to reuse as you wish (there's a BSD-like license).
The Joost API is here, and as always we welcome suggestions about that or about these blogposts.
Playing videos and opening links in Joost widgets
Links are important in Joost. Every video and channel in Joost has a "Joost Link" - a URL and associated web page. Joost Links allow people to link directly to Joost videos on the Web - and you can use Joost Links in widgets to play videos in Joost.
The general form of a Joost Link is:
http://joost.com/<publicID>#param1=value1,param2=value2
The publicID must contain exactly 7 characters, from the set a-z 0-9.
There is no way to distinguish Joost Links for channels and videos except by de-referencing them.
There are also some more complex Joost Links. For example:
http://joost.com/0440001#program=044000u
describes the channel Aardman Animations, starting with the video "Creature Comforts - The Sea";
http://joost.com/0440001#program=0440007,start=20000
Describes the show "Town Called Panic: Cow Hulk" in channel "Aardman Animations", starting 20 seconds in.
Within a Joost Widget you can play one of these links like this:
<a onclick=\'navigate("http://joost.com/0440001#program=044000u")\'>Play video inside channel</a>
To open a web page that is not a Joost Link, just use navigate in the following way:
<a href='#' onclick='navigate(\"http://dev.joost.com\")'>Joost Developer Site</a>
You can see some example code here and the API definition is here.
Next time we'll see how to test these Joost Links to make sure they can be played by the viewer.
Testing whether your user can view a video or channel
If you're using Joost Links in a widget you often need to know if they can be played by the user of your widget. It's a fact of life (and of business) that certain videos are only playable in some regions; and from time to time, a channel line-up may change.
To check that a Joost Link is playable, you can use retrieveURL in the Engine class. Here's a very simple example of how you might check a given URL:
var url="http://joost.com/123456a";
Engine.retrieveURL(url, testChannelListener);
var testChannelListener = {
updateSuccess : function(channel, entry) {
logMessage("updateSuccess() "+channel.title+" "+entry.title);
},
updateFailure : function(errorCode) {
if(errorCode=="load:404"){
logMessage("Cannot be played because not a Joost link");
}else
if(errorCode=="load:403"){
logMessage("Cannot be played because of geo restrictions);
}else{
logMessage("Cannot be played for some reason "+errorCode);
}
}
}
Let's walk though it:
First, get your URL and send it to retrieveURL
var url="http://joost.com/123456a";
Engine.retrieveURL(url, testChannelListener);
Engine.retrieveURL takes two arguments, the URL you want to check and a listener callback which is called when retrieveURL has the information about the URL.
I find callbacks rather strange, as from what I can remember of my Java days I never used anything like them - but here we can just think of them as functions to be called when something that takes time has been completed, in this case the lookup about the URL, (the downside about callbacks is that it's a bit complicated to send arguments to them, but never mind that here as we don't need to).
Second, write a listener
The second argument is our class, testChannelListener. What we want to happen here is for this class to listen for two possible function calls which the Joost engine might provide depending on what it finds for the URL.
updateSuccess
If it is a Joost Link and we can play it we get a success. Here we just print to the console (see output to the console by calling it up using control-shift-D)
updateSuccess : function(channel, entry) {
logMessage("updateSuccess() "+channel.title+" "+entry.title);
},
If we get this we can use the channel and the entry and the various methods associated with those.
updateFailure
If there's a problem we usually get a failure:
updateFailure : function(errorCode) {
if(errorCode=="load:404"){
logMessage("Cannot be played because not a Joost link");
}else
if(errorCode=="load:403"){
logMessage("Cannot be played because of geo restrictions);
}else{
logMessage("Cannot be played for some reason "+errorCode);
}
}
and an errorCode is returned.
This functionality is very useful for bookmarks or the retrieval of other Joost content that you might want to suggest to the user, for example with the URL methods. I use it for making suggestions to the user.
The detail of this part of the Joost Widget API is in the Engine section - see retrieveURL.
Second preview release
Hi, here's a new developer release, no new features but we've fixed
many little bugs in various places, and we may have a fix for the
"empty explore" Bug. It isn't enabled by default, but if you're seeing
this bug add the preference: user_pref("tvp.ui.spoonMasking",false);
to your prefs file and then see if it works. We're pretty sure the
problem was related to masking issues with some graphics cards, but
are yet to really reproduce.
Download preview release 2 for Windows
Download preview release 2 for Mac
Try it out and let us know anything you find.
TV Anywhere, anytime
