Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

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

(Plugin)
(section rename)
Line 26: Line 26:
 
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.
 
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 ===
+
=== Creating the HTML file ===
 
Create a new HTML file called <tt>reversePlugin.html</tt> with the following content:
 
Create a new HTML file called <tt>reversePlugin.html</tt> with the following content:
 
<source lang="html4strict">
 
<source lang="html4strict">
Line 44: Line 44:
 
</source>
 
</source>
  
=== Plugin ===
+
=== Making it a plugin ===
 
Next, we'll add some code that exposes a service to Orion. Add the following, again inside the &lt;head&gt; tags:
 
Next, we'll add some code that exposes a service to Orion. Add the following, again inside the &lt;head&gt; tags:
 
<source lang="javascript">
 
<source lang="javascript">
Line 60: Line 60:
 
* <tt>provider.connect();</tt> — <span style="background-color: #00ff00;">TODO</span>
 
* <tt>provider.connect();</tt> — <span style="background-color: #00ff00;">TODO</span>
  
=== Implementing the service ===
+
=== Registering the service ===
 
Now we're going to create and register a service with the [[Orion/Documentation/Developer Guide/Plugging into the editor#orion.edit.command|"orion.edit.command"]] service type.
 
Now we're going to create and register a service with the [[Orion/Documentation/Developer Guide/Plugging into the editor#orion.edit.command|"orion.edit.command"]] service type.
 
Add the highlighted lines as shown:
 
Add the highlighted lines as shown:
Line 79: Line 79:
 
* <tt>provider.registerServiceProvider("orion.edit.command", serviceImpl, serviceProperties);</tt>: This call registers our service implementation and properties with the service type "orion.edit.command". At this point, if we were to install our plugin into Orion, we've got enough to make the Orion editor see our contribution. However, our contribution still does nothing. Let's fix that.<br />
 
* <tt>provider.registerServiceProvider("orion.edit.command", serviceImpl, serviceProperties);</tt>: This call registers our service implementation and properties with the service type "orion.edit.command". At this point, if we were to install our plugin into Orion, we've got enough to make the Orion editor see our contribution. However, our contribution still does nothing. Let's fix that.<br />
  
 +
=== Implementing the service ===
 
We'll fill in the <tt>serviceImpl</tt> and <tt>serviceProperties</tt> objects with the actual details of the service.
 
We'll fill in the <tt>serviceImpl</tt> and <tt>serviceProperties</tt> objects with the actual details of the service.
 
Change the <tt>serviceImpl</tt> object to look like this:
 
Change the <tt>serviceImpl</tt> object to look like this:

Revision as of 10:05, 13 June 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 an HTML file containing some JavaScript that knows how to connect to the Orion client. Plugins can be hosted on any web server and installed into Orion using their URL.

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 things like:

  • 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

For a full list of available services, see the Developer Guide.

What you need

Every plugin must include the following JavaScript library:

You can copy-paste its contents into a <script> tag in your plugin, or load it externally like so:

<script src="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 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 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="plugin.js" />

Making it a plugin

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();
 
        provider.connect();
    }
</script>

At this point, we've got an honest-to-goodness Orion plugin, albeit one that does nothing. 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.
  • provider.connect();TODO

Registering the service

Now we're going to create and register a service with the "orion.edit.command" service type. Add the highlighted lines as shown:

   window.onload = function() {
       var provider = new eclipse.PluginProvider();
var serviceImpl = { }; var serviceProperties = { }; provider.registerServiceProvider("orion.edit.command", serviceImpl, serviceProperties);
provider.connect(); }

Let's go over what we have now:

  • var serviceImpl: This object gives the implementation of our service, the part that will do the actual work. When someone requests our service, the plugin is loaded into an IFrame, and the service's methods are made available. The function-typed properties of the serviceImpl object define the service methods.
  • var serviceProperties: Every service provider can supply properties, which is an object that holds metadata about the service provider. If you're familiar with Eclipse desktop, you can think of service properties as analogous to the extensions declared in a plugin.xml file.
  • provider.registerServiceProvider("orion.edit.command", serviceImpl, serviceProperties);: This call registers our service implementation and properties with the service type "orion.edit.command". At this point, if we were to install our plugin into Orion, we've got enough to make the Orion editor see our contribution. However, our contribution still does nothing. Let's fix that.

Implementing the service

We'll fill in the serviceImpl and serviceProperties objects with the actual details of the service. Change the serviceImpl object to look like this:

        var serviceImpl = {
                run: function(text) {
                    return text.split("").reverse().join("");
                }
            };

- run() is a method expected by the orion.edit.command service API. - note about how it's called

Change the serviceProperties object to look like this:

        var serviceProperties = { 
                name: "Reverse Text",
                key: ["e", true, true] // Ctrl+Shift+e
            };

The finished plugin file

Make sure that your copy of 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, true] // Ctrl+Shift+e
            };
        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

Copyright © Eclipse Foundation, Inc. All Rights Reserved.