Jump to: navigation, search

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

(Add orion.core.contenttypes)
(orion.core.file: attempt to document methods of FileClient API and their usage status)
Line 45: Line 45:
 
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.core/web/plugins/sampleFilePlugin.html sample file plugin] in the Orion Git repository.
  
 
+
The file client API methods are as follows:
 +
; fetchChildren (location)
 +
: Obtains the children of a remote resource.<br />Among other places, this function is used in the Orion navigator to display the file system contents in a tree view.
 +
; createWorkspace (name)
 +
: Creates a new workspace with the given name.<br />TODO -- this is never called by the Orion IDE.
 +
; loadWorkspaces ()
 +
: Loads all the user's workspaces.<br />TODO -- this is never called by the Orion IDE.
 +
; loadWorkspace (location)
 +
: 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 Orion navigator when navigating to the root of the file system.
 +
; createProject (url, projectName, serverPath, create)
 +
: Adds a project to a workspace.<br />TODO -- the Orion IDE never calls this function for third-party file systems.
 +
; createFolder (parentLocation, folderName)
 +
: Creates a folder.<br />Invoked when using the '''New Folder''' command in the Orion navigator.
 +
; createFile (parentLocation, fileName)
 +
: Create a new file in a specified location.<br />Invoked when using the '''New File''' command in the Orion navigator.
 +
; deleteFile (location)
 +
: Deletes a file, directory, or project.<br />Invoked when using the '''Delete''' command in the Orion navigator.
 +
; moveFile (sourceLocation, targetLocation, name)
 +
: Moves a file or directory.<br />Invoked when using the '''Move''' and '''Cut..Paste''' commands in the Orion navigator.
 +
; copyFile (sourceLocation, targetLocation)
 +
: Copies a file or directory.<br />Invoked when using the '''Copy..Paste''' commands in the Orion navigator.
 +
; read (location, isMetadata)
 +
: Returns the contents or metadata of the file at the given location.<br />Invoked by the Orion editor to open a file for editing.
 +
; 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)
 +
: Performs a search with the given query.<br />Invoked by various search widgets that appear in the Orion UI.
  
 
= orion.core.marker =
 
= orion.core.marker =

Revision as of 16:27, 3 April 2012

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.contenttypes

The orion.core.contenttypes 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.contenttypes").getContentTypes().then(function(contentTypes) {
  for (var i=0; i < contentTypes.length; i++) {
    var contentType = contentTypes[i];
    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.ContentTypeService in the Orion client API reference for a complete list of functions available.

orion.core.favorite

The orion.core.favorite 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:

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

serviceRegistry.getService("orion.core.favorite").makeFavorites(itemOrArray);

See orion.favorites.FavoritesService in the Orion client API reference for a complete list of functions available on the favorite service.

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 sample file plugin in the Orion Git repository.

The file client API methods are as follows:

fetchChildren (location)
Obtains the children of a remote resource.
Among other places, this function is used in the Orion navigator to display the file system contents in a tree view.
createWorkspace (name)
Creates a new workspace with the given name.
TODO -- this is never called by the Orion IDE.
loadWorkspaces ()
Loads all the user's workspaces.
TODO -- this is never called by the Orion IDE.
loadWorkspace (location)
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 Orion navigator when navigating to the root of the file system.
createProject (url, projectName, serverPath, create)
Adds a project to a workspace.
TODO -- the Orion IDE never calls this function for third-party file systems.
createFolder (parentLocation, folderName)
Creates a folder.
Invoked when using the New Folder command in the Orion navigator.
createFile (parentLocation, fileName)
Create a new file in a specified location.
Invoked when using the New File command in the Orion navigator.
deleteFile (location)
Deletes a file, directory, or project.
Invoked when using the Delete command in the Orion navigator.
moveFile (sourceLocation, targetLocation, name)
Moves a file or directory.
Invoked when using the Move and Cut..Paste commands in the Orion navigator.
copyFile (sourceLocation, targetLocation)
Copies a file or directory.
Invoked when using the Copy..Paste commands in the Orion navigator.
read (location, isMetadata)
Returns the contents or metadata of the file at the given location.
Invoked by the Orion editor to open a file for editing.
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)
Performs a search with the given query.
Invoked by various search widgets that appear in the Orion UI.

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:

 serviceRegistry.getService("orion.core.marker").addEventListener("problemsChanged", 
     function(problems) {
       //do something with the new problems
     });

Each marker is a simple JSON object with the following properties:

reason
A string stating the description of the problem or marker
line
The line number of the marker
character
The column position of the marker

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