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 editor
Contents
- 1 Overview of contributing services to the Orion editor
- 2 The Editor Context object
- 3 orion.core.astprovider
- 4 orion.edit.command
- 5 orion.edit.contentAssist
- 6 orion.edit.editor
- 7 orion.edit.highlighter
- 8 orion.edit.model
- 9 orion.edit.occurrences
- 10 orion.edit.outliner
- 11 orion.edit.validator
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.
The Editor Context object
Orion 4.0 introduces Object References, which enable two-way communication between a service provider and the host Orion page. An Object Reference exposes functions that a service provider can call to help it fulfill a service contract. Like everything in Orion's service framework, Object References work asynchronously: all functions return Promises and the caller must wait for them to fulfill to an actual value. An Object Reference is valid only during the lifetime of its parent service call. Once the provider has fulfilled the service call, any Object References created for that call are unregistered by the framework, and cannot be used thereafter.
Many of the service APIs documented on this page now provide a special Object Reference, called the Editor Context object, as the first parameter in their function signatures. The Editor Context object contains various functions to query the state of the Orion editor, and to cause side effects. For example, if a provider needs the text from the editor buffer to fulfill its service contract, it can invoke the Editor Context's getText()
method:
// Use text to fulfill the provider's service contract
});
Any plugin that uses Object References must load Orion's Deferred.js
in addition to the usual plugin.js
script. Failure to do this will cause runtime errors when the plugin attempts to use an Object Reference.
API versions
The older API signatures are labelled as "Orion 3.0" in the documentation. These are still supported, but date from Orion releases when Object References were not available. It is preferable to use the "Orion 4.0" version of an API whenever available, as these provide greater consistency, are somewhat more efficient, and can be more easily evolved in future releases without changing method signatures.
Editor Context methods
The Editor Context object provides the following methods:
- getAST(options)
- Resolves to
Object
. Returns an AST for the file being edited, if an AST provider is available. Orion ships with an Esprima AST provider for JavaScript files. Additional providers can be contributed by plugins.
- Resolves to
- getCaretOffset()
- Resolves to
Number
. Returns the offset of the editing caret.
- Resolves to
- getSelection()
- Resolves to
Selection
. Returns the editor's current selection.
- Resolves to
- getText(start?, end?)
- Resolves to
String
. Returns the text in the given range.
- Resolves to
- setCaretOffset(offset, show?)
- Resolves to
undefined
. Sets the caret offset. Ifshow
is true, the editor will scroll to the new caret position.
- Resolves to
- setSelection(selection)
- Resolves to
undefined
. Sets the editor's selection.
- Resolves to
- setText(text, start?, end?)
- Resolves to
undefined
. Sets the text in the given range.
- Resolves to
orion.core.astprovider
The orion.core.astprovider
service allows plugins to provide ASTs (Abstract Syntax Trees) for specific content types.
Service methods
Implementations of orion.core.astprovider
must define the following function:
- computeAST(astContext)
- astContext is an object that contains all of the information needed to compute the AST. The astContext object currently only contains the
text
argument that contains the entire source from the current editor context.
Service attributes
Implementations of orion.core.astprovider
may define the following attributes:
- contentType
Array
An array of Content Type IDs for which this command is valid.
Examples
The following example is how Orion uses the Esprima parser internally to provide ASTs for JavaScript:
- var provider = new orion.PluginProvider();
- provider.registerService('orion.core.astprovider',
- {
- computeAST: function(astContext) {
- var ast = esprima.parse(astContext.text, {
- loc: true,
- range: true,
- raw: true,
- tokens: true,
- comment: true,
- tolerant: true
- });
- if (ast.errors) {
- ast.errors = ast.errors.map(serialize.serializeError);
- }
- return ast;
- }
- }, {
- contentType: ['application/javascript']
- });
- provider.connect();
orion.edit.command
The orion.edit.command
service allows plugins to provide a command that operates on the editor. Typically, the command that takes some editor text as input, performs some operation or transformation on the text, and generates a new text value. The command can also optionally receive and return selection information for changing the editor selection. The transformation can happen directly, or indirectly through a delegated UI provided by the plugin.
Service methods (Orion 4.0)
The 4.0 version of the command API allows a command to take arbitrary action using the editorContext.
- execute(editorContext, options)
- editorContext
ObjectReference
The Editor Context object. - options
Object
- options.contentType
String
The Content Type ID of the file being edited. - options.input
String
Path and filename being edited.
- options.contentType
The execute()
method should return a Promise, which the provider is expected to resolve when it has finished performing the command action. The command action should be performed using the Editor Context object: for example, use editorContext.setText()
to change the editor text, or editorContext.setSelection()
to change the editor selection. The fulfillment value of the promise is ignored.
Note: Future versions of Orion will expose delegated UI functionality through the EditorContext object. This is currently not supported, due to Bug 419764.
Service methods (Orion 3.0)
- run(selectedText, text, selection, resource)
- selectedText
String
. The text that is currently selected in the editor. - text
String
. Provides the entire buffer being edited. - selection
orion.editor.Selection
The current selection in the editor. - resource
String
The full path and filename of the file being edited.
The return value of run()
is a CommandResult object.
The CommandResult object
A CommandResult object is either a simple String
which will replace the current editor selection, or an object
.
- The object must either have a
text
property or auriTemplate
property.- If it has a
text
property, then the text is a replacement string for the entire editor buffer. - If it has a
uriTemplate
property, then a delegated UI iframe will be opened on the specified URI.
- If it has a
- It may optionally have a
width
and/orheight
property that describes the desired size of the UI. Width and height are specified in CSS units, such as "100px" or "50em". The delegated UI must post a message back to the host window with an object that identifies itself as a delegatedUI and contains aresult
property that describes the new selection text or the replacement text object. (See example). - It may optionally have a
selection
object indicating the new selection value. - It may optionally have a
status
field giving status information to show in the notification area.
The Status object
A Status object has the following fields:
- Severity
String
. Allowed values are:"Warning"
,"Error"
. - Message
String
. The status message to display. May include hyperlinks, given in Markdown syntax.
Service attributes
Implementations of orion.edit.command
must define the following attributes:
- name
String
The command text to show to the user.- id
String
The id of the command contribution.- tooltip
String
Optional. A tooltip describing the command.
- img
String
Optional. The URL of an icon to associate with the command. The icon may not appear in all situations. For example, the main toolbar may not show the icon, but a menu item might show the icon.- key
Array
Optional. A key binding for the command. The structure of this array matches the arguments of theorion.textview.KeyBinding
constructor. See its entry in the Client API reference for details.- validationProperties
Array
Optional. An array Validation Properties that must match the editor's file in order for the command to appear.- contentType
Array
Optional. An array of Content Type IDs for which this command is valid.
Examples
The following examples start with the simplest editor command and then add more complexity.
Replacing the selection
This example converts the selected text to upper case. 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",
- id : "uppercase.example"
- img : "/images/gear.gif",
- key : [ "u", true ]
- });
- provider.connect();
Replacing the editor contents
This example 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. A content type is used so that this command is only available for javascript files.
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}};
}
Delegating a UI before manipulating the editor
Here is an example of a delegated UI run function that computes a URL for the delegated UI based on the file name of the edited file. In this example, the function returns a complex object with a uriTemplate
field and width
and height
properties. The UI that is opened will be responsible for posting a message back to the editor with a result object that contains either a String for the selected text or a complex object with replacement content.
- id: "delegatedUI.example",
- run : function(selectedText, text, selection, fileName) {
- return {uriTemplate: "http://com.example/myDelegatedUI#" + fileName, width: "600px", height: "400px"};
- }
The delegated UI would post a message identifying itself and including a result. The message must include a pageService
property of "orion.page.delegatedUI", a source
that matches the orion.edit.command service id, and either a result
or a cancelled
property. The following examples illustrate the different ways the result could be returned.
- /* a message containing replacement selected text */
- window.parent.postMessage(JSON.stringify({
- pageService: "orion.page.delegatedUI",
- source: "delegatedUI.example",
- result: replacementSelection
- }), "*");
- /* a message containing new content for the editor */
- window.parent.postMessage(JSON.stringify({
- pageService: "orion.page.delegatedUI",
- source: "delegatedUI.example",
- result: JSON.stringify({text: replacementText})
- }), "*");
- /* a message signifying user cancellation of the delegated UI */
- window.parent.postMessage(JSON.stringify({
- pageService: "orion.page.delegatedUI",
- source: "delegatedUI.example",
- cancelled: true
- }), "*");
Google Picker example
The Google Picker is a fully functioning example of a delegated UI in an editor command. It opens a Google Picker allowing the user to pick a resource, and then inserts a link to that resource into the editor text. To install the plug-in, open this link. The code is available here.
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 (Orion 4.0)
- computeContentAssist(editorContext, options)
- editorContext
ObjectReference
The Editor Context object. - options
Object
- options.delimiter
String
The line delimiter being used in the editor (CRLF, LF, etc.) - options.indentation
String
The leading whitespace at the start of the line. - options.line
String
The text of the line. - options.offset
Number
The offset at which content assist is being requested. Relative to the document. - options.prefix
String
The substring extending from the first non-word character preceding the editing caret up to the editing caret. This may give a clue about what the user was in the process of typing. It can be used to narrow down the results to be returned. The prefix is just a guess; it is not appropriate for all types of document, depending on their syntax rules. - options.selection
orion.editor.Selection
The current selection in the editor. - options.tab
String
The tab character being used in the editor. Typical values are a Tab character, or a sequence of four spaces.
- options.delimiter
Service methods (Orion 3.0)
- computeProposals(buffer, offset, context)
- When content assist is triggered, the editor calls this function to obtain suggestions from a content assist provider.
- buffer
String
The entire buffer being edited. - offset
Number
Offset in the text buffer at which content assist is being invoked. - context
Object
Additional contextual information about the content assist invocation. This object has the following properties:- context.line
String
Text of the entire line that the editing caret is on. - context.prefix
String
The substring extending from the first non-word character preceding the editing caret up 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. The prefix is just a guess; it is not appropriate for all types of document, depending on their syntax rules. - selection
orion.editor.Selection
The current selection in the editor.
- context.line
- buffer
Returns an Array
giving possible completions that may be inserted into the editor. Result elements must be "proposal" objects having the following properties:
- proposal
String
completion text that will be inserted in the editor if chosen. The text is inserted at the offset. - description A
String
describing the completion. This text will be shown in the content assist popup. - positions An optional
Array
of positions within the completion proposal that require user input. Supplying this property will cause the editor to enter linked mode, and the user can use the Tab key to iterate through the regions of the proposal that require user input. For example if the completion is a function, the positions could indicate the function arguments that need to be supplied. Entries in this position array must be objects with two integer properties: offset, and length describing the regions requiring user input. - escapePosition An optional
Number
indicating the offset the cursor should have in the document after the completion is inserted. If this value is not supplied, the cursor will be positioned at the end of the inserted text. - style A String giving styling information for the proposal. The available styles are:
"default"
(no styling, also used if this property is not present),"emphasis"
(proposal displayed in bold),"noemphasis"
(proposal is greyed out with a colored background),"hr"
(proposal displayed as a <hr/> and is not selectable by up and down arrows).
Alternatively, a Deferred may be returned, which allows the suggestions to be computed asynchronously.
Service attributes
Implementations of orion.edit.contentAssist
must define the following attributes:
- name
String
Name for the content assist provider.- contentType
Array
An array of Content Type IDs that this provider can provide content assist for. The provider'scomputeProposals
function will be called only for files having one of these content types.
Examples
The example below provides content assist suggestions for files whose name ends in .js
. It offers JavaScript keywords as suggestions, by checking them against the prefix provided by the content assist engine.
- var provider = new orion.PluginProvider();
- provider.registerServiceProvider("orion.edit.contentAssist",
- {
- computeProposals: function(buffer, offset, context) {
- var keywords = [ "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" ];
- var proposals = [];
- for (var i=0; i < keywords.length; i++) {
- var keyword = keywords[i];
- if (keyword.indexOf(context.prefix) === 0) {
- proposals.push({
- proposal: keyword.substring(context.prefix.length),
- description: keyword
- });
- }
- }
- return proposals;
- }
- },
- {
- name: "JavaScript content assist",
- contentType: ["application/javascript"]
- });
- provider.connect();
The example below will provide completion on the character 'a' that will insert an HTML anchor element. After completion the cursor will be positioned within the href
attribute.
- var provider = new orion.PluginProvider();
- provider.registerServiceProvider('orion.edit.contentAssist',
- {
- computeProposals: function(buffer, offset, context) {
- var proposals = [];
- if (context.prefix === 'a') {
- proposals.push({
- proposal: ' href=""></a>',
- description: '<a></a> - HTML anchor element',
- escapePosition: offset+7});
- }
- return proposals;
- },
- {
- name: 'HTML content assist',
- contentType: ['text/html']
- });
- provider.connect();
Here is an identical example to the HTML provider, but written against the Orion 4.0 API.
- // Note that orion/Deferred is an implied dependency of orion/plugin here, because we are using an object reference.
- define(["orion/plugin"], function(PluginProvider) {
- var provider = new PluginProvider();
- provider.registerServiceProvider('orion.edit.contentAssist',
- {
- computeContentAssist: function(editorContext, options) {
- var proposals = [];
- if (options.prefix === 'a') {
- proposals.push({
- proposal: ' href=""></a>',
- description: '<a></a> - HTML anchor element',
- escapePosition: offset+7});
- }
- return proposals;
- },
- {
- name: 'HTML content assist',
- contentType: ['text/html']
- });
- provider.connect();
- });
More advanced content assist providers will generally use the buffer text or the AST provided in the editorContext object.
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 combination with two other services, which allow new file types to be defined and associated with editors. See:
- orion.core.contenttype: Registers a new content type for files.
- orion.navigate.openWith: Associates a content type (registered via
orion.core.contenttype
) to an editor (registered viaorion.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. - uriTemplate
-
String
Gives a URI template for constructing a URL that can be followed to drive this editor to a particular file. The parameterLocation
is substituted with the URL of the file being edited. The template is specified using the URI Template syntax. - orionTemplate
-
String
Optional. Gives an Orion template for constructing the editor URL. This serves the same purpose as the uriTemplate field. However an Orion template allows a more human-readable parameter encoding scheme than a URI Template. If both fields are provided, the orionTemplate takes priority over the uriTemplate.
NOTE: Orion templates are not yet standardized.
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 portion of the URL. Presumably myGreatEditor.php would read the string and open the file. Authentication is beyond the scope of this example.
- var provider = new eclipse.PluginProvider();
- provider.registerServiceProvider("orion.edit.editor", {},
- { id: "example.mygreateditor",
- name: "My Great Editor",
- uriTemplate: "http://mysite.com/myGreatEditor.php?fileToEdit={Location}"
- });
The code below shows a complete example of how to use the orion.editor
, orion.core.contenttype
, and orion.navigate.openWith
services in conjunction to declare a new editor, declare new file types, and associate them together. The example is adapted from Orion's own source code.
- // Declare an editor
- provider.registerServiceProvider("orion.edit.editor", {}, {
- id: "orion.editor",
- name: "Orion Editor",
- uriTemplate: "../edit/edit.html#{Location,params*}",
- orionTemplate: "../edit/edit.html#{,Location,params*}"});
- // Declare content types
- provider.registerServiceProvider("orion.core.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 registerServiceProvider() calls is not important.
orion.edit.highlighter
The orion.edit.highlighter
service contributes syntax highlighting rules to the editor. A highlighter service may provide highlighting in one of two ways:
- By passing a grammar, which is a declarative description of a language's syntax. The grammar tells the Orion editor how to recognize and style language constructs in a file.
- By writing a highlighter, which allows highlighting information to be calculated asynchronously by the provider itself and sent to the Orion editor for display.
The service also provides a list of content types. When the editor opens a file of a registered content type, the provider is invoked (using one of the two methods described above) to obtain the styling.
NOTE: The "highlighter" API is experimental and subject to change in future versions.
Service methods
Implementations of orion.edit.highlighter
whose type attribute is "highlighter", must define the following method:
- setContentType(contentTypeId)
- contentTypeId
String
The Content Type ID of the file that is being edited.
Orion invokes this method to inform the provider what kind of file it must provide highlighting for. This allows the provider that to register itself with several content types, but implement different logic for each type.
When this provider's type is "grammar", no service methods are defined: a grammar provider is purely declarative.
Service attributes
Implementations of orion.edit.highlighter
must define the following attributes:
- type
String
What kind of highlight provider is being registered. Allowed values are"grammar"
and"highlighter"
. Future versions may support more.- contentType
Array
An array of Content Type IDs that this provider will be used for.- grammar
Object
Optional. When the type of this provider is "grammar", this attribute holds an object giving the grammar to be used to assign style classes. This object is a JavaScript equivalent of the format described here.
Service events
When the type of the provider is "highlighter", the provider must independently listen to changes in the Orion text editor by registering with the orion.edit.model
service, and calculate the necessary highlighting information in response to the changes. Whenever highlighting information is available, the provider must dispatch an event of type "orion.edit.highlighter.styleReady"
containing the styles. The event will be used by the Orion editor to apply styles to the file being displayed.
- orion.edit.highlighter.styleReady
- This event is documented in the Orion Client API reference as
orion.editor.StyleReadyEvent
. Consult its entry there for detailed information.
When the type of the provider is "grammar", the provider dispatches no service events.
Example of a 'grammar' provider
- var provider = new eclipse.PluginProvider();
- provider.registerServiceProvider("orion.edit.highlighter",
- {
- // "grammar" provider is purely declarative. No service methods.
- }, {
- type : "grammar",
- contentType: ["text/html"],
- 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 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.)
Example of a 'highlighter' provider
See the source code of the orion-codemirror plugin, particularly these lines.
orion.edit.model
An orion.edit.model
service provides listeners on changes made to the orion.textview.TextView
that powers the Orion editor.
NOTE: This section is experimental and may change in future versions.
Service methods
An implementation of orion.edit.model
may define zero or more functions depending on what event types it gives in its types attribute. For every event type in types, the function with the name "on" + eventType
will be invoked. For example, a "ModelChanged" event type causes the the provider's "onModelChanged()" function to be invoked.
The functions are always invoked with a single parameter, event
, containing the event data that was dispatched by the TextView. The current list of supported onXXXX methods is as follows:
- onContextMenu(event)
- onDragStart(event)
- onDragEnd(event)
- onDragEnter(event)
- onDragOver(event)
- onDragLeave(event)
- onDragStop(event)
- onModelChanging(event)
- onModelChanged(event)
- onModify(event)
- onMouseDown(event)
- onMouseUp(event)
- onMouseMove(event)
- onMouseOver(event)
- onMouseOut(event)
- onScroll(event)
- onVerify(event)
- onFocus(event)
- onBlur(event)
Service attributes
Implementations of orion.edit.model
must define the following attributes:
- types
-
Array
An array of TextView event types that this provider is interested in. When an event of one of these types is dispatched by the TextView, this provider's corresponding function will be invoked. For example, a provider with "ModelChanged" in its types array will have its onModelChanged function invoked whenever the TextView dispatches aModelChanged
event. - contentType
-
Array
An array of Content Type IDs that this provider is interested in listening to changes for. The provider will only be notified of events that occur when a file matching one of these content types is being edited.
Example
See the source code of the orion-codemirror plugin.
orion.edit.occurrences
The orion.edit.occurrences
service allows plugins to compute identifier occurrences for specific content types.
Service methods
Implementations of orion.edit.occurrences
must define the following function:
- computeOccurrences(editorContext, context)
- editorContext is an
orion.edit.EditorContext
object that contains all of the information about the current editor. - context is an object that contains the current selection in the editor to find occurrences for.
Service attributes
Implementations of orion.edit.occurrences
may define the following attributes:
- contentType
Array
An array of Content Type IDs for which this occurrence computer is valid.- pattern
String
A string to create a regular expression to determine if this occurrence service applies to the current context. This attribute has been
deprecated in favor of contentType
.
Examples
The following example is how Orion plugs in occurrence support for JavaScript:
- var provider = new orion.PluginProvider();
- provider.registerService('orion.edit.occurrences',
- {
- computeOccurrences: function(editorContext, context) {
- return [];
- }
- {
- contentType: ["application/javascript"]
- });
- provider.connect();
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 (Orion 4.0)
A provider implements the computeOutline
method, whose signature is as follows:
- computeOutline(editorContext, options)
- editorContext
ObjectReference
The Editor Context object. - options
Object
- options.contentType
String
The Content Type ID of the file being edited.
- options.contentType
The return value (or fulfillment value) is an Array of top-level OutlineElement objects, which will be displayed in the outline pane.
Service methods (Orion 3.0)
A provider implements the getOutline
method, whose 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 of top-level OutlineElement objects, which will be displayed in the outline pane.
The OutlineElement object
Each OutlineElement has these 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 OutlineElements 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 provided for finer-grained control. (Consult the
orion.util.hashFromPosition()
documentation in the Client API reference for details about these parameters.)
- The optional properties column, start, end, text may be provided for finer-grained control. (Consult the
- 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:
- contentType
Array
An array of Content Type IDs giving the types of files that 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.)
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;
}
}, {
contentType: ["text/plain"],
name: "Headings",
id: "orion.outliner.example.headings"
});
provider.connect();
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 where problems are. 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 the document where the problem occurs.
Service methods (Orion 4.0)
- computeProblems(editorContext, options)
- editorContext
ObjectReference
The Editor Context object. - options
Object
- options.contentType
String
The Content Type ID of the file being edited. - options.title
String
The path and filename of the file being edited.
- options.contentType
Returns (or fulfills to) an Object
giving the validation result. The returned object must have a problems
property giving an Array of problems found in the file.
Service methods (Orion 3.0)
- 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 a problems
property whose value is an array giving the problems found in the file.
The Problem object
A Problem object has the following properties:
- description
String
A description of the problem. - 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.)
A problem will have additional properties that give its location within the file. The location can be specified using line+column, or using offsets.
For a line-based problem, you provide a line number and columns:
- line
Number
The line number where the problem was found. (Line numbers begin counting from 1.) - start
Number
The column within the line where the problem begins. (Columns begin counting from 1.) - end
Number
Optional The column within the line where the problems ends. (If omitted,start+1
is assumed.)
For a document-based problem, you provide character offsets:
- start
Number
The offset at which the problem begins. (0=first character in the document.) - end
Number
Optional The offset at which the problem ends. (If omitted,start+1
is assumed.)
A document-based problem can span several lines.
Service attributes
Implementations of orion.edit.validator
must define the following attributes:
- contentType
-
Array
An array of Content Type IDs giving the types of files that this validator is capable of validating.
Examples
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({
description: "Mixed spaces and tabs",
line: i + 1,
start: match.index + 1,
end: match.index + match[0].length + 1,
severity: "warning" });
}
}
var result = { problems: problems };
return result;
}
},
{
contentType: ["application/javascript"]
});
provider.connect();
This example will validate JavaScript 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.