TODO: Hooks aren't implemented in the actual UI yet, but the backend API documented here exists.

This documents the extension API as exposed via XPCOM. It consists of 2 interfaces, one for the httpd server, and another for adding/removing hooks to the Telescope UI. These hooks allow users to call your extension functions from the Telescope UI.

The Telescope UI service is accessed by the following javascript

try
{
var telescope = Components.classes['@awilco.net/telescope;1'].getService(Components.interfaces.awITelescope);
}
catch(e)
{	//telescope not installed
	return;
}

The standard technique for extensions to use this (or what hopefully will be the standard method, as I am decreeing it here :) ) is the following:

• Create a /web/ directory in your extension
• In your chrome.manifest, make sure there is a
  resource EXTENSION_NAME ./
  line
• Register your component for the profile-after-change event (NOTE: not app-startup otherwise it won't see a user set port!), put this code in the event handler section (see https://developer.mozilla.org/en/Observer_Notifications or one of the example documents at the end of this section

try
{
   var telescope = Components.classes['@awilco.net/telescope;1'].getService(Components.interfaces.awITelescope);
   var ios = Components.classes["@mozilla.org/network/io-service;1"].getService(Components.interfaces.nsIIOService);
   var uri = ios.newURI('resource://EXTENSION_NAME/web/',null,null);
   telescope.server.registerURI('/EXTENSION_NAME/',uri,null);
 
   //Add a hook to some event we want to fine
   telescope.addHook('mainPage','EXTENSION_NAME_hook1','/EXTENSION_NAME/do_something.sjs','My Hook!','/EXTENSION_NAME/hook_img.png');
}
catch(e)
{  //telescope not installed }

• In the web directory, you can use .sjs files to run scripts on the server, these can access XPCOM NOTE: these scripts are trusted with XPCOM access!

There are 3 types of hooks:

1 A main page hook, this is an image and text link that appears at the end of the main page list
2 A media list or media item hook. This appears in the popup menu that the user can raise by pressing and holding
3 A now playing Pane. This hook has no label or image (they are ignored), but the link returns html to be shown in the centre pane of the now playing view

Hooks are added with the addHook(category,id,URL,label,imgURL) command. All input values are strings, and all are required apart from imgURL.

category is one of the following strings:
'mainPage' A link on the main page
'mediaItem' A link that appears on the popup for tracks
'mediaList' A link that appears on unfiltered playlists only (i.e. items in the 'Playlists' link
'mediaView' A link that appears on filtered view links (e.g. property view pages), these are automatically added to the 'mediaList' category also id should be a unique string, so begin with the extension name.
URL is a aboslute (starts with /) path or, whole URL if pointing to some external website, that the link points to.
label is the text that appears in the menu.
imgURL is an optional image to show alongside the label.