Differences

This shows you the differences between two versions of the page.

Link to this comparison view

telescope_extension_api [2015/08/15 15:15] (current)
Line 1: Line 1:
 +==== Extension API ====
 +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.
 +
 +=== Telescope UI Hooks ===
 +The Telescope UI service is accessed by the following javascript
 +<code javascript>​
 +try
 +{
 +var telescope = Components.classes['​@awilco.net/​telescope;​1'​].getService(Components.interfaces.awITelescope);​
 +}
 +catch(e)
 +{ //​telescope not installed
 + return;
 +}
 +</​code>​
 +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
 +<code javascript>​
 +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 }
 +</​code>​
 +  * 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.\\