A Widget is a small, stand alone application which sits on your desktop. There are a number of platforms on which you can develop widgets, including: Yahoo! Widgets Apple Dashboard for Mac OS X 1.4 Tiger This example Widget runs on the Yahoo! Widgets which provides an engine for both Windows PC and Mac.

Widgets generally display information from a remote source or a web-based function such as search. The BBC Web API can be used as such a source of information to build your own widget. For further guidance on how to to this, read the How it works section below. To run the example BBC Web API What's On Widget you first need to:

1. install the Yahoo! Widgets engine
2. download the BBC Web API What's On Widget and double-click on the .widget file to start the Widget.

	Chaning the current channel is done by clicking on the tab which appears at the bottom of the Widget when you hover over it. This displays all the available BBC tv and radio channels. Click on one to change the curren display. This will update your preference so that if you close the Widget this channel will be selected when you restart it.
	You can view the schedule listing for the current channel by clicking on the channel logo.
	You can toggle the extra information displayed alongside the current programme. Click on the red button which displays 'next' by default. This will cycle through the next programme current programme description livetext (radio only)
	Selecting a radio network gives you the oppotunity to listen to the live RealAudio stream. Click on the play button to play and the stop button to stop.

The Widget consists of a image resources and a .kon file which defines the Widget layout and interactivity through XML and Javascript.

Accessing the API

Data is retrieved from the API using the Javascript XMLHTTPRequest object, just as is used in the AJAX example. Communication in the Widget is done synchronously and the server response is handled directly in the same function. The following is the function to retrieve shcedule information for a channel:

//***************************************************************************
// getSchedule()
//
// Request the schedule for the current channel using the BBC Web API
//***************************************************************************				
function getSchedule( channelId )	{
		
  try {
    var request = new XMLHttpRequest();
    request.open( "GET", api_root + "method=bbc.schedule.getProgrammes&detail=schedule&limit=9
      &channel_id=" + channelId, false );
    request.send();
				
    if ( request.status == 200 ) {
      var programmeList = request.responseXML.evaluate( "rsp/schedule/programme" );
    }
  } catch (e) {
    print (e);
    miscText.text.data = "Error";
  }
      	
  return programmeList;
}

Elements of the XML response are retrieved to display the desired information, for example the programme title:

var item = itemList.item( 0 );
title = item.getAttribute('title');
if(title.length > 18){
  title = title.substring(0,18) + "...";
}

Playing live radio streams

The API provides the location of RealAudio streams of every national BBC radio network. It is possible to play these directly within the Widget. The following functions retrieve the RealAudio stream for the current channel and play it:

//***************************************************************************
// getChannelLocations()
//
// Request the location for the current channel using the BBC Web API
//***************************************************************************		
function getChannelLocations( channelId ) {
		
  try	{
    var request = new XMLHttpRequest();
    request.open( "GET", api_root + "method=bbc.channel.getLocations&channel_id=" + channelId, false );
    request.send();
				
    if ( request.status == 200 ) {
      var locations = request.responseXML.evaluate( "rsp/channel/location/type[.='real-audio']/../url" );
      var url = locations.item( 0 ).firstChild.data;
    }

  }	catch (e)	{
    print (e);
    miscText.text.data = "Error: loc " + channelId;
  }		
		
  return url;
}
		
//***************************************************************************
// playCurrentChannel()
//
// Calls to request current channel location
//***************************************************************************			
function playCurrentChannel() {
		  
  var url = getChannelLocations( channels[ preferences.channelPref.value ].id );
  playChannel( url );
}		
		
//***************************************************************************
// playChannel()
//
// Sends the URL to RealPlayer
//***************************************************************************		
function playChannel( url )	{		

  try { 
    if ( !Player ) {
      Player = COM.createObject('rmocx.RealPlayer G2 Control'); 
      COM.connectObject( Player, "RealPlay" ); 
    }
			
    Player.SetSource( url ); 
    Player.DoPlay();
				
    playing = true;
				
    showStopListen();
		
  } catch(e) {}
}