The Editor Context object | ||
---|---|---|
![]() |
![]() |
|
Plugging into the editor | orion.edit.command |
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:
editorContextObject.getText().then(function(text) { // 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.
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.
The Editor Context object provides the following methods:
Number
. Returns the offset of the editing caret.Selection
. Returns the editor's current selection.String
. Returns the text in the given range. undefined
. Sets the caret offset. If show
is true, the editor will scroll to the new caret position.undefined
. Sets the editor's selection.undefined
. Sets the text in the given range.
![]() |
![]() |
![]() |
Plugging into the editor | orion.edit.command |