PluginDevelopmentGettingStarted » History » Version 2

Andreas Smas, 02/08/2013 11:19 PM

1 1 Andreas Smas
h1. Developing a plugin
2 1 Andreas Smas
3 1 Andreas Smas
To develop a plugin for Showtime it's easiest to load the plugin via Showtime's plugin development argument (-p):
4 1 Andreas Smas
5 1 Andreas Smas
Example:
6 1 Andreas Smas
<pre>
7 2 Andreas Smas
build.linux/showtime -p testplugin
8 1 Andreas Smas
</pre>
9 1 Andreas Smas
10 1 Andreas Smas
This will output something like:
11 1 Andreas Smas
12 1 Andreas Smas
<pre>
13 2 Andreas Smas
plugins [ERROR]: Unable to load development plugin: testplugin
14 2 Andreas Smas
                 Unable to load testplugin/plugin.json -- File not found
15 1 Andreas Smas
</pre>
16 1 Andreas Smas
17 1 Andreas Smas
Go ahead and create the directory:
18 1 Andreas Smas
19 1 Andreas Smas
<pre>
20 2 Andreas Smas
mkdir testplugin
21 1 Andreas Smas
</pre>
22 1 Andreas Smas
23 1 Andreas Smas
Edit the JSON file with your favorite text editor:
24 1 Andreas Smas
25 1 Andreas Smas
<pre>
26 2 Andreas Smas
emacs testplugin/plugin.json
27 1 Andreas Smas
</pre>
28 1 Andreas Smas
29 1 Andreas Smas
And put the required fields in there:
30 1 Andreas Smas
31 1 Andreas Smas
<pre><code class="javascript">
32 2 Andreas Smas
{
33 2 Andreas Smas
  "type": "javascript",
34 2 Andreas Smas
  "file": "testplugin.js",
35 2 Andreas Smas
  "id": "testplugin"
36 2 Andreas Smas
}
37 1 Andreas Smas
</code></pre>
38 1 Andreas Smas
39 1 Andreas Smas
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
40 1 Andreas Smas
else in the keymapper setup). This works fine even if the plugin failed to load for whatever reason. All hooks and resources that are
41 1 Andreas Smas
registered by the plugin is automatically removed when the plugin is reloaded.  The same procedure happens when a plugin is uninstalled
42 1 Andreas Smas
from the plugin repository browser.  Pressing Shift+F5 will also reload the data model for the current loaded page. Ir. If you have a
43 1 Andreas Smas
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.
44 1 Andreas Smas
45 1 Andreas Smas
Now go ahead and edit the javascript file
46 1 Andreas Smas
<pre>
47 2 Andreas Smas
emacs testplugin/testplugin.js
48 1 Andreas Smas
</pre>
49 1 Andreas Smas
Put one single line in that file:
50 1 Andreas Smas
51 1 Andreas Smas
<pre><code class="javascript">
52 2 Andreas Smas
showtime.print('hello world');
53 1 Andreas Smas
</code></pre>
54 1 Andreas Smas
55 1 Andreas Smas
Press Shift+F5 and the console window from where you started showtime
56 1 Andreas Smas
should say:
57 1 Andreas Smas
58 1 Andreas Smas
<pre>
59 2 Andreas Smas
hello world
60 2 Andreas Smas
plugins [INFO]: Reloaded dev plugin testplugin/
61 1 Andreas Smas
</pre>
62 1 Andreas Smas
63 1 Andreas Smas
Showtime will just execute the plugin which only outputs 'Hello world' on the console and then exits. So, how to create something more
64 1 Andreas Smas
interesting?  First the javascript code needs to create a scope where its local variables will live and also need to remember 'this' which
65 1 Andreas Smas
is, when the script is invoked, a plugin object created by Showtime. Change the code to:
66 1 Andreas Smas
67 1 Andreas Smas
<pre><code class="javascript">
68 1 Andreas Smas
(function(plugin) {
69 1 Andreas Smas
  showtime.print("Hello! I'm a plugin running inside Showtime " + showtime.currentVersionString);
70 1 Andreas Smas
})(this);
71 1 Andreas Smas
</code></pre>
72 1 Andreas Smas
73 2 Andreas Smas
h2. Routing an URI to the plugin
74 1 Andreas Smas
75 2 Andreas Smas
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
76 2 Andreas Smas
starting with the plugin's ID. This is not imposed by any code in Showtime but rather a convention. URI routes registered by plugins
77 2 Andreas Smas
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/ .. )
78 1 Andreas Smas
79 1 Andreas Smas
Back to our test code:
80 1 Andreas Smas
81 2 Andreas Smas
<pre><code class="javascript">
82 2 Andreas Smas
(function(plugin) {
83 2 Andreas Smas
  // Enable URI routing for this plugin.
84 2 Andreas Smas
  plugin.config.URIRouting = true;
85 1 Andreas Smas
    
86 2 Andreas Smas
  // Add a URI route and a corresponding function to be invoked
87 2 Andreas Smas
  plugin.addURI("testplugin:hello", function(page) {
88 2 Andreas Smas
    showtime.print("I was called");
89 2 Andreas Smas
  })
90 2 Andreas Smas
})(this);
91 2 Andreas Smas
</code></pre>
92 1 Andreas Smas
93 2 Andreas Smas
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.