Orion/How Tos/How to write an Orion SDK plugin

Introduction

This how-to explains creating a plug-in that is part of the Orion SDK - one that is stored, built and used in the Orion client. For a how-to on creating a plug-in in general, please see the Simple Plug-in Example.

The remainder of this how-to assumes a few things:

1. You have already created a plug-in and that you want to hook all of the pieces up to make it part of the SDK. As an example the new org.eclipse.orion.client.javascript plug-in will be referenced.
2. You have the Orion client repository checked out, and the projects imported in your workspace.
3. You have some familiarity with Ant buildfiles and editing them.

Put the code in the client

When you add a plug-in to the SDK, you could add the code a couple of ways:

1. Add the code in the org.eclipse.orion.client.ui/web/plugins/ folder, update the defaults.prefs file and have it built as part of the client UI bundle.
2. Add the code as a separate bundle that will be built separately and lives in the org.eclipse.orion.client/bundles/ folder.

This how-to assumes you want to create a separate bundle and have placed your plug-in code in the org.eclipse.orion.client/bundles/ folder. For example the JavaScript plug-in is found in the org.eclipse.orion.client/bundles/org.eclipse.orion.client.javascript/ folder.

Configure build.properties

The build.properties file must be created / edited to tell Orion what you would like to be built.

The most common cases will have two entries:

• bin.includes - what should be included in the binary-only build
• src.includes - what should be included in the source build

The JavaScript plug-in, for example, has the following entries:

bin.includes = META-INF/,\
               bundle.properties,\
               web/
src.includes = web/,\
               about.html

A word of caution here, your bin.includes entry must contain the root to where your plug-ins' HTML resides or the build will fail stating it cannot find your plug-in.

Add a POM.xml file

Since Orion is moving towards a completely Tycho / Maven-based build, your plug-in will also require a pom.xml file to indicate how it should be built. For more information on POM files please see the Maven POM file introduction.

First we add some information about our plug-in:

• groupId - this will be have the value org.eclipse.orion
• artifactId - this is the identifier of your plug-in from its MANIFEST.MF file, for example org.eclipse.orion.client.javascript
• version - this is the version of your plug-in from its MANIFEST.MF file with -SNAPSHOT added after the end. For example the JavaScript plug-in has the version 1.0.0.qualifier which would be entered as 1.0.0-SNAPSHOT in the POM file.
• packaging - this is how the plug-in should be packaged, the value is typically eclipse-plugin

Secondly, we add some information about the parent:

• groupId - this is the value org.eclipse.orion
• artifactId - this is the client parent identifier org.eclipse.orion.client.parent
• version - this is the client parent version, which currently is: 1.0.0-SNAPSHOT
• relativePath - this is the path relative to the parent, which is ../..

As an example, the complete POM.xml for the JavaScript plug-in looks like:

<project xmlns="http://maven.apache.org/POM/4.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
	<modelVersion>4.0.0</modelVersion>

	<groupId>org.eclipse.orion</groupId>
	<artifactId>org.eclipse.orion.client.javascript</artifactId>
	<version>1.0.0-SNAPSHOT</version>
	<packaging>eclipse-plugin</packaging>

	<parent>
		<groupId>org.eclipse.orion</groupId>
		<artifactId>org.eclipse.orion.client.parent</artifactId>
		<version>1.0.0-SNAPSHOT</version>
		<relativePath>../..</relativePath>
	</parent>
</project>

Update the top-level POM file

To make sure your plug-in is built as part of the Orion build you also must update the POM file in the top level of the client repository: org.eclipse.orion.client/pom.xml. In the modules section you must add an entry with the repository-relative path to your plug-in root.

For example the JavaScript project added the entry:

<module>bundles/org.eclipse.orion.client.javascript</module>

Update the defaults

To have your plug-in show up installed by default in Orion (see testing Orion plugins for more information) you will want to add an entry to the org.eclipse.orion.client.ui/web/defaults.pref file.

The entry is based off the root of where your plug-in provides its packages (more on this in update the site information section) and specifies if the plug-in should be started automatically. For example, the JavaScript plug-in adds the entry: "javascript/plugins/javascriptPlugin.html":true. This entry points to the HTML file for the plug-in which is based off the root supplied in the site configuration and also indicates that the plugin should be automatically started.

The path entered here appended to the path from the site configuration must point directly to your plug-ins' HTML file. For example the JavaScript plugin has the org.eclipse.orion.client.javascript/web/ path in its site configuration, making the full path to the plugin HTML file: org.eclipse.orion.client.javascript/web/javascript/plugins/javascriptPlugin.html.

Update the site information

For your plug-in to be able to load correctly while self-hosting you will need to add the path to the folder that contains your plug-ins' code. For example, the JavaScript plugin has all of its code in its web folder, so we have to make a couple of edits:

1. In the org.eclipse.orion.client.ui/web/plugins/site/selfHostingRules.js file we have to add an entry that will map our plug-ins code folder to the root. For example: { type: FILE, source: "/", targetPattern: "${0}/bundles/org.eclipse.orion.client.javascript/web" },. This entry will then be used in the site configuration page by the tool that converts a site to a self-host site.
2. In any existing sites that you want your plug-in to appear in, you will have to edit the site information and add your plug-ins' code path mapped to the server root. For example the JavaScript plug-in adds a path of your_target_name/org.eclipse.orion.client/bundles/org.eclipse.orion.client.javascript/web mapped to a server path of /.

Update Orionnode

If you would also like your plug-in to run in the Node.js version of Orion, you will have to make a few edits:

1. You will have to add an entry to the client library defaults.prefs file which is found in org.eclipse.orion.client/modules/orionode/lib/orionode.client/defaults.pref. The entry you add here is the same as the one we added in the update the defaults section. For example: "javascript/plugins/javascriptPlugin.html":true
2. The second addition is in the org.eclipse.orion.client/modules/orionode/lib/orion_static.js file. The entry here is to add a static mapping for your new plug-in, and is done by adding a repository-relative path to your plug-ins' content in the connect function.
   For example the JavaScript plug-in added the following: statik(path.resolve(orionClientRoot, './bundles/org.eclipse.orion.client.javascript/web'), options),