Orion/Documentation/Developer Guide/Plugging into the editor

Overview of contributing services to the Orion editor

The built Orion editor defines a number of services for customizing its appearance and behavior. These services will typically be defined by a plug-in providing editing functionality for different programming languages or file extensions. This section will outline the services that are available for editor customization.

orion.edit.command

The orion.edit.command service is the simplest kind of editor extension. A command service simply provides a function that takes some text as input, performs some operation or transformation on the text, and returns a new text value. The command can also optionally receive and return selection information for changing the editor selection.

Service methods

Implementations of orion.edit.command must define the following function:

run(selectedText, text, selection)

selectedText is a string containing the text that is currently selected in the editor. The text argument provides the entire editor buffer. The selection argument is a selection object with start and end fields.

Service attributes

Implementations of orion.edit.command may define the following attributes:

img

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

name

String The command text show to the user.

key

Array An optional key binding for the command. The structure of this array matches the arguments of the orion.textview.KeyBinding constructor. See its entry in the Client API reference for details.

Examples

The following simple example just converts the selected text to upper case. In this example the function return value is a simple string, so this is interpreted by the editor as replacement for the original editor selection. In the service properties, we see the command provides a key binding of Ctrl+U (or Cmd+U on Mac).

 var provider = new eclipse.PluginProvider();
 provider.registerServiceProvider("orion.edit.command", {
   run : function(text) {
     return text.toUpperCase();
   }
 }, {
   name : "UPPERCASE",
   img : "/images/gear.gif",
   key : [ "u", true ]
 });
 provider.connect();

Here is an example of a slightly more complex run function that takes the selection and wraps it in C-style block comments. In this example the function returns a complex object with both text and selection fields. These are interpreted by the editor as the new editor buffer contents, and the new editor selection.

 run : function(selectedText, text, selection) {
   return {text: text.substring(0,selection.start) + "/*" + 
     text.substring(selection.start,selection.end) + "*/" + 
     text.substring(selection.end),
     selection: {start:selection.start,end:selection.end+4}};
 }

orion.edit.contentAssist

The orion.edit.contentAssist service contributes content assist providers to the editor. A content assist provider produces suggestions for text that may be inserted into the editor at a given point. Providers are invoked when the user triggers the "content assist" action by pressing Ctrl+Space in the editor.

Service methods

Implementations of orion.edit.contentAssist must define the following function:

getKeywords(prefix, buffer, selection)

When content assist is triggered, the editor calls this function to obtain suggestions from a content assist provider.
Returns Array giving possible strings that may be inserted into the editor.
Alternatively, a Dojo promise may be returned, which allows the suggestions to be computed asynchronously.

prefix String The substring extending from the first non-word character preceding the editing caret to the editing caret. This may give a clue about what the user intended to type, and can be used to narrow down the results to be returned.

buffer String The entire buffer being edited.

selection orion.textview.Selection The current selection in the editor.

Service attributes

Implementations of orion.edit.contentAssist must define the following attributes:

name

String Name for the content assist provider.

pattern

String A regular expression pattern matching filenames that this provider can provide content assist for. The provider's getKeywords function will be called only for files that match this pattern.

Examples

var provider = new eclipse.PluginProvider();
provider.registerServiceProvider("orion.edit.contentAssist",
  {
     getKeywords: function(prefix, buffer, selection) {
       return [ "break", "case", "catch", "continue", "debugger", "default", "delete", "do", "else",
                "finally", "for", "function", "if", "in", "instanceof", "new", "return", "switch", "this",
                "throw", "try", "typeof", "var", "void", "while", "with" ];
     }
  },
  {
    name: "JavaScript content assist",
    pattern: "\\.js$"
  });
provider.connect();

The above example provides content assist suggestions for files whose name ends in .js. It offers JavaScript keywords as suggestions.

orion.edit.editor

This service declares a new editor. By default, the Orion client UI declares a single editor with id "orion.editor" which is used to edit source code. Using this service, you can declare entirely new editors (for example, you could register an editor that provided a paint interface for drawing images).

Contributions to this service do not directly affect the Orion UI. Instead, this service is typically used in conjunction with two other services, which allow new file types to be defined and associated with editors. See:

• orion.file.contenttype: Registers a new content type for files.
• orion.navigate.openWith: Associates a content type registered via orion.file.contenttype with an editor registered via orion.edit.editor.

Service methods

None. This service is purely declarative.

Service attributes

id

String The unique identifier of this editor.

name

String The user-readable name of this editor.

href

String Gives a template for constructing a URL that can be followed to drive this editor to a particular file. The variable ${Location} is substituted with the URL of the file being edited.

Examples

This example code declares an editor called "My Great Editor". When My Great Editor is used to edit a file in Orion, the user will be pointed to a URL containing the location of the file they want to edit as "fileToEdit" in the query parameters.

 var provider = new eclipse.PluginProvider();
 provider.registerServiceProvider("orion.edit.editor", {}, 
   { id: "example.mygreateditor",
     name: "My Great Editor",
     href: "http://mysite.com/myGreatEditor.php?fileToEdit=${Location}"
   });

The code below shows a complete example of how to use the orion.editor, orion.file.contenttype, and orion.navigate.openWith services in conjunction to declare a new editor, declare new file types, and associate them together.

 // Declare an editor
 provider.registerServiceProvider("orion.edit.editor", {}, {
   id: "orion.editor",
   name: "Orion Editor",
   href: "../edit/edit.html#${Location}"});

 // Declare content types
 provider.registerServiceProvider("orion.file.contenttype", {}, {
   contentTypes:
     [{ id: "text.plain",
       name: "Text",
       extension: ["txt"]
     },
     {  id: "text.html",
       "extends": "text.plain",
       name: "HTML",
       extension: ["html", "htm"]
     }]
   });

 // Associate editor with content types
 provider.registerServiceProvider("orion.navigate.openWith", {}, {
     editor: "orion.editor",
     contentType: ["text.plain", "text.html"]});

 provider.connect();

Note that the order of these provider.registerServiceProvider() calls is not important.

orion.edit.highlighter

The orion.edit.highlighter service contributes syntax highlighting rules to the editor. A highlighter service provides a grammar, which is a declarative description of the structure of a language and what CSS classes the different structural pieces correspond to. The service also provides a list of file extensions. When the editor opens a file of a registered extension type, the grammar is applied to the file to obtain the styling.

Service methods

None.

Service attributes

Implementations of orion.edit.highlighter must define the following attributes:

type

String What kind of highlight provider is being registered. For now this should always be "grammar", although future versions may support more.

fileTypes

Array An array of file extensions that this provider will be used for.

grammar

Object An object giving the grammar to be used to assign style classes. This object is expected to be a JavaScript equivalent of the format described here.

Examples

var provider = new eclipse.PluginProvider();
provider.registerServiceProvider("orion.edit.highlighter",
  {
  }, {
    type : "grammar",
    fileTypes : ["html", "htm"],
    grammar: {
      patterns: [
          {  begin: "<!--", 
             end: "-->",
             captures: { "0": "punctuation.definition.comment.html" },
             contentName: "comment.block.html"
          }
      ]
    }
  });
provider.connect();

The above example provides a grammar to be used for .html and .htm files. It will assign the CSS class punctuation-definition-comment-html to the <!-- and --> delimiters, and assign the CSS class comment-block-html to the text inside the delimiters. Consult this reference for a full description of the grammar format.

(Note that some aspects of the grammar format are not supported. See orion.editor.TextMateStyler in the Client API reference for a detailed explanation.)

orion.edit.validator

An orion.edit.validator service provides a function that can check the contents of a file and return a data structure indicating which lines (if any) have problems. The result of this service is used by the Orion UI to create annotations in the ruler beside each problematic line, and also to underline the specific portion of a line where the problem occurs.

Service methods

Implementations of orion.edit.validator must define the following function:

checkSyntax(title, contents)

title String The path and filename of the file being edited.

contents String The contents of the file being edited.

Returns an Object giving the validation result. The returned object must have an problems property whose value is an array giving the problems found in the file. Each problem object must have the properties:

description String A description of the problem.

line Number Gives the line number where the problem was found. (Line numbers begin counting from 1.)

start Number Gives the column within the line where the problem begins.

end Number Optional Gives the column within the line where the problems ends. (If omitted, start+1 is assumed.)

severity String Optional Gives the severity of this problem. The severity affects how the problem is displayed in the Orion UI. Allowed values are "warning" and "error". (If omitted, "error" is assumed.)

Service attributes

Implementations of orion.edit.validator must define the following attributes:

pattern

String A regular expression pattern matching the filenames that this validator is capable of validating.

Examples

var provider = new eclipse.PluginProvider();
var serviceProvider = provider.registerServiceProvider("orion.edit.validator",
  {
     checkSyntax: function(title, contents) {
       var problems = [];
       var lines = contents.split(/\r?\n/);
       for (var i=0; i < lines.length; i++) {
         var line = lines[i];
         var match = /\t \t| \t /.exec(line);
         if (match) {
           problems.push({
             reason: "Mixed spaces and tabs",
             line: i + 1,
             character: match.index + 1,
             end: match.index + match[0].length + 1,
             severity: "warning" });
         }
       }
       var result = { problems: problems };
       return result;
     }
  },
  {
     pattern: "\\.(txt|js)$"
  });
provider.connect();

This example will validate .txt and .js files. It finds lines containing a sequence of space-tab-space or tab-space-tab and produces a warning on every such line. Note that +1 is necessary because column and line indices in the Orion UI are numbered from 1, not 0.

orion.edit.outliner

An orion.edit.outliner service provides an overview of a file being edited. The overview is given as a tree, which the Orion UI renders in the left-hand pane alongside the file you are editing. Items in the tree can be links that take you to the appropriate position in the file, or to another URL entirely.

Service methods

Implementations of orion.edit.outliner must have a getOutline method that will be called to generate the outline for a resource. Its signature is as follows:

getOutline(contents, title)

contents String The contents of the file being edited.

title String The path and filename of the file being edited.

Returns an Array giving the top-level elements to be shown in the outline. Each element of the returned array must have the properties:

label String Text to be shown in the UI for this element.

className String Optional A space-separated list of CSS class names to be applied to this element in the UI.

children Array Optional Array of child elements of this element. Children may be nested to an arbitrary depth.

line Number Optional The line number within the file to use as the link for this element in the UI. Line numbers begin counting from 1.

The optional properties column, start, end, text may be used for finer-grained control. (Consult the orion.util.hashFromPosition() documentation in the Client API reference for details about these parameters.)

href String Optional When line is omitted, the href property provides a URL to use as the link.

Service attributes

Implementations of orion.edit.outliner must define the following attributes:

pattern

String A regex pattern matching the names of files this outliner can provide an outline for.

id

String A unique identifier for this outline provider.

name

String A user-readable name for this outline provider.

Examples

This example shows an outline provider that runs on .txt files. It finds Mediawiki-style =Section Headings= and generates a flat outline from them. (A more elaborate implementation might also find subsections and include them as children of the top-level sections.)

var provider = new eclipse.PluginProvider();
provider.registerServiceProvider("orion.edit.outliner", {
  getOutline: function(contents, title) {
    var outline = [];
    var lines = contents.split(/\r?\n/);
    for (var i=0; i < lines.length; i++) {
      var line = lines[i];
      var match = /^=\s*(.+?)\s*=$/.exec(line);
      if (match) {
        outline.push({
           label: match[1],
           line: i+1  // lines are numbered from 1
        });
      }
    }
    return outline;
  }
}, {
  pattern: "\.txt$",
  name: "Headings",
  id: "orion.outliner.example.headings"
});
provider.connect();