View source for Orion/JavaScript/API

{{warning|Potential API Changes|This page describes a new, consumable API for the JavaScript language tools that is still in development. As new features, frameworks and protocols are added or removed, the shape of the API may change in a compatible way over time.}}

= Experimental API =

In Orion 12.0 we are developing an API that will allow the JavaScript language tools to be built and directly consumed outside of Orion - say for example, as a plugin in another IDE.

To begin using the API, you first have to build the library that provides the API (as it is not part of the normal Orion client build).

On the [[Orion/JavaScript/Build]] we have step-by-step instructions on building the API bundle.

== API Dependencies ==

Once you have [[Orion/JavaScript/Build|built the bundle]], you can consume it by requiring it (or AMD define it, etc) and instantiating
the JavaScript constructor.

For example, to require it in an AMD environment, you might do:

<source lang="javascript">
define(function (require) {
  var orionJSLib = require("./lib/orionJavaScript");
  var orionJS = new orionJSLib(new scriptResolver());
});
</source>

and then call the API functions on <code>orionJS</code> as needed. When creating an instance of the API, you'll notice that you have to provide a shim to tell the tools how to find / resolve files. In the above example, we have <code>new scriptResolver()</code> to denote where the shim is instantiated / used. There is much more detail on the shape of the resolver object in the [[#The Script Resolver|script resolver section]].

=== The Script Resolver ===

When creating a new instance of the tools, you have to provide a way (shim) for the tools to look up and resolve files. This is what we term the ''scriptResolver''.

Currently, the resolver '''must''' have the following shape:
;ScriptResolver.prototype.getFileClient()
: Returns [[#The File Client|an object]] that provides search and reading functions to the file system / server
;ScriptResolver.prototype.getWorkspaceFile(logicalName, options)
:Returns a [[#The File Object|file object]] for the given logical name and [[#Get Workspace File Options|options]]
;ScriptResolver.prototype.resolveRelativeFiles(path, files, metadata)
:Resolves the list of possible [[#The File Object|files]] against the base path, optionally using the given metadata (more on the [[#The Metadata Object|metadata object]] in a later section)

=== The File Client ===
The file client object is returned from the script resolver shim,  and '''must''' have the following shape:
;FileClient.prototype.fileServiceRootURL()
:Returns the string root of the service (in most simple cases this is "/")
;FileClient.prototype.search(options)
:Returns a list of file objects for the given options (more on the [[#The Search Options|search options]] in a later section)
;FileClient.prototype.read(filename)
:Returns the contents and [[#The Metadata Object|metadata]] for a file with the given name

=== The Metadata Object ===

This object is used to describe a file (without necessarily being a handle to that file) and '''must''' contain at least the following information:
;name
:The string name of the file
;location
:The string location of the file. This is the full path to the file, such that a read could read the contents of the file
;path
:The string, workspace-relative path of the file
;contentType
:An object that contains the id of the content type 

=== The File Object ===
This object is used to describe a file, and carries the contents of the file (typically this object is returned from <code>FileClient.read</code>. The object '''must''' have the following shape:
;name
:The string name of the file
;location
:The string, fully qualified path of the file - where it was read from
;contents
:The string contents of the file

=== Get Workspace File Options ===
This object is passed into <code>ScriptResolver.getWorkspaceFile</code> and can contain any additional options needed to find the files in the workspace.

=== The Search Options ===
This object is passed into <code>FileClient.search</code>, and can contain any additional options needed to perform the search.

== Consuming the API ==

Once you have a freshly minted instance of the tools in your hand (after providing the [[#API Dependencies|necessary shims]]), you can simply make function calls for the support you would like to use. 

The API is arranged with some functions directly on the instance and some of them on a <code>Tern</code> child object.

More specifically the API currently looks like:

;JavaScript.prototype.Tern.addFile(file, text)
:Add the given file and contents to Tern
;JavaScript.prototype.Tern.checkRef(file, offset, origin, files, callback)
:Check the given reference against the original to see if the types match
;JavaScript.prototype.Tern.completions(file, offset, keywords, files, callback)
:Compute content assist
;JavaScript.prototype.Tern.definition(file, offset, guess, files, callback)
:Get the definition at the given offset
;JavaScript.prototype.Tern.delFile(file)
:Delete the given file from Tern
;JavaScript.prototype.Tern.documentation(file, offset, docFormat, files, callback)
:Get the JSDoc for the thing at the given offset
;JavaScript.prototype.Tern.environments(callback)
:Get all of the detected environments from Tern (a delegate to a custom parser hook)
;JavaScript.prototype.Tern.fixes(file, annotation, annotations, files, callback)
:Computes the quick fixes for the given annotation, and optionally the list of similar annotations
;JavaScript.prototype.Tern.implementation(file, offset, guess, files, callback)
:Find the actual implementation of the thing at the given offset (not just its declaration)
;JavaScript.prototype.Tern.installedPlugins(callback)
:Get all of the plugins currently installed in Tern
;JavaScript.prototype.Tern.lint(file, rules, env, files, callback)
:Run ESLint on the given file with the given rules / settings
;JavaScript.prototype.Tern.occurrences(file, offset, files, callback)
:Compute the occurrences for the given file and offset
;JavaScript.prototype.Tern.outline(file, files, callback)
:Compute a source outline for the given file
;JavaScript.prototype.Tern.rename(file, offset, newname, files, callback)
:Compute a rename change set at the given offset, for the new name
;JavaScript.prototype.Tern.startServer(jsonOptions, callback)
:Start (or restart) the running Tern server
;JavaScript.prototype.Tern.type(file, offset, callback)
:Look up the type information at the given offset

More and more functionality will be added over time, such as, access to the quick fix computer, doc generation and markdown hovers. We chose to provide access to the underlying Tern server first, so we could make a Tern service on Orion for other plugins.

=== The Callback Function ===
For most of the API, you are required to give a function that will be called when the tools have completed processing your request. In all cases, the callback will be called, and will be called with the first param being an error (if one) and the second param being the results of the request.

[[Category:Orion]]
[[Category:JavaScript]]