Skip to main content
Jump to: navigation, search

Difference between revisions of "Orion/Documentation/Developer Guide/User interface services"

(Overview of user interface services)
(orion.page.command)
Line 24: Line 24:
  
 
     var editCommand = new mCommands.Command({
 
     var editCommand = new mCommands.Command({
       name: "Edit",
+
       name: "Make Favorite",
       image: "/images/editing_16.gif",
+
       image: "/images/makeFavorite.gif",
 
       id: "my.command.id",
 
       id: "my.command.id",
 
       visibleWhen: function(item) {
 
       visibleWhen: function(item) {
 
         //return true if this command should be visible for 'item'
 
         //return true if this command should be visible for 'item'
 
       },
 
       },
       callback: function(item, commandId, domId, userData) {
+
       callback: function(commandInvocation) {
         //execute the command
+
         //get the items, etc. from the commandInvocation and 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.
+
The image associated with a command can be defined as a single downloadable image, or as a CSS class to be used as the background for the image (so that image sprites can be used.)
 +
 
 +
The command's callback is executed when the user clicks on the command.  The callback implementation may do the work directly, or it may need to collect some parameters from the user first.  If the latter, it is useful to determine which parameters are required in order for the command to accomplish its work, and which are optional.  Required parameters may be specified in the command.  If they are specified, then the command service will generate a UI for collecting the parameters before the callback is ever called.  For example, the following command specifies that a "name" parameter should be collected before calling the callback:
 +
 
 +
  var newArtifactCommand = new mCommands.Command({
 +
    name: "New Artifact",
 +
    tooltip: "Create a new artifact",
 +
    imageClass: "sprite-new_artifact",
 +
    id: "my.newArtifact",
 +
    parameters: new mCommands.ParametersDescription[new mCommands.CommandParameter('name', 'text', 'Name:', 'New Artifact'], false);
 +
    callback: function(data) {
 +
      var name = data.parameters.valueFor('name');
 +
      if (name) {
 +
        // do some work
 +
      }
 +
    },
 +
    visibleWhen: function(item) {
 +
      item.artifactHolder;
 +
    }});
 +
 
 +
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 data. 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.
 
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.
+
At this point, we've defined a generic edit command, its behavior, and its scope.  Nothing will appear in the UI until we decide to show it on a particular page.  To add a command to 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.
 
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) {
+
  serviceRegistry.getService("orion.page.command").registerCommandContribution("my.command.id", 1);
  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 key bindings or url bindings that should be registered in order to trigger the command. (Note that order is important. If a command has not been added to the command service at the time the contribution is registered, the contribution will be ignored, since no command with the specified id is found).
  
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.
+
After all commands and UI contributions are defined, some code must tell the command service to render the commands. For most Orion pages, the rendering is handled by the various page components. For example, any "global" commands are rendered by the banner code. The toolbar renders commands that are scoped at the "dom" level and use a dom id of "pageActions" or "pageNavigationActions." It figures out which items should be passed to the handler, using the selection service.
  
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 items on 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.
  
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, in the navigator, there are actions that apply to each item in the navigator list. These are "object" level commands, and the navigator renders them in a column for each item in the list. As it renders the command, it specifies the handler (the explorer code) and the individual item to which that rendering applies.
  
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:
+
In some cases, a page organizes commands according to visual "panes" that appear inside the page.  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) {
+
  var commandService = serviceRegistry.getService("orion.page.command");
  commandService.registerCommandContribution("orion.compare.copyToLeft", 1, rightContainerCommands",  
+
commandService.registerCommandContribution("orion.compare.copyToLeft", 1, rightContainerCommands",  
      /* no parent path */ null, new mKeyBinding.KeyBinding("A", true, true));
+
/* no parent path */ null, new mKeyBinding.KeyBinding("A", true, true));
  commandService.registerCommandContribution("orion.compare.nextDiff", 2, "rightContainerCommands");
+
commandService.registerCommandContribution("orion.compare.nextDiff", 2, "rightContainerCommands");
  commandService.registerCommandContribution("orion.compare.prevDiff", 3, "rightContainerCommands");
+
commandService.registerCommandContribution("orion.compare.prevDiff", 3, "rightContainerCommands");
 +
// now render the commands into the dom node using "tool" style.  There are no items to pass to the handler.
 +
commandService.renderCommands("rightContainerCommands", "dom", /* no items */ null, myCompareHandler, "tool");
  
  // 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.
 
See orion.commands.CommandService in the client API reference for documentation about commands, contributions, and rendering.

Revision as of 14:10, 9 December 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. Rather, they provide ways for scripts on each page to contribute links, messages, and commands to the title area, and 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: "Make Favorite",
     image: "/images/makeFavorite.gif",
     id: "my.command.id",
     visibleWhen: function(item) {
       //return true if this command should be visible for 'item'
     },
     callback: function(commandInvocation) {
       //get the items, etc. from the commandInvocation and execute the command
     })
   });
 });

The image associated with a command can be defined as a single downloadable image, or as a CSS class to be used as the background for the image (so that image sprites can be used.)

The command's callback is executed when the user clicks on the command. The callback implementation may do the work directly, or it may need to collect some parameters from the user first. If the latter, it is useful to determine which parameters are required in order for the command to accomplish its work, and which are optional. Required parameters may be specified in the command. If they are specified, then the command service will generate a UI for collecting the parameters before the callback is ever called. For example, the following command specifies that a "name" parameter should be collected before calling the callback:

 var newArtifactCommand = new mCommands.Command({
   name: "New Artifact",
   tooltip: "Create a new artifact",
   imageClass: "sprite-new_artifact",
   id: "my.newArtifact",
   parameters: new mCommands.ParametersDescription[new mCommands.CommandParameter('name', 'text', 'Name:', 'New Artifact'], false);
   callback: function(data) {
     var name = data.parameters.valueFor('name');
     if (name) {
       // do some work
     }
   },
   visibleWhen: function(item) {
     item.artifactHolder;
   }});

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

At this point, we've defined a generic edit command, its behavior, and its scope. Nothing will appear in the UI until we decide to show it on a particular page. To add a command to 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").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 key bindings or url bindings that should be registered in order to trigger the command. (Note that order is important. If a command has not been added to the command service at the time the contribution is registered, the contribution will be ignored, since no command with the specified id is found).

After all commands and UI contributions are defined, some code must tell the command service to render the commands. For most Orion pages, the rendering is handled by the various page components. For example, any "global" commands are rendered by the banner code. The toolbar renders commands that are scoped at the "dom" level and use a dom id of "pageActions" or "pageNavigationActions." It figures out which items should be passed to the handler, using the selection service.

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 items on 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, in the navigator, there are actions that apply to each item in the navigator list. These are "object" level commands, and the navigator renders them in a column for each item in the list. As it renders the command, it specifies the handler (the explorer code) and the individual item to which that rendering applies.

In some cases, a page organizes commands according to visual "panes" that appear inside the page. 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:

var commandService = serviceRegistry.getService("orion.page.command");
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 "tool" style.  There are no items to pass to the handler.
commandService.renderCommands("rightContainerCommands", "dom", /* no items */ null, myCompareHandler, "tool");


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"
  });

Back to the top