Skip to main content
Jump to: navigation, search

Difference between revisions of "Orion/Documentation/Developer Guide/Simple plugin example"

m (warn)
(update service names)
Line 48: Line 48:
 
         var serviceImpl = { /* TODO */ };
 
         var serviceImpl = { /* TODO */ };
 
         var serviceProperties = { /* TODO */ };
 
         var serviceProperties = { /* TODO */ };
         provider.registerServiceProvider("editorAction", serviceImpl, serviceProperties);
+
         provider.registerServiceProvider("orion.edit.command", serviceImpl, serviceProperties);
 
         provider.connect();
 
         provider.connect();
 
     }
 
     }
Line 58: Line 58:
 
** <tt>var serviceImpl</tt> — This object gives the implementation of our service, the part that will do the actual work.<br>When someone requests our service — for example, by calling <tt>getService()</tt> on a <tt>ServiceReference</tt> object — our plugin will be loaded into an IFrame, and our service becomes available for use. The <tt>function</tt>-typed properties of the serviceImpl object define the methods of our service that people can call.
 
** <tt>var serviceImpl</tt> — This object gives the implementation of our service, the part that will do the actual work.<br>When someone requests our service — for example, by calling <tt>getService()</tt> on a <tt>ServiceReference</tt> object — our plugin will be loaded into an IFrame, and our service becomes available for use. The <tt>function</tt>-typed properties of the serviceImpl object define the methods of our service that people can call.
 
** <tt>var serviceProperties</tt> — Every service provider can supply '''properties''', which is an object that holds metadata about the service provider. Orion stores these properties when a plugin is installed <span style="background-color: #00ff00;">(?)</span>, and they can later be queried without causing the plugin to be loaded.<br>Properties are often used to filter out service providers that are irrelevant to a particular task. For example, if you're writing a service provider for content assist, you'd specify what file types your provider applies to in its properties. The content assist loader then only loads plugins that provide content assist for the particular file type being edited.  This is important because plugin load can be an expensive operation, so we want to avoid doing it if possible.<!-- If you're familiar with Eclipse desktop, you can think of service properties as analogous to the extensions declared in a plugin.xml file, since these can be queried without loading the plugin itself. -->
 
** <tt>var serviceProperties</tt> — Every service provider can supply '''properties''', which is an object that holds metadata about the service provider. Orion stores these properties when a plugin is installed <span style="background-color: #00ff00;">(?)</span>, and they can later be queried without causing the plugin to be loaded.<br>Properties are often used to filter out service providers that are irrelevant to a particular task. For example, if you're writing a service provider for content assist, you'd specify what file types your provider applies to in its properties. The content assist loader then only loads plugins that provide content assist for the particular file type being edited.  This is important because plugin load can be an expensive operation, so we want to avoid doing it if possible.<!-- If you're familiar with Eclipse desktop, you can think of service properties as analogous to the extensions declared in a plugin.xml file, since these can be queried without loading the plugin itself. -->
** <tt>provider.registerServiceProvider("editorAction", serviceImpl, serviceProperties);</tt> — <span style="background-color: #00ff00;">TODO</span>
+
** <tt>provider.registerServiceProvider("orion.edit.command", serviceImpl, serviceProperties);</tt> — <span style="background-color: #00ff00;">TODO</span>
 
** <tt>provider.connect();</tt> — <span style="background-color: #00ff00;">TODO</span>
 
** <tt>provider.connect();</tt> — <span style="background-color: #00ff00;">TODO</span>
 
* Now we'll fill in the <tt>serviceImpl</tt> and <tt>serviceProperties</tt> objects with the actual details of the service that our plugin will provide.
 
* Now we'll fill in the <tt>serviceImpl</tt> and <tt>serviceProperties</tt> objects with the actual details of the service that our plugin will provide.
Line 78: Line 78:
 
             };
 
             };
 
         var serviceProperties = { name: "Reverse Text", key: ["e", true] };
 
         var serviceProperties = { name: "Reverse Text", key: ["e", true] };
         provider.registerServiceProvider("editorAction", serviceImpl, serviceProperties);
+
         provider.registerServiceProvider("orion.edit.command", serviceImpl, serviceProperties);
 
         provider.connect();
 
         provider.connect();
 
     }
 
     }
Line 108: Line 108:
 
Here are some existing plugins we've written. View their source code to see how they work:
 
Here are some existing plugins we've written. View their source code to see how they work:
 
; http://orionhub.org/plugins/sampleCommandsPlugin.html
 
; http://orionhub.org/plugins/sampleCommandsPlugin.html
: Contributes several sample actions to the Orion navigator by using the <tt>fileCommands</tt> service type.
+
: Contributes several sample actions to the Orion navigator by using the <tt>orion.navigate.command</tt> service type.
  
 
; http://orionhub.org/plugins/htmlSyntaxHighlightPlugin.html
 
; http://orionhub.org/plugins/htmlSyntaxHighlightPlugin.html
: Contributes syntax highlighting support for HTML files by using the <tt>ISyntaxHighlight</tt> service type.
+
: Contributes syntax highlighting support for HTML files by using the <tt>orion.edit.highlighter</tt> service type.
  
 
; http://bokowski.github.com/format-js.html
 
; http://bokowski.github.com/format-js.html
: Contributes a "Beautify JS" button to the editor toolbar by using the <tt>editorAction</tt> service type.
+
: Contributes a "Beautify JS" button to the editor toolbar by using the <tt>orion.edit.command</tt> service type.
  
 
; http://mamacdon.github.com/m6/uglify/uglify-plugin.html
 
; http://mamacdon.github.com/m6/uglify/uglify-plugin.html
: Contributes an "Uglify JS" button to the editor toolbar byusing the <tt>editorAction</tt> service type.
+
: Contributes an "Uglify JS" button to the editor toolbar byusing the <tt>orion.edit.command</tt> service type.
  
 
== See also ==
 
== See also ==

Revision as of 11:19, 28 May 2011

Warning2.png
Article under construction
This How To is not finished yet. Some information may be incomplete.


This page explains how to write a plugin for Orion. It's intended for developers who want to extend Orion's functionality.

What's a plugin?

  • A plugin is basically just an HTML file that knows how to connect to the Orion client. Plugins are written in HTML and JavaScript, and can be hosted on any web server.
  • In order to be useful, a plugin should provide one or more services. When Orion needs a service contributed by a plugin, it loads the plugin inside an IFrame.
  • Orion currently supports a small set of extension points — service types that plugins can contribute to, in order to customize the client and add more functionality. These include:
    • Adding more commands to the editor toolbar
    • Adding more commands to the navigator view
    • Adding content assist for new file types
    • Adding syntax highlighting rules for new file types

What you need

Every plugin must include the following JavaScript libraries:

The easiest way to satisfy these is to get orion-plugin.js, which is a minified file that includes both of them. You can then copy-paste its contents into a <script> tag in your plugin, or load it externally like so:

<script src="orion-plugin.js" />

Writing the plugin

Let's make a plugin that adds a button to the toolbar of the Orion editor. When clicked, it will reverse the selected text in the editor. This is not a very useful feature, but it'll be a good introduction to the concepts involved.

Creating the plugin HTML file

  • Create a new HTML file called reversePlugin.html with the following content:
<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8" />
    <title>Reverse Plugin</title>
</head>
<body></body>
</html>
  • What we have now isn't a plugin yet. It's just a bare-bones HTML file. The next step is to include the API we'll need to talk to Orion.
  • Grab the orion-plugin.js file (see What you need) and put it in the same folder as reversePlugin.html. Then add this inside the <head> tags of the HTML file:
<script src="orion-plugin.js" />
  • Next, we'll add some code that exposes a service to Orion. Add the following, again inside the <head> tags:
<script>
    window.onload = function() {
        var provider = new eclipse.PluginProvider();
        var serviceImpl = { /* TODO */ };
        var serviceProperties = { /* TODO */ };
        provider.registerServiceProvider("orion.edit.command", serviceImpl, serviceProperties);
        provider.connect();
    }
</script>
  • At this point, we've got an honest-to-goodness Orion plugin, albeit one that doesn't do anything. Let's go over the various parts in detail:
    • var provider = new eclipse.PluginProvider()TODO
      Optionally, an object giving metadata about the plugin can be provided as an argument to the constructor.
    • var serviceImpl — This object gives the implementation of our service, the part that will do the actual work.
      When someone requests our service — for example, by calling getService() on a ServiceReference object — our plugin will be loaded into an IFrame, and our service becomes available for use. The function-typed properties of the serviceImpl object define the methods of our service that people can call.
    • var serviceProperties — Every service provider can supply properties, which is an object that holds metadata about the service provider. Orion stores these properties when a plugin is installed (?), and they can later be queried without causing the plugin to be loaded.
      Properties are often used to filter out service providers that are irrelevant to a particular task. For example, if you're writing a service provider for content assist, you'd specify what file types your provider applies to in its properties. The content assist loader then only loads plugins that provide content assist for the particular file type being edited. This is important because plugin load can be an expensive operation, so we want to avoid doing it if possible.
    • provider.registerServiceProvider("orion.edit.command", serviceImpl, serviceProperties);TODO
    • provider.connect();TODO
  • Now we'll fill in the serviceImpl and serviceProperties objects with the actual details of the service that our plugin will provide.

TODO

  • Before continuing, make sure that reversePlugin.html looks like this:
<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8" />
    <title>Reverse Plugin</title>
    <script>
    window.onload = function() {
        var provider = new eclipse.PluginProvider();
        var serviceImpl = {
                run: function(text) {
                    return text.split("").reverse().join("");
                }
            };
        var serviceProperties = { name: "Reverse Text", key: ["e", true] };
        provider.registerServiceProvider("orion.edit.command", serviceImpl, serviceProperties);
        provider.connect();
    }
</script>
</head>
<body></body>
</html>

Testing the plugin

First we need to host our plugin somewhere.


Now that you've got a URL for reversePlugin, install it:


Now let's try it out.

  • In Orion, go to the navigator and create a new file called test.txt.
  • Click on test.txt to open the editor.
  • You'll see a new button on the editor toolbar:
    Image
  • Select some text, click the button, and it should be reversed.

Examples

Here are some existing plugins we've written. View their source code to see how they work:

http://orionhub.org/plugins/sampleCommandsPlugin.html
Contributes several sample actions to the Orion navigator by using the orion.navigate.command service type.
http://orionhub.org/plugins/htmlSyntaxHighlightPlugin.html
Contributes syntax highlighting support for HTML files by using the orion.edit.highlighter service type.
http://bokowski.github.com/format-js.html
Contributes a "Beautify JS" button to the editor toolbar by using the orion.edit.command service type.
http://mamacdon.github.com/m6/uglify/uglify-plugin.html
Contributes an "Uglify JS" button to the editor toolbar byusing the orion.edit.command service type.

See also

Back to the top