Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Orion/Documentation/Developer Guide/Core client services"

(orion.core.favorite)
(Merge edit by Caseyflynn.google.com)
 
(38 intermediate revisions by 8 users not shown)
Line 2: Line 2:
 
Orion provides a number of basic infrastructure services that can be used by client scripts for performing various tasks. These services have no user interface component and can be used within any page of a client application. This section of the guide outlines what services are available, along with simple examples of how to use them.
 
Orion provides a number of basic infrastructure services that can be used by client scripts for performing various tasks. These services have no user interface component and can be used within any page of a client application. This section of the guide outlines what services are available, along with simple examples of how to use them.
  
= orion.core.favorite =
+
= orion.core.container.themes.provider =
 +
The container themes service retrieves Style Objects that are converted to CSS and appended to the DOM. Where Style objects are as follows:
 +
<source lang="javascript" enclose="div">
 +
{
 +
  “className” : Base Class Name,
 +
  “name”      : User defined name for the theme,
 +
  “styles”    : JSON object containing CSS style information
 +
}
 +
</source>
 +
:where the styles is defined recursively as:
 +
<source lang="javascript" enclose="div">
 +
“cssSelector” : {
 +
    (“cssSelector” | “CSS Property Name” : “CSS Property Value”)
 +
}
 +
</source>
 +
:Where “cssSelector” is any valid CSS Selector (e.g. .class, #id, element, etc). “CSS Property Name” and “CSS Property Value” are valid CSS property names and values respectively.
 +
To implement a provider themes provider, a plugin may be created that conforms to the following API:
 +
; getStyles ( ) — returns Array of container style objects
 +
: Obtains and returns style objects.
 +
; getThemeVersion ( ) — returns a Number indicating version
 +
: Version number is used to determine whether new Style information is available.
 +
; getProtectedThemes ( ) — returns Array of string containing theme names
 +
: Obtains and returns theme names that should not be deleted or modified via the Theme Settings page.
 +
; getDefaultTheme ( ) — returns a String containing a valid theme name
 +
: Obtains and returns a theme name that should be used as the default theme if the user has not selected one via Theme Settings page.
  
The <tt>orion.core.favorite</tt> service is used to access and store the user's bookmarks or favorites. While a user may opt to use their own browser's bookmark mechanism instead, there are some specific advantages to using Orion's favorite service instead:
+
= orion.core.contentTypeRegistry =
* Favorites are persisted on the server, so the user can switch to another client computer or browser and access their familiar bookmarks
+
* Favorites are associated with a specific Orion application and user, so favorites from different users or applications are not all mixed into a single place.
+
* Favorites are used to suggest file and folder based parameters for other actions in Orion, such as moving and copying files to a location, or finding specific files.
+
  
Here is an example usage of the favorites service:
+
The <tt>orion.core.contentTypeRegistry</tt> service provides information about the [[Orion/Documentation/Developer Guide/Plugging into the navigator#orion.core.contenttype|Content Types]] that have been registered with Orion.
  
serviceRegistry.getService("orion.core.favorite").makeFavorites(item);
+
Here is an example usage showing how to query all registered content types and print them to the console:
 
+
<source lang="javascript" enclose="div">
See <tt>orion.favorites.FavoritesService</tt> in the Orion client API reference for a complete list of functions available on the favorite service.
+
serviceRegistry.getService("orion.core.contentTypeRegistry").getContentTypes().then(function(contentTypes) {
 +
    contentTypes.forEach(function(contentType) {
 +
        console.log("Content Type ID: " + contentType.id + ", " +
 +
                "name: " + contentType.name + ", " +
 +
                "extends from: " + contentType['extends'] + ", " +
 +
                "file extension(s): [" + contentType.extension.join(",") + "], " +
 +
                "filename(s): [" + contentType.filename.join(",") + "], " +
 +
                "image: " + contentType.image + "\n");
 +
    });
 +
});
 +
</source>
 +
See <tt>orion.core.ContentTypeRegistry</tt> in the Orion client API reference for a complete list of functions available.
  
 
= orion.core.file =
 
= orion.core.file =
Line 20: Line 52:
  
 
The code snippet below demonstrates a use of this service:
 
The code snippet below demonstrates a use of this service:
<pre>
+
<source lang="javascript" enclose="div" >
provider.registerServiceProvider("orion.core.file", service, {Name: 'Sample File System'});
+
    provider.registerServiceProvider("orion.core.file", service, {Name: 'Sample File System'});
</pre>
+
</source>
  
The above code will contribute a top level node to the Navigator named "Sample File System". The parameter "service" in the API above must provide the functions specified by the Orion file client API. Refer to <tt>orion.fileClient.FileClient</tt> in the client API reference for further details. For more information on client-server interaction, see Orion [http://wiki.eclipse.org/Orion/Server_API/File_API File Server API]. For an complete file system example, see the [https://github.com/eclipse/orion.client/blob/master/bundles/org.eclipse.orion.client.core/web/plugins/sampleFilePlugin.html sample file plugin] in the Orion Git repository.
+
The above code will contribute a top level node to the Navigator named "Sample File System". The parameter "service" in the API above must provide the functions specified by the Orion file client API. Refer to <tt>orion.fileClient.FileClient</tt> in the client API reference for further details. For more information on client-server interaction, see Orion [http://wiki.eclipse.org/Orion/Server_API/File_API File Server API]. For an complete file system example, see the [https://github.com/eclipse/orion.client/blob/master/bundles/org.eclipse.orion.client.ui/web/plugins/filePlugin/HTML5LocalFileImpl.js HTML5 local file plugin] in the Orion Git repository.
  
 +
The file client API methods are as follows:
 +
; fetchChildren (location) — returns Array of [[Orion/Server API/File API#File|File]].
 +
: Obtains the children of a remote resource.<br>Among other places, this function is used in the file navigator to display the file system contents in a tree view.
 +
; createWorkspace (name)
 +
: Creates a new workspace with the given name.
 +
; loadWorkspaces ( ) — returns an Array of [[Orion/Server API/File API#File|File]].
 +
: Loads all the user's workspaces.
 +
; loadWorkspace (location) —  returns a [[Orion/Server API/File API#File|File]].
 +
: Loads the workspace with the given id and sets it to be the current workspace for the IDE. The workspace is created if none already exists.<br>Called by the file navigator when navigating to the root of the file system.<br>NOTE: The returned file object should have a zero-length 'Parents' array to designate it as the root of the filesystem (see [https://bugs.eclipse.org/bugs/show_bug.cgi?id=392374 bug 392374]).
 +
; createProject (url, projectName, serverPath, create)
 +
: Adds a project to a workspace.<br>The Orion IDE invokes this function when a top-level folder is created in the file navigator.
 +
; createFolder (parentLocation, folderName)
 +
: Creates a folder.<br>Invoked when using the '''New Folder''' command in the file navigator.
 +
; createFile (parentLocation, fileName)
 +
: Create a new file in a specified location.<br>Invoked when using the '''New File''' command in the file navigator.
 +
; deleteFile (location)
 +
: Deletes a file, directory, or project.<br>Invoked when using the '''Delete''' command in the file navigator.
 +
; moveFile (sourceLocation, targetLocation, name)
 +
: Moves a file or directory.<br>Invoked when using the '''Move''' and '''Cut..Paste''' commands in the file navigator.
 +
; copyFile (sourceLocation, targetLocation)
 +
: Copies a file or directory.<br>Invoked when using the '''Copy..Paste''' commands in the file navigator.
 +
; read (location, isMetadata) — returns String (contents) or [[Orion/Server API/File API#File|File]] (metadata).
 +
: Returns the contents or metadata of the file at the given location.<br>Invoked by the Orion editor to open a file for editing, and to retrieve metadata about the file being edited.
 +
; write (location, contents, args)
 +
: Writes the contents or metadata of the file at the given location.<br>Invoked by the Orion editor to save a file being edited.
 +
; remoteImport (targetLocation, options)
 +
: Imports file and directory contents from another server.<br>
 +
; remoteExport (sourceLocation, options)
 +
: Exports file and directory contents to another server.
 +
; search (location, query) — returns Array of [[Orion/Server API/File API#File|File]].
 +
: Performs a search with the given query.<br>Invoked by various search widgets that appear in the Orion UI.
  
 +
This API is asynchronous: in other words, every API method is expected to return a promise that eventually resolves with the result object, or rejects if an error occurred.
  
 +
<!--
 
= orion.core.marker =
 
= orion.core.marker =
  
 
The marker service is used to store problems found by a builder or syntax validator. A client can register with this service for notification when markers are changed. Here is an example of a component that is registering for notification of marker changes:
 
The marker service is used to store problems found by a builder or syntax validator. A client can register with this service for notification when markers are changed. Here is an example of a component that is registering for notification of marker changes:
 
+
<source lang="javascript" enclose="div" >
 
   serviceRegistry.getService("orion.core.marker").addEventListener("problemsChanged",  
 
   serviceRegistry.getService("orion.core.marker").addEventListener("problemsChanged",  
 
       function(problems) {
 
       function(problems) {
 
         //do something with the new problems
 
         //do something with the new problems
 
       });
 
       });
 
+
</source>
 
Each marker is a simple JSON object with the following properties:
 
Each marker is a simple JSON object with the following properties:
  
Line 45: Line 110:
 
;character
 
;character
 
:The column position of the marker
 
:The column position of the marker
 +
-->
  
 
= orion.core.preference =
 
= orion.core.preference =
Line 51: Line 117:
  
 
Here is an example of retrieving a preference storing the list of recently used projects:
 
Here is an example of retrieving a preference storing the list of recently used projects:
 
+
<source lang="javascript" enclose="div">
  prefService.getPreferences("/window/recent").then(function(prefs) {
+
prefService.getPreferences("/window/recent").then(function(prefs) {
 
     var projects =  prefs.get("projects");
 
     var projects =  prefs.get("projects");
 
     if (typeof projects === "string") {
 
     if (typeof projects === "string") {
Line 60: Line 126:
 
       //do something with the projects
 
       //do something with the projects
 
     }
 
     }
  });
+
});
 
+
</source>
 
And here is an example of adding a new project to the list, and storing the result back in the preference service:
 
And here is an example of adding a new project to the list, and storing the result back in the preference service:
 
+
<source lang="javascript" enclose="div">
  prefService.getPreferences("/window/recent").then(function(prefs) {
+
prefService.getPreferences("/window/recent").then(function(prefs) {
 
     var projects = prefs.get("projects");
 
     var projects = prefs.get("projects");
 
     if (typeof projects === "string") {
 
     if (typeof projects === "string") {
Line 71: Line 137:
 
     projects.push({name: "My Proj", location: "http://example.com/myproj"});
 
     projects.push({name: "My Proj", location: "http://example.com/myproj"});
 
     prefs.put("projects", projects);
 
     prefs.put("projects", projects);
  });
+
});
 +
</source>
  
= orion.core.textlink =
+
= orion.core.setting =
 +
Orion plugins can define ''settings'' using the <code>orion.core.setting</code> service. A setting defines some persistent information that is provided to one of the plugin's services. Defined settings appear on Orion's <b>Settings</b> page, and their values can be changed using an automatically-generated UI.
  
The text link service scans text for segments that could be interpreted as hyperlinks, and inserts appropriate anchor elements representing each link. For example the service could scan for email addresses in a piece of text and convert them to mailto: links.
+
A setting is a combination of two more basic configuration elements:
 +
* A [[Orion/Documentation/Developer Guide/Configuration services#Managed Services|''PID'' (persistent identifier)]], which uniquely identifies the configuration data for the setting.
 +
* [[Orion/Documentation/Developer Guide/Configuration services#Meta Typing|''Metatype'' information]], which defines the "shape" of the setting. Specifically, it defines what named properties appear in the setting and what data type they have (string, boolean, number, etc). The Settings page uses this Metatype information to generate appropriate UI widgets (for example, text field, checkbox, etc).
  
Here is an example of using the text link service:
+
== Service properties ==
 +
To contribute one or more settings, the '''settings''' service property is used:
 +
; settings
 +
: <code>Setting[]</code>. Defines Settings. Each <code>Setting</code> element has the following shape:
 +
:; pid
 +
:: <code>String</code>. The PID for this setting. This PID occupies the same namespace as the PIDs contributed by [[Orion/Documentation/Developer Guide/Configuration services#Managed Services|Managed Services]], and must be unique in that respect.
 +
:; name
 +
:: <code>String</code>. Human-readable name of this setting.
 +
:; category
 +
:: <code>String</code>. ''Optional''. Gives the ID of a category that this setting will be associated with. Many settings can be associated with one category. All the categories
 +
:; tags
 +
:: <code>String[]</code>. ''Optional.'' List of tags applying to this setting.
 +
:; order
 +
:: <code>Number</code>. ''Optional.'' The one-based ordering for preferences to be rendered on the settings page. If not provided zero is assumed.
 +
:; properties
 +
:: <code>[[Orion/Documentation/Developer_Guide/Configuration_services#Define_an_OCD|AttributeDefinition]][]</code>. Gives the properties that make up this setting. The shape of the <code>AttributeDefinition</code> element is explained in [[Orion/Documentation/Developer Guide/Configuration services#Define an OCD|Metatype documentation]].
  
var divWithLinks = linkService.addLinks(someText);
+
== Service methods ==
dojo.place(divWithLinks, body, "first");
+
None. This service is completely declarative.
  
The text link service makes use of [[Orion/Documentation/Developer_Guide/Plugging_into_Orion_pages#orion.core.linkScanner| link scanners]] contributed by plugins to perform the analysis and replacement of text with links. If no link scanners are available, the text link service simply returns a DOM element containing the entire input text.
+
== Example 1: a boolean setting ==
 +
This example shows how to define a Setting with PID <code>example.navconfig</code>. This Setting has a single property <code>newtab</code>, which is boolean-typed. Because we've enumerated the property's possible values using an '''options''', the generated UI presentation will show a drop-down menu. Since we've provided a '''defaultValue''' of <code>false</code>, the second option "Open links in a same tab" will selected by default.
 +
<source lang="javascript" enclose="div">
 +
define(['orion/plugin'], function(PluginProvider) {
 +
    var pluginProvider = new PluginProvider();
 +
    pluginProvider.registerService('orion.core.setting',
 +
        {},  // no methods
 +
        {  settings: [
 +
              {  pid: 'example.navconfig',
 +
                  name: 'Navigation settings',
 +
                  properties: [
 +
                      {  id: 'newtab',
 +
                        name: 'Links',
 +
                        type: 'boolean',
 +
                        defaultValue: false,
 +
                        options: [
 +
                            {  label: "Open links in a new tab",
 +
                                value: true
 +
                            },
 +
                            {  label: "Open links in same tab",
 +
                                value: false
 +
                            }
 +
                        ]
 +
                      }
 +
                  ]
 +
              }
 +
          ]
 +
        });
 +
    provider.connect();
 +
});
 +
</source>
 +
When a user visits the Orion Settings page, they'll see an automatically-generated UI containing a drop-down menu, similar to the one shown below. Manipulating the drop-down menu causes the setting's value to change, and causes any Managed Services registered against the <code>example.navconfig</code> PID to have their [[Orion/Documentation/Developer Guide/Configuration services#Service methods|<code>updated()</code> methods]] invoked.
  
= orion.file.contenttype =
+
[[Image:Orion orion.core.setting example.png|border]]
The content type service tells Orion about a new kind of file. The content types contributed to this service don't have any direct effect on the Orion UI, but they can be referred to by other services that need to associate themselves with a particular kind of file. For an example, see [[Orion/Documentation/Developer_Guide/Plugging_into_the_navigator#orion.navigate.openWith|orion.navigate.openWith]].
+
  
The Orion client UI defines a bunch of content types by default: see <code>webEditingPlugin.html</code> in the client UI code.
+
== Example 2: ordered settings ==
 +
Here is how you can order settings on the page when more than one group is declared for the same category:
  
== Service attributes ==
+
<source lang="javascript" enclose="div">
; contentTypes
+
// my_plugin.js
: An <tt>Array</tt> containing one or more content types to register. Each element of the array defines a new content type, and must have this shape:
+
define(["orion/plugin"], function(PluginProvider) {
::; id
+
    var pluginProvider = new PluginProvider();
::: <tt>String</tt> The unique identifier of the content type. This is a simple hierarchical name and should start with a category like "text" or "image".
+
    pluginProvider.registerService("orion.core.setting",
::; name
+
        {}// no methods
::: <tt>String</tt> The user-readable name of the content type.
+
        {  settings: [
::; extension
+
              {  pid: "example.group1",
::: <tt>String[]</tt> ''Optional.'' Array of file extensions characterizing this content type. (Extensions are given without the leading "." character).
+
                  name: "mysetting1",
::; extension
+
                  order: 2,
::: <tt>String[]</tt> ''Optional.'' Array of filenames characterizing this content type. Use this when a type does not have a characteristic file extension, but rather a filename. (For example, "Makefile", "README", "passwd").
+
                  properties: [
::; extends
+
                      {  id: "key1",
::: <tt>String</tt> ''Optional.'' If this content type is a subtype of another, this gives the parent content type's ID.
+
                        name: "Pref1",
 +
                        type: "string"
 +
                      }
 +
                  ]
 +
              },
 +
              {  pid: "example.group2",
 +
                  name: "mysetting2",
 +
                  order: 1,
 +
                  properties: [
 +
                      {  id: "key2",
 +
                        name: "Pref2",
 +
                        type: "string"
 +
                      }
 +
                  ]
 +
              }
 +
          ]
 +
        });
 +
    provider.connect();
 +
});
 +
</source>
  
== Service methods ==
 
None. This service is purely declarative.
 
  
== Example ==
+
Then the page will render in the requested order like:
This example code contributes contributes a new content type for Perl files. A Perl file extends from <code>"text.plain"</code> and has the extension <code>.pl</code>.
+
 
  provider.registerServiceProvider("orion.file.contenttype", {}, {
+
[[File:Sorted-prefs.png]]
    contentTypes: [{  id: "text.perl",
+
 
                      name: "Perl",
+
== See also ==
                      extension: ["pl"],
+
* [[Orion/Documentation/Developer Guide/Configuration services|Configuration services]]
                      "extends": "text.plain"
+
 
                  }] });
+
= orion.core.textlink =
  provider.connect();
+
 
 +
The text link service scans text for segments that could be interpreted as hyperlinks, and inserts appropriate anchor elements representing each link. For example the service could scan for email addresses in a piece of text and convert them to mailto: links.
 +
 
 +
Here is an example of using the text link service:
 +
<source lang="javascript" enclose="div" >
 +
var divWithLinks = linkService.addLinks(someText);
 +
dojo.place(divWithLinks, body, "first");
 +
</source>
 +
The text link service makes use of [[Orion/Documentation/Developer_Guide/Plugging_into_Orion_pages#orion.core.linkScanner| link scanners]] contributed by plugins to perform the analysis and replacement of text with links. If no link scanners are available, the text link service simply returns a DOM element containing the entire input text.
 +
 
 +
The container themes service retrieves Style Objects that are converted to CSS and appended to the DOM. Where Style objects are as follows:
 +
<source lang="javascript" enclose="div">
 +
{
 +
  “className” : Base Class Name,
 +
  “name”      : User defined name for the theme,
 +
  “styles”    : JSON object containing CSS style information
 +
}
 +
</source>
 +
:where the styles is defined recursively as:
 +
<source lang="javascript" enclose="div">
 +
“cssSelector” : {
 +
    (“cssSelector” | “CSS Property Name” : “CSS Property Value”)
 +
}
 +
</source>
 +
:Where “cssSelector” is any valid CSS Selector (e.g. .class, #id, element, etc). “CSS Property Name” and “CSS Property Value” are valid CSS property names and values respectively.
  
The example code below contributes a new content type for Ant build files. An Ant build file is a special kind of XML file that always has the name "build.xml".
+
To implement a provider themes provider, a plugin may be created that conforms to the following API:
 +
; getStyles ( ) — returns Array of container style objects
 +
: Obtains and returns style objects.
 +
; getThemeVersion ( ) — returns a Number indicating versoin
 +
: Version number is used to determine whether new Style information is available.
 +
; getProtectedThemes ( ) — returns Array of string containing theme names
 +
: Obtains and returns theme names that should not be deleted or modified via the Theme Settings page.
 +
; getDefaultTheme ( ) — returns a String containing a valid theme name
 +
: Obtains and returns a theme name that should be used as the default theme if the user has not selected one via Theme Settings page.
  
  provider.registerServiceProvider("orion.file.contenttype", {}, {
+
[[Category:Orion]]
    contentTypes: [{  id: "text.ant",
+
                      name: "Ant build file",
+
                      filename: ["build.xml"],
+
                      "extends": "text.xml"
+
                  }] });
+
  provider.connect();
+

Latest revision as of 11:28, 14 September 2017

Overview of core client services

Orion provides a number of basic infrastructure services that can be used by client scripts for performing various tasks. These services have no user interface component and can be used within any page of a client application. This section of the guide outlines what services are available, along with simple examples of how to use them.

orion.core.container.themes.provider

The container themes service retrieves Style Objects that are converted to CSS and appended to the DOM. Where Style objects are as follows:

{
  “className” : Base Class Name,
  “name”      : User defined name for the theme,
  “styles”    : JSON object containing CSS style information
}
where the styles is defined recursively as:
“cssSelector” : {
    (“cssSelector” | “CSS Property Name” : “CSS Property Value”)
}
Where “cssSelector” is any valid CSS Selector (e.g. .class, #id, element, etc). “CSS Property Name” and “CSS Property Value” are valid CSS property names and values respectively.

To implement a provider themes provider, a plugin may be created that conforms to the following API:

getStyles ( ) — returns Array of container style objects
Obtains and returns style objects.
getThemeVersion ( ) — returns a Number indicating version
Version number is used to determine whether new Style information is available.
getProtectedThemes ( ) — returns Array of string containing theme names
Obtains and returns theme names that should not be deleted or modified via the Theme Settings page.
getDefaultTheme ( ) — returns a String containing a valid theme name
Obtains and returns a theme name that should be used as the default theme if the user has not selected one via Theme Settings page.

orion.core.contentTypeRegistry

The orion.core.contentTypeRegistry service provides information about the Content Types that have been registered with Orion.

Here is an example usage showing how to query all registered content types and print them to the console:

serviceRegistry.getService("orion.core.contentTypeRegistry").getContentTypes().then(function(contentTypes) {
    contentTypes.forEach(function(contentType) {
        console.log("Content Type ID: " + contentType.id + ", " +
                "name: " + contentType.name + ", " +
                "extends from: " + contentType['extends'] + ", " +
                "file extension(s): [" + contentType.extension.join(",") + "], " +
                "filename(s): [" + contentType.filename.join(",") + "], " +
                "image: " + contentType.image + "\n");
    });
});

See orion.core.ContentTypeRegistry in the Orion client API reference for a complete list of functions available.

orion.core.file

The orion.core.file service is used to provide file system contents for the Orion workspace. For example a plug-in can use this service to include content from one server into a workspace on another server. Each file service is displayed as a root element in the Orion Navigator page.

The code snippet below demonstrates a use of this service:

    provider.registerServiceProvider("orion.core.file", service, {Name: 'Sample File System'});

The above code will contribute a top level node to the Navigator named "Sample File System". The parameter "service" in the API above must provide the functions specified by the Orion file client API. Refer to orion.fileClient.FileClient in the client API reference for further details. For more information on client-server interaction, see Orion File Server API. For an complete file system example, see the HTML5 local file plugin in the Orion Git repository.

The file client API methods are as follows:

fetchChildren (location) — returns Array of File.
Obtains the children of a remote resource.
Among other places, this function is used in the file navigator to display the file system contents in a tree view.
createWorkspace (name)
Creates a new workspace with the given name.
loadWorkspaces ( ) — returns an Array of File.
Loads all the user's workspaces.
loadWorkspace (location) — returns a File.
Loads the workspace with the given id and sets it to be the current workspace for the IDE. The workspace is created if none already exists.
Called by the file navigator when navigating to the root of the file system.
NOTE: The returned file object should have a zero-length 'Parents' array to designate it as the root of the filesystem (see bug 392374).
createProject (url, projectName, serverPath, create)
Adds a project to a workspace.
The Orion IDE invokes this function when a top-level folder is created in the file navigator.
createFolder (parentLocation, folderName)
Creates a folder.
Invoked when using the New Folder command in the file navigator.
createFile (parentLocation, fileName)
Create a new file in a specified location.
Invoked when using the New File command in the file navigator.
deleteFile (location)
Deletes a file, directory, or project.
Invoked when using the Delete command in the file navigator.
moveFile (sourceLocation, targetLocation, name)
Moves a file or directory.
Invoked when using the Move and Cut..Paste commands in the file navigator.
copyFile (sourceLocation, targetLocation)
Copies a file or directory.
Invoked when using the Copy..Paste commands in the file navigator.
read (location, isMetadata) — returns String (contents) or File (metadata).
Returns the contents or metadata of the file at the given location.
Invoked by the Orion editor to open a file for editing, and to retrieve metadata about the file being edited.
write (location, contents, args)
Writes the contents or metadata of the file at the given location.
Invoked by the Orion editor to save a file being edited.
remoteImport (targetLocation, options)
Imports file and directory contents from another server.
remoteExport (sourceLocation, options)
Exports file and directory contents to another server.
search (location, query) — returns Array of File.
Performs a search with the given query.
Invoked by various search widgets that appear in the Orion UI.

This API is asynchronous: in other words, every API method is expected to return a promise that eventually resolves with the result object, or rejects if an error occurred.


orion.core.preference

The preferences service manages a hierarchical set of preference nodes. Nodes are identified by a path string, where segments are delimited by the slash character ('/'). Each node is a JSON object with string keys and values that are String, Boolean, or Number.

Here is an example of retrieving a preference storing the list of recently used projects:

prefService.getPreferences("/window/recent").then(function(prefs) {
    var projects =  prefs.get("projects");
    if (typeof projects === "string") {
      projects = JSON.parse(projects);
    }
    if (projects && projects.length && projects.length > 0) {
      //do something with the projects
    }
});

And here is an example of adding a new project to the list, and storing the result back in the preference service:

prefService.getPreferences("/window/recent").then(function(prefs) {
    var projects = prefs.get("projects");
    if (typeof projects === "string") {
      projects = JSON.parse(projects);
    }
    projects.push({name: "My Proj", location: "http://example.com/myproj"});
    prefs.put("projects", projects);
});

orion.core.setting

Orion plugins can define settings using the orion.core.setting service. A setting defines some persistent information that is provided to one of the plugin's services. Defined settings appear on Orion's Settings page, and their values can be changed using an automatically-generated UI.

A setting is a combination of two more basic configuration elements:

  • A PID (persistent identifier), which uniquely identifies the configuration data for the setting.
  • Metatype information, which defines the "shape" of the setting. Specifically, it defines what named properties appear in the setting and what data type they have (string, boolean, number, etc). The Settings page uses this Metatype information to generate appropriate UI widgets (for example, text field, checkbox, etc).

Service properties

To contribute one or more settings, the settings service property is used:

settings
Setting[]. Defines Settings. Each Setting element has the following shape:
pid
String. The PID for this setting. This PID occupies the same namespace as the PIDs contributed by Managed Services, and must be unique in that respect.
name
String. Human-readable name of this setting.
category
String. Optional. Gives the ID of a category that this setting will be associated with. Many settings can be associated with one category. All the categories
tags
String[]. Optional. List of tags applying to this setting.
order
Number. Optional. The one-based ordering for preferences to be rendered on the settings page. If not provided zero is assumed.
properties
AttributeDefinition[]. Gives the properties that make up this setting. The shape of the AttributeDefinition element is explained in Metatype documentation.

Service methods

None. This service is completely declarative.

Example 1: a boolean setting

This example shows how to define a Setting with PID example.navconfig. This Setting has a single property newtab, which is boolean-typed. Because we've enumerated the property's possible values using an options, the generated UI presentation will show a drop-down menu. Since we've provided a defaultValue of false, the second option "Open links in a same tab" will selected by default.

define(['orion/plugin'], function(PluginProvider) {
    var pluginProvider = new PluginProvider();
    pluginProvider.registerService('orion.core.setting',
        {},  // no methods
        {  settings: [
               {  pid: 'example.navconfig',
                  name: 'Navigation settings',
                  properties: [
                      {  id: 'newtab',
                         name: 'Links',
                         type: 'boolean',
                         defaultValue: false,
                         options: [
                             {  label: "Open links in a new tab",
                                value: true
                             },
                             {  label: "Open links in same tab",
                                value: false
                             }
                         ]
                      }
                  ]
               }
           ]
        });
    provider.connect();
});

When a user visits the Orion Settings page, they'll see an automatically-generated UI containing a drop-down menu, similar to the one shown below. Manipulating the drop-down menu causes the setting's value to change, and causes any Managed Services registered against the example.navconfig PID to have their updated() methods invoked.

Orion orion.core.setting example.png

Example 2: ordered settings

Here is how you can order settings on the page when more than one group is declared for the same category:

// my_plugin.js
define(["orion/plugin"], function(PluginProvider) {
    var pluginProvider = new PluginProvider();
    pluginProvider.registerService("orion.core.setting",
        {},  // no methods
        {  settings: [
               {  pid: "example.group1",
                  name: "mysetting1",
                  order: 2,
                  properties: [
                      {  id: "key1",
                         name: "Pref1",
                         type: "string"
                      }
                  ]
               },
               {  pid: "example.group2",
                  name: "mysetting2",
                  order: 1,
                  properties: [
                      {  id: "key2",
                         name: "Pref2",
                         type: "string"
                      }
                  ]
               }
           ]
        });
    provider.connect();
});


Then the page will render in the requested order like:

Sorted-prefs.png

See also

orion.core.textlink

The text link service scans text for segments that could be interpreted as hyperlinks, and inserts appropriate anchor elements representing each link. For example the service could scan for email addresses in a piece of text and convert them to mailto: links.

Here is an example of using the text link service:

var divWithLinks = linkService.addLinks(someText);
dojo.place(divWithLinks, body, "first");

The text link service makes use of link scanners contributed by plugins to perform the analysis and replacement of text with links. If no link scanners are available, the text link service simply returns a DOM element containing the entire input text.

The container themes service retrieves Style Objects that are converted to CSS and appended to the DOM. Where Style objects are as follows:

{
  “className” : Base Class Name,
  “name”      : User defined name for the theme,
  “styles”    : JSON object containing CSS style information
}
where the styles is defined recursively as:
“cssSelector” : {
    (“cssSelector” | “CSS Property Name” : “CSS Property Value”)
}
Where “cssSelector” is any valid CSS Selector (e.g. .class, #id, element, etc). “CSS Property Name” and “CSS Property Value” are valid CSS property names and values respectively.

To implement a provider themes provider, a plugin may be created that conforms to the following API:

getStyles ( ) — returns Array of container style objects
Obtains and returns style objects.
getThemeVersion ( ) — returns a Number indicating versoin
Version number is used to determine whether new Style information is available.
getProtectedThemes ( ) — returns Array of string containing theme names
Obtains and returns theme names that should not be deleted or modified via the Theme Settings page.
getDefaultTheme ( ) — returns a String containing a valid theme name
Obtains and returns a theme name that should be used as the default theme if the user has not selected one via Theme Settings page.

Back to the top