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.
Orion/Documentation/Developer Guide/Plugging into the navigator
Contents
The Navigator page provides a view for users to browse and manipulate files in their workspace. The Navigator defines some services to allow plug-ins to contribute commands to this view.
The orion.navigate.command service is used to contribute commands that are relevant to a selected file or folder. When the service is executed, a file object or array of file objects is passed to the service's run method. The command can perform some operation on the provided files. If the command is simply linking to another page, a uriTemplate can be used to specify the link.
Service methods
Implementations of orion.navigate.command may define the following function:
- run(selection)
- Takes the navigator selection as an argument, and runs a command against the selected objects.
This method will only be called when the implementation does not define a uriTemplate property.
Service attributes
Implementations of orion.navigate.command may define the following attributes:
- image
- The URL of an icon to associate with the command
- name
- The command text show to the user
- id
- The command id
- forceSingleItem
- A boolean attribute specifying whether the command supports only a single selected item or multiple items
- uriTemplate
- Optional. A URI Template that defines a link to another page, using variables from the selected object's metadata or validation properties. If this property is specified, then the run service method will never be called.
- tooltip
- Tooltip text shown to the user when they hover on the command
- validationProperties
- Optional. An array of Validation Properties used to determine if the selected object should offer this command.
Example
Here is a sample plug-in that contributes a link to a Google search for the selected file's name:
var provider = new eclipse.PluginProvider({postInstallUrl:"/plugin/list.html"}); provider.registerServiceProvider("orion.navigate.command", {}, { image: "http://www.google.com/favicon.ico", name: "Google Search", id: "sample.commands.sample4", forceSingleItem: true, uriTemplate: "http://www.google.com/#q={Name}", tooltip: "Link to google search for this file name" }); provider.connect();
When this plug-in is installed, the user will see the google search command in the Navigator menu as follows:
For more examples of contributing Navigator commands see the sample commands plugin.
The orion.navigate.content service is used to contribute buttons that help the user to create new top level folders with autogenerated content. The service describes a folder name and a command that should be run to generate the content, including the parameters to pass to the command. If the content is to be generated by simply linking to another page, a uriTemplate can be used to specify the link instead of a command and folder.
Service methods
None. This service is purely declarative.
Service attributes
Implementations of orion.navigate.content may define the following attributes:
- name
- The text to show to the user in the create content button.
- id
- The extension point id.
- description
- The description shown next to the create content button which explains how the content is generated.
- uriTemplate
- Optional. A URI Template that defines a link to another page. If this property is specified, then the command property will be ignored.
- folder
- Optional. The name of the folder that should be created for the content. The user may override this name. If it is not specified, a default will be proposed for the user.
- command
- Optional. The id of a command that should be run to generate content into the folder.
- parameters
- Optional. Parameters that should be passed to the command that generates content.
Example
Here is a sample plug-in that uses the HTTP import command to unzip a zip file that is colocated with the Orion plugin into an Orion folder.
var provider = new orion.PluginProvider(); var temp = document.createElement('a'); temp.href = "testContent.zip"; provider.registerService("orion.navigate.content", null, { id: "orion.content.test", name: "Another Exemplary Sample Site", description: "Generate a sample site from Susan's test plugin.", folder: "Test New Content", command: "orion.importZipURL", parameters: [{name: "url", type: "url", label: "Extracted from:", defaultValue: temp.href}, {name: "unzip", type: "boolean", label: "Unzip:", defaultValue: true}] }); provider.connect();
When this plug-in is installed, the user will see the "Another Exemplary Sample Site" button appear in the new content section of the navigator.
The orion.navigate.openWith service is used to associate a registered editor (see orion.edit.editor) with a registered content type (see orion.core.contenttype). Once this association has been made, the editor will be presented as a choice in the "Open With" menu beside files of that content type.
By default, the Orion client UI provides an editor with ID orion.editor
, to be used for editing source code. You can refer to this editor ID when you want to associate a new content type with the Orion Editor.
Service methods
None. This service is purely declarative.
Service attributes
Implementations of orion.navigate.openWith must define the following attributes:
- editor
String
The ID of the editor we want to associate. This must match exactly the editor's ID as given in orion.edit.editor.- contentType
-
String[]
An array of one or more content type IDs that will be associated with the editor.
Example
Here is a sample plug-in that associates the Orion Editor with the "text/markdown"
content type. This example assumes that the "text/markdown"
type has been previously registered with the orion.core.contenttype service.
var provider = new eclipse.PluginProvider(); provider.registerServiceProvider("orion.navigate.openWith", {}, { id: "orion.editor", contentType: ["text/markdown"] }); provider.connect();
When this plug-in is installed, the user will see the Orion Editor as an available target in the Open With Navigator menu beside files of the Markdown content type:
orion.core.contenttype
The content type service tells Orion about a new kind of file. The content types contributed to this service don't have any direct effect on the Orion UI, but they can be referred to by other services that need to associate themselves with a particular kind of file. For an example, see orion.navigate.openWith.
The Orion client UI defines a bunch of content types by default: see webEditingPlugin.html
in the client UI code.
Service attributes
- contentTypes
- An Array containing one or more content types to register. Each element of the array defines a new content type, and must have this shape:
- id
- String The unique identifier of the content type. This is a simple hierarchical name and should start with a category like "text" or "image".
- name
- String The user-readable name of the content type.
- extension
- String[] Optional. Array of file extensions characterizing this content type. (Extensions are given without the leading "." character).
- filename
- String[] Optional. Array of filenames characterizing this content type. Use this when a type does not have a characteristic file extension, but rather a filename. (For example, "Makefile", "README", "passwd").
- extends
- String Optional. If this content type is a subtype of another, this gives the parent content type's ID.
- image
- String Optional. URL of an image to display beside files of this type (for example, in the Orion navigator).
Service methods
None. This service is purely declarative.
Example
This example code contributes contributes a new content type for Perl files. A Perl file extends from "text/plain"
and has the extension .pl
.
provider.registerServiceProvider("orion.core.contenttype", {}, { contentTypes: [{ id: "application/perl", name: "Perl", extension: ["pl"], "extends": "text/plain" }] }); provider.connect();
The example code below contributes a new content type for Ant build files. An Ant build file is a special kind of XML file that always has the name "build.xml".
provider.registerServiceProvider("orion.core.contenttype", {}, { contentTypes: [{ id: "text/ant", name: "Ant build file", filename: ["build.xml"], "extends": "application/xml" }] }); provider.connect();