# 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:

computeProposals(prefix, buffer, selection)
  When content assist is triggered, the editor calls this function to obtain suggestions from a content assist provider.
  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 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 content assist engine will discard any proposals that don't start with this prefix.
    buffer `String` The entire buffer being edited.
    selection `orion.textview.Selection` The current selection in the editor.

Returns an `Array` giving possible completions that may be inserted into the editor. Result elements must be either `String` objects with literal string completions, or proposal objects with the following properties:

  proposal `String` completion text that will be inserted in the editor if chosen. The prefix, if any, will be removed from this text automatically by the Orion code completion engine.
  description An optional `String` describing the completion. If provided, this text will be shown in the content assist popup. If not provided, the proposal will be shown instead.
  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 integer 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.

## 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'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.

    var provider = new eclipse.PluginProvider();
    provider.registerServiceProvider("orion.edit.contentAssist",
      {
         computeProposals: 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",
        contentType: ["text.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 eclipse.PluginProvider();
    provider.registerServiceProvider("orion.edit.contentAssist",
      {
        computeProposals: function(prefix, buffer, selection) {
          var proposals = [];
          if (prefix === 'a') {
            proposals.push({
              proposal: "a href=\"\"></a>",
              description: "<a></a> - HTML anchor element",
              escapePosition: selection.offset+7});
          }
          return proposals;
      },
      {
        name: "HTML content assist",
        contentType: ["text.html"]
      });
    provider.connect();