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

Introduction

This how-to explains how to create a plug-in built as part of the Orion SDK. To create a plug-in that interacts with Orion, see the developer guide's Simple Plugin Example.

The remainder of this how-to assumes the following:

1. You have already created a plugin (folder structure and description). This guide will show you the additional steps to make the plug-in part of the SDK.
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.

The new plug-in org.eclipse.orion.client.javascript will be used as an example.

Add build.properties

A build.properties file must be added at the root of the plug-in project. It must specify what files should be built for your plug-in.

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 plugin, 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 plugin's HTML resides or the build will fail stating it cannot find your plugin.

Add POM.xml

Since Orion is moving towards a completely Tycho / Maven-based build, your plug-in will also require a pom.xml at the root of the plug-in 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 plugin as direct children of the POM project element:

• groupId - this will be have the value org.eclipse.orion
• artifactId - this is the identifier of your plugin from its MANIFEST.MF file, for example org.eclipse.orion.client.javascript
• version - this is the version of your plugin from its MANIFEST.MF file with -SNAPSHOT added after the end. For example the JavaScript plugin 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 plugin should be packaged, the value is typically eclipse-plugin

Secondly, we have to add a section 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 plugin 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 default plug-ins

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

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

The path entered here added to the path from the site configuration must point directly to your pluings' 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.