# 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",
         imageClass: "core-sprite-favorite",
         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 CSS data URI's and 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) {
         return 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.

     serviceRegistry.getService("orion.page.command").addCommand(editCommand, "object");

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, parameters, URL bindings, contributions, and rendering.