Revision as of 16:10, 24 June 2011

Overview of user interface services

Orion provides a number of utility services that can be used by scripts on Orion pages. These are not services that would be implemented or used by a plugin. However, they provide ways to contribute links, messages, and commands to the title area of each page, to display dialogs to the end user. A service is also provided for broadcasting or listening to selection changes, which allows synchronization between multiple widgets on a page. For example, this service is used to enable the editor to react to selection changes in the outline panel.

orion.page.selection

The selection service tracks the selection in the current page. The page determines how selections are shown and made by the user, but typically they are managed in a list, table, or tree. Clients can use this service to get or set the current selection, or to register a listener that will be notified when the selection changes.

Here is an example of adding a listener to track selection changes:

 serviceRegistry.getService("orion.page.selection").then(function(service) {
   service.addEventListener("selectionChanged", function(fileURI) {
     //do something with the selection
   });
 });

See orion.selection.Selection in the client API reference for a complete list of functions available on the selection service.

orion.page.command

The command service is responsible for managing and rendering commands such as tool bar and menu items. A command represents a single clickable action for a user, such as a toolbar button or menu item. Commands can typically be defined in common code, independent of any particular UI presentation of the commands or associated items. Here is an example of a simple command definition:

 define(['orion/commands'], function(mCommands) {

   var editCommand = new mCommands.Command({
     name: "Edit",
     image: "/images/editing_16.gif",
     id: "my.command.id",
     visibleWhen: function(item) {
       //return true if this command should be visible for 'item'
     },
     callback: function(item, commandId, domId, userData) {
       //execute the command
     })
   });
 });

Once a command is defined, it needs to be registered in the command service. A scope for the command is specified when the command is added. Commands contributed in the "global" scope are intended to be used on any page, and typically do not depend on an "item" in the handler. Commands in the "dom" scope are intended to be shown in a particular dom element that is defined when the command is contributed by a page. The "item" in question is typically associated with the page or the selection service. Commands in the "object" scope are intended to be shown for individual objects (items) that appear in tables, lists, or trees. The item in the handler typically corresponds to the object by which it is presented.

This snippet below registers the edit command and adds it in the "object" scope.

For a command to appear on a page, the page must register a "command contribution" in the UI. The contributions are made separately so that, for example, an application could define all the commands that apply to its objects in common code, leaving the individual pages to decide how those commands might be shown.

Using the above example, a page that wanted to show object-level editing commands would make a contribution using the command service.

serviceRegistry.getService("orion.page.command").then(function(commandService) {
  commandService.registerCommandContribution("my.command.id", 1);
});

In its simplest form, a command contribution describes the command that should be shown, and a position that can be used relative to other commands. Additional parameters allow the page to specify which dom element a command should appear in (if it is "dom" scope), any nested groups it should be grouped with, and any keybindings that should be registered in order to trigger the command.

Once all commands and the UI contributions are defined, something must trigger the rendering of those commands. For the existing Orion pages, the rendering is handled by the various page components. For example, any "global" commands would be rendered in the header near the search bar. The toolbar renders commands that are scoped at the "dom" level and use a dom id of "pageActions." It figures out which items should be passed to the handler, using the selection service. The navigator renders commands that are contributed at the "object" scope and are considered visible for the items rendered by the navigator.

Pages can define their own dom elements for rendering commands in order to control precise layout, or to handle commands that are scoped to different parts of the page. In this case, the page must not only contribute the commands, but must also render the commands for the dom elements in question. The code that is rendering commands is responsible for determining which object is used as "this" for the command callbacks (the handler) and what item or items are passed as into the callback.

For example, a side by side compare editor might want to render different commands for the left and right compare panes. It must define dom elements where these contributions are shown, and it must render commands into this dom element. The following snippet shows an example of custom dom-based contributions, including a key binding for the "copyToLeft" command:

serviceRegistry.getService("orion.page.command").then(function(commandService) {
  commandService.registerCommandContribution("orion.compare.copyToLeft", 1, rightContainerCommands", 
     /* no parent path */ null, new mKeyBinding.KeyBinding("A", true, true));
  commandService.registerCommandContribution("orion.compare.nextDiff", 2, "rightContainerCommands");
  commandService.registerCommandContribution("orion.compare.prevDiff", 3, "rightContainerCommands");

  // now render the commands into the dom node using "image" style.  There are no items to pass to the handler.
  commandService.renderCommands("rightContainerCommands", "dom", /* no items */ null, myCompareHandler, "image");
});

See orion.commands.CommandService in the client API reference for documentation about commands, contributions, and rendering.

orion.page.dialog

The dialog service provides functions for obtaining simple confirmations for prompts from the user. Use of the dialog service allows clients to perform these simple interactions without choosing a specific implementation (dialog, browser prompts) and instead delegates that responsibility to the service.

See orion.dialogs.DialogService in the client API reference for a complete list of functions available on the dialog service.

orion.page.message

The message service provides functions for reporting status messages, error messages, or information about long running operations. Using the message service allows clients to report information to the user without choosing a specific implementation or UI. The service determines how these messages are reported.vice.

See orion.status.StatusReportingService in the client API reference for a complete list of functions available on the message service.

orion.page.link

The link service provides a mechanism for plugins to add links that should appear in the main header of Orion pages. Clients supply the link name and URL. The header code will look for implementors of this service when generating page headers for Orion. For example, the following snippet defines the main links that are shown in a default Orion installation.

  provider.registerServiceProvider("orion.page.link", serviceImpl, {
     name: "Navigator",
     id: "orion.navigator",
     href: "/navigate/table.html#"
  });
  provider.registerServiceProvider("orion.page.link", serviceImpl, {
     name: "Sites",
     id: "orion.sites",
     href: "/sites/sites.html"
  });
  provider.registerServiceProvider("orion.page.link", serviceImpl, {
     name: "Plugins",
     id: "orion.plugins",
     href: "/plugin/list.html"
  });
  provider.registerServiceProvider("orion.page.link", serviceImpl, {
     name: "Repositories",
     id: "orion.repositories",
     href: "/git/git-clone.html"
  });