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"
m |
|||
Line 1: | Line 1: | ||
− | This how-to | + | = Introduction = |
+ | This how-to deals with 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 [[Orion/Documentation/Developer_Guide/Simple_plugin_example | Simple Plug-in Example]]. | ||
− | The remainder of this how-to assumes | + | The remainder of this how-to assumes a few things: |
− | #You have already created a | + | #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 <code>org.eclipse.orion.client.javascript</code> plug-in will be referenced. |
#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. | ||
− | + | = 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 <code>org.eclipse.orion.client.ui/web/plugins/</code> folder, [[#Update the defaults|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 <code>org.eclipse.orion.client/bundles/</code> folder. | ||
− | + | This how-to assumes you want to create a separate bundle and have placed your plug-in code in the <code>org.eclipse.orion.client/bundles/</code> folder. For example the JavaScript plug-in is found in the <code>org.eclipse.orion.client/bundles/org.eclipse.orion.client.javascript/</code> folder. | |
− | + | = Configure build.properties = | |
+ | |||
+ | The <code>build.properties</code> file must be created / edited to tell Orion what you would like to be built. | ||
The most common cases will have two entries: | The most common cases will have two entries: | ||
Line 18: | Line 24: | ||
*'''src.includes''' - what should be included in the source build | *'''src.includes''' - what should be included in the source build | ||
− | The JavaScript | + | The JavaScript plug-in, for example, has the following entries: |
<pre> | <pre> | ||
bin.includes = META-INF/,\ | bin.includes = META-INF/,\ | ||
Line 27: | Line 33: | ||
</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 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 <code>pom.xml</code> | + | Since Orion is moving towards a completely Tycho / Maven-based build, your plug-in will also require a <code>pom.xml</code> file 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 | + | First we add some information about our plug-in: |
*'''groupId''' - this will be have the value <code>org.eclipse.orion</code> | *'''groupId''' - this will be have the value <code>org.eclipse.orion</code> | ||
− | *'''artifactId''' - this is the identifier of your | + | *'''artifactId''' - this is the identifier of your plug-in from its MANIFEST.MF file, for example <code>org.eclipse.orion.client.javascript</code> |
− | *'''version''' - this is the version of your | + | *'''version''' - this is the version of your plug-in from its MANIFEST.MF file with <code>-SNAPSHOT</code> added after the end. For example the JavaScript plug-in has the version <code>1.0.0.qualifier</code> which would be entered as <code>1.0.0-SNAPSHOT</code> in the POM file. |
− | *'''packaging''' - this is how the | + | *'''packaging''' - this is how the plug-in should be packaged, the value is typically <code>eclipse-plugin</code> |
− | Secondly, we | + | Secondly, we add some information about the parent: |
*'''groupId''' - this is the value <code>org.eclipse.orion</code> | *'''groupId''' - this is the value <code>org.eclipse.orion</code> | ||
*'''artifactId''' - this is the client parent identifier <code>org.eclipse.orion.client.parent</code> | *'''artifactId''' - this is the client parent identifier <code>org.eclipse.orion.client.parent</code> | ||
Line 45: | Line 51: | ||
*'''relativePath''' - this is the path relative to the parent, which is <code>../..</code> | *'''relativePath''' - this is the path relative to the parent, which is <code>../..</code> | ||
− | As an example, the complete POM.xml for the JavaScript | + | As an example, the complete POM.xml for the JavaScript plug-in looks like: |
<pre> | <pre> | ||
<project xmlns="http://maven.apache.org/POM/4.0.0" | <project xmlns="http://maven.apache.org/POM/4.0.0" | ||
Line 66: | Line 72: | ||
</pre> | </pre> | ||
− | + | = Update the defaults = | |
− | To have your | + | To have your plug-in 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 will want to 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 | + | The entry is based off the root of where your plug-in provides its packages (more on this in [[#Update the site information|update the site information]] section) and specifies if the plug-in should be started automatically. For example, the JavaScript plug-in adds the entry: <code>"javascript/plugins/javascriptPlugin.html":true</code>. This entry points to the HTML file for the plug-in which is based off the root supplied in the [[#Update the site information|site configuration]] and also indicates that the plugin should be automatically started. |
− | The path entered here | + | The path entered here appended to the path from the [[#Update the site information|site configuration]] must point directly to your plug-ins' 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 the site information = | |
− | + | = Update the build = | |
− | [[Category:Orion | + | [[Category:Orion|How To]] |
Revision as of 14:44, 7 November 2013
Contents
Introduction
This how-to deals with 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
org.eclipse.orion.client.javascript
plug-in will be referenced. - 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
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 version1.0.0.qualifier
which would be entered as1.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 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
.