Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "Orion/How Tos/How to write an Orion SDK plugin"
| Line 1: | Line 1: | ||
= Introduction = | = Introduction = | ||
| − | This how-to | + | 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 [[Orion/Documentation/Developer_Guide/Simple_plugin_example | Simple Plugin Example]]. |
| − | + | ||
| − | The remainder of this how-to assumes | + | The remainder of this how-to assumes the following: |
| − | #You have already created a plugin and | + | #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. |
#You have the [http://git.eclipse.org/c/orion/org.eclipse.orion.client.git/ Orion client repository] checked out, and the projects imported in your workspace. | #You have the [http://git.eclipse.org/c/orion/org.eclipse.orion.client.git/ Orion client repository] checked out, and the projects imported in your workspace. | ||
#You have some familiarity with Ant buildfiles and editing them. | #You have some familiarity with Ant buildfiles and editing them. | ||
| − | + | The new plug-in <code>org.eclipse.orion.client.javascript</code> will be used as an example. | |
| − | = | + | = Add the code to the client = |
| − | + | = Add build.properties = | |
| + | |||
| + | A <code>build.properties</code> 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: | The most common cases will have two entries: | ||
| Line 27: | Line 28: | ||
</pre> | </pre> | ||
| − | A word of caution here, your <code>bin.includes</code> entry '''must''' contain the root to where your | + | A word of caution here, your <code>bin.includes</code> entry '''must''' contain the root to where your plugin's HTML resides or the build will fail stating it cannot find your plugin. |
| − | = Add | + | = Add POM.xml = |
| − | Since Orion is moving towards a completely Tycho / Maven-based build, your | + | Since Orion is moving towards a completely Tycho / Maven-based build, your plug-in will also require a <code>pom.xml</code> at the root of the plug-in to indicate how it should be built. For more information on POM files please see the [http://maven.apache.org/guides/introduction/introduction-to-the-pom.html Maven POM file introduction]. |
First we add some information about our plugin as direct children of the POM project element: | First we add some information about our plugin as direct children of the POM project element: | ||
| Line 66: | Line 67: | ||
</pre> | </pre> | ||
| − | = Update | + | = Update default plug-ins = |
| − | To have your plugin show up installed by default in Orion (see [[Orion/Documentation/Developer_Guide/Simple_plugin_example#Testing_the_plugin|testing Orion plugins]] for more information) you | + | To have your plugin show up installed by default in Orion (see [[Orion/Documentation/Developer_Guide/Simple_plugin_example#Testing_the_plugin|testing Orion plugins]] for more information) you must add an entry to the <code>org.eclipse.orion.client.ui/web/defaults.pref</code> file. |
The entry is based off the root of where your plugin provides its packages (more on this in [[#Update the site information|update the site information]] section) and specifies if the plugin should be started automatically. For example, the JavaScript plugin adds the entry: <code>"javascript/plugins/javascriptPlugin.html":true</code>. This entry points to the HTML file for the plugin and is based off the root you supply in the [[#Update the site information|site configuration]] and also indicates that the plugin should be automatically started. | The entry is based off the root of where your plugin provides its packages (more on this in [[#Update the site information|update the site information]] section) and specifies if the plugin should be started automatically. For example, the JavaScript plugin adds the entry: <code>"javascript/plugins/javascriptPlugin.html":true</code>. This entry points to the HTML file for the plugin and is based off the root you supply in the [[#Update the site information|site configuration]] and also indicates that the plugin should be automatically started. | ||
| Line 74: | Line 75: | ||
The path entered here added to the path from the [[#Update the site information|site configuration]] must point directly to your pluings' HTML file. For example the JavaScript plugin has the <code>org.eclipse.orion.client.javascript/web/</code> path in its site configuration, making the full path to the plugin HTML file: <code>org.eclipse.orion.client.javascript/web/javascript/plugins/javascriptPlugin.html</code>. | The path entered here added to the path from the [[#Update the site information|site configuration]] must point directly to your pluings' HTML file. For example the JavaScript plugin has the <code>org.eclipse.orion.client.javascript/web/</code> path in its site configuration, making the full path to the plugin HTML file: <code>org.eclipse.orion.client.javascript/web/javascript/plugins/javascriptPlugin.html</code>. | ||
| − | = Update | + | = Update site information = |
= Update the build = | = Update the build = | ||
[[Category:Orion|How To]] | [[Category:Orion|How To]] | ||
Revision as of 14:33, 7 November 2013
Contents
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:
- 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.
- 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.
The new plug-in org.eclipse.orion.client.javascript will be used as an example.
Add the code to the client
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
-SNAPSHOTadded after the end. For example the JavaScript plugin has the version1.0.0.qualifierwhich would be entered as1.0.0-SNAPSHOTin 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.