Orion/How Tos/How to write an Orion SDK plugin
- 1 Introduction
- 2 Put the code in the client
- 3 Configure build.properties
- 4 Add a POM.xml file
- 5 Update the top-level POM file
- 6 Update the defaults
- 7 Update the site information
- 8 Update Orionnode
- 9 Update the client build
- 10 Update the server build
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:
- 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
- You have the Orion client repository checked out, and the projects imported in your workspace.
- 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:
- 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.
- Add the code as a separate bundle that will be built separately and lives in the
This how-to assumes you want to create a separate bundle and have placed your plug-in code in 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
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
- artifactId - this is the identifier of your plug-in from its MANIFEST.MF file, for example
- version - this is the version of your plug-in from its MANIFEST.MF file with
1.0.0.qualifierwhich would be entered as
1.0.0-SNAPSHOTin the POM file.
- packaging - this is how the plug-in should be packaged, the value is typically
Secondly, we add some information about the parent:
- groupId - this is the value
- artifactId - this is the client parent identifier
- version - this is the client parent version, which currently is:
- relativePath - this is the path relative to the parent, which is
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.
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
Update the site information
web folder, so we have to make a couple of edits:
- In the
org.eclipse.orion.client.ui/web/plugins/site/selfHostingRules.jsfile we have to add an entry that will map our plug-ins code folder to the root. For example:
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:
- You will have to add an entry to the client library
defaults.prefsfile 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:
- The second addition is in the
org.eclipse.orion.client/modules/orionode/lib/orion_static.jsfile. 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
Update the client build
To have your plug-in build as part of the Orion client build, we have to make two changes: add your bundle to the Orion feature and set it up for optimization.
Update the feature
The feature file we want to update is:
org.eclipse.orion.client/features/org.eclipse.orion.client-feature/feature.xml. To add your plugin to the Orion feature simply add a new
plugin section with the identifier and version of your plugin.
Update the Ant buildfile
- This section is a summary. For more details about minification, see the Releng Builds page.
As part of building for Orion, all plug-ins are optimized during the build which is accomplished using a RequireJS build config file. The build config file is org.eclipse.orion.client/releng/org.eclipse.orion.client.releng/builder/orion.build.js. To make sure that your new plugin is also optimized, we must make make 3 edits to this file:
- The first change is to the bundles array, to make sure your plugin gets staged to be optimized.
- The second change is to the jsdocs array, to list the source source folder(s) of your bundle that will be searched for API documentation.
- The third change is to the modules array, to list your bundle's pages and plugins that will be optimized by RequireJS.
- // Bundles whose ./web/ folders will be copied into the staging directory by the builder.
- bundles: [
- // ...
- // Folders that should be searched for JSDoc
- jsdocs: [
- // ...
- // List of modules that r.js will optimize
- modules: [
- // ...
- // Any additional modules from javscript bundle should be listed here.
Update the Ant buildfile
The Ant buildfile
org.eclipse.orion.server/releng/org.eclipse.orion.releng/builder/customTargets.xml requires three edits to integrate your new plug-in. The first two edits are exactly the same as the edits from the client update the buildfile section. The third edit is to have your API doc be generated during the build and requires an entry in the
java call in the
Update the server build
To have your plug-in build as part of the Orion server build, we have to make two edits: one in the configurator and one to the Ant buildfile
Update the configurator
So that the server knows about your plugin we have to add a resource mapping. The mapping is added to the
org.eclipse.orion.server/bundles/org.eclipse.orion.server.configurator/plugin.xml file as a new
httpcontext entry and a new
resource element provides an alias for your