PluginDevelopmentGettingStarted » History » Version 1

Version 1/14 - Next » - Current version
Andreas Smas, 02/08/2013 11:18 PM


Developing a plugin

To develop a plugin for Showtime it's easiest to load the plugin via Showtime's plugin development argument (-p):

Example:

    build.linux/showtime -p testplugin

This will output something like:

    plugins [ERROR]: Unable to load development plugin: testplugin
                     Unable to load testplugin/plugin.json -- File not found

Go ahead and create the directory:

    mkdir testplugin

Edit the JSON file with your favorite text editor:

    emacs testplugin/plugin.json

And put the required fields in there:

    {
     "type": "javascript",
     "file": "testplugin.js",
     "id": "testplugin" 
    }

You can reload the development plugin at any time by pressing Shift+F5 in Showtime (assuming you have not mapped that key/action to something
else in the keymapper setup). This works fine even if the plugin failed to load for whatever reason. All hooks and resources that are
registered by the plugin is automatically removed when the plugin is reloaded. The same procedure happens when a plugin is uninstalled
from the plugin repository browser. Pressing Shift+F5 will also reload the data model for the current loaded page. Ir. If you have a
page opened that links to your plugin in development mode Showtime will first reload the plugin and then reload the page itself. This makes it very easy to do rapid development of plugins.

Now go ahead and edit the javascript file

    emacs testplugin/testplugin.js

Put one single line in that file:

    showtime.print('hello world');

Press Shift+F5 and the console window from where you started showtime
should say:

    hello world
    plugins [INFO]: Reloaded dev plugin testplugin/

Showtime will just execute the plugin which only outputs 'Hello world' on the console and then exits. So, how to create something more
interesting? First the javascript code needs to create a scope where its local variables will live and also need to remember 'this' which
is, when the script is invoked, a plugin object created by Showtime. Change the code to:

(function(plugin) {
  showtime.print("Hello! I'm a plugin running inside Showtime " + showtime.currentVersionString);
})(this);
  1. Routing an URI to the plugin

Almost everything in Showtime has an URI. This is also one of the way
for a user to interact with plugins. Each plugin reserves URI space
starting with the plugin's ID. This is not imposed by any code in
Showtime but rather a convention. URI routes registered by plugins
take precedence over the URI routes that Showtime itself handle so it
is possible to, for example, add routes for certain well known domains
on the Internet (think http://www.youtube.com/ .. )

Back to our test code:

(function(plugin) {
// Enable URI routing for this plugin.
plugin.config.URIRouting = true;
// Add a URI route and a corresponding function to be invoked
plugin.addURI("testplugin:hello", function(page) {
showtime.print("I was called");
})
})(this);

Now, reload the plugin (Shift+F5) and type "testplugin:hello" in the
search input field on Showtime's home page. (Maybe you didn't know, but
the search field can be used to open any valid Showtime URI). Showtime
will open a new page with nothing but a spinning throbber and just
print the console message. Not very exciting but it's a good start.