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