Orion/Documentation/Developer Guide/Plugging into the navigator

Overview of contributing services to the navigator

The file navigator is found on the Editor page. It provides a view for users to browse and manipulate files in their workspace. Several services allow plugins to contribute commands to this view.

orion.navigate.command

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:

id

String. The command id.

image

String. The URL of an icon to associate with the command.

name

String. The command text show to the user.

forceSingleItem

Boolean. Specifies whether the command supports only a single selected item (true) or multiple items (false).

uriTemplate

String. 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

String. Tooltip text shown to the user when they hover on the command

validationProperties

ValidationProperty[]. Optional. An array of Validation Properties used to determine if the selected object should offer this command.

showGlobally

Boolean. Optional, defaults to false. A boolean attribute specifying whether this command should be shown in file contexts other than the navigator. (For example, the editor toolbar is one such context. If a command specifies both showGlobally and forceSingleItem, it will be shown on the editor toolbar.)

Example

Here is a sample plug-in that contributes a link to a Google search for the selected file's name:

1.  var provider = new orion.PluginProvider({postInstallUrl:"/plugin/list.html"});
2.  provider.registerServiceProvider("orion.navigate.command", {}, {
3.    image: "http://www.google.com/favicon.ico",
4.    name: "Google Search",
5.    id: "sample.commands.sample4",
6.    forceSingleItem: true,
7.    uriTemplate: "http://www.google.com/#q={Name}",
8.    tooltip: "Link to google search for this file name"
9.  });
10.  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.

orion.navigate.openWith

The orion.navigate.openWith service is used to associate a registered editor with a registered content type. Once this association has been made, the editor will be presented as a choice in the actions menu (gear menu) beside files of that content type. (If it's the only available editor for that file, it will be used to generate the link when the file is clicked).

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/x-php" content type. This example assumes that the "text/x-php" type has been previously registered with the orion.core.contenttype service.

1.   var provider = new orion.PluginProvider();
2.   provider.registerServiceProvider("orion.navigate.openWith", {},
3.     {  id: "orion.editor",
4.        contentType: ["text/x-php"]
5.     });
6.   provider.connect();

When this plug-in is installed, the user will see the Orion Editor as an available target in the actions menu beside files of the PHP 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, including JavaScript, CSS, HTML, Markdown, and several others. See webEditingPlugin.js in the client UI code for a full list. (If you are contributing tools that deal with one of Orion's predefined content types, you must use the same content type ID rather than define your own, as file extensions can be registered by only a single content type.)

Service attributes

contentTypes

ContentType[]. An array of one or more content types to register. Each element of the array defines a new content type.

The ContentType object

A ContentType object has the following 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). Note that extensions are unique: if two content types both register against the same extension, one content type will be chosen arbitrarily over the other. Extensions may contain additional periods (ex: 'a.b.c') in which case the longest matching extension will be used ('foo.a.b' will match extension 'a.b' if both 'a.b' and 'b' are registered).

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"). A filename match will be chosen over a matching extension.

filenamePattern

String Optional. A valid regular expression pattern to test against the file name.

extends

String Optional. If this content type is a subtype of another, this gives the parent content type's ID. This content type will inherit the contributions that match any of its supertypes. For example, a content type with extends: "text/plain" would inherit all the commands that apply to text/plain.

image

String Optional. URL of an image to display beside files of this type (for example, in the Orion navigator). This field can contain a data URI.

imageClass

String Optional. CSS class name for an image to display beside files of this type (for example, in the Orion navigator). Providing a class name allows a variety of CSS techniques to be used to generate an image: for example, sprites, web fonts, etc. Multiple class names (separated by a space) can be provided within the imageClass string. The imageClass supersedes image if both are provided.

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.

1. provider.registerServiceProvider("orion.core.contenttype", {}, {
2.     contentTypes: [
3.         {
4.             id: "application/perl",
5.             name: "Perl",
6.             extension: ["pl"],
7.             "extends": "text/plain"
8.         }
9.     ]});
10. provider.connect();

The example code below contributes a new content type for Maven build files. A Maven build file is a special kind of XML file that always has the name "pom.xml".

1. provider.registerServiceProvider("orion.core.contenttype", {}, {
2.     contentTypes: [
3.         {
4.             id: "text/x-maven-pom",
5.             name: "Maven build file",
6.             filename: ["pom.xml"],
7.             "extends": "application/xml",
8.             imageClass: "orion-maven-sprite"
9.         }
10.     ]});
11. provider.connect();