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

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.

Returns Proposal[].

The Proposal object

A Proposal object has the following properties:

description String Description text for this proposal. Will be shown in the content assist popup.
escapePosition Number Optional. Gives the offset, relative to the document, where the cursor should be placed after the proposal is inserted. If this value is not supplied, the cursor will be positioned at the end of the inserted text.
overwrite Boolean Optional, defaults to false. If true, this proposal's proposal will overwrite the prefix that was passed to computeProposals().
positions Object[] Optional. 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.
proposal String Completion text that will be inserted in the editor if chosen by the user. The text is inserted at the offset that was passed to computeProposals().
style String Optional. Gives 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).

Service attributes

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

name
String Name for the content assist provider.
contentType
String[] An array of Content Type IDs that this provider can provide content assist for. The provider's computeProposals 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, possibly parsing the file into an Abstract Syntax Tree (AST).