Orion/Documentation/Developer Guide/Plugging into the shell

Overview of contributing services to the Shell page

The Shell page provides a view through which users can interact with Orion via a command-line interface. The page provides some basic commands for navigating Orion's workspace, and defines a service that allows plug-ins to contribute additional commands.

orion.shell.command

The orion.shell.command service is used to contribute commands to the Shell page. When the service is executed, an object containing the user-supplied argument values is passed to the service's callback method. The command then optionally returns a response (a return value) to be displayed in the Shell.

Service methods

Implementations of orion.shell.command may define the following function:

callback(args)

Takes the user-supplied command-line arguments (if any) as an argument, and optionally returns an HTML response string.

The only context where a contributed command would not define a service method is to assist with the contribution of sub-commands. For example, to contribute commands "tar create" and "tar extract", a parent command "tar" without a service method must first be contributed.

Service attributes

Implementations of orion.shell.command define the following attributes:

name

The name that is typed at the command line to invoke the command

description

(Recommended) A brief description of the command

manual

(Optional) A longer description of the command

parameters

(Optional) An array of the parameters that the command accepts

The Shell page currently uses GCLI as its underlying shell widget, and consequently has adopted its syntax for parameter specification. For details on this syntax begin reading at the "## Default argument values" header in the GCLI Writing Commands doc. The basic parameter object attributes are:

name

The parameter's identifier

type

One of { string | boolean | number | array | selection | deferred }

description

(Recommended) A brief description of the parameter

defaultValue

(Optional) The value assumed by the parameter if the user does not supply a value for it, makes the parameter optional

Example

The following sample plug-in contributes an "echo" command to the Shell:

 var serviceImpl = {
   callback: function(args) {
     return "<b>" + args.string + "<\/b>";
   }
 };
 var serviceProperties = { 
   name: "echo",
   description: "Echo a string",
   parameters: [{
     name: "string",
     type: "string",
     description: "The string to echo back"
   }]
 };
 var provider = new eclipse.PluginProvider();
 provider.registerServiceProvider(
   "orion.shell.command",
   serviceImpl,
   serviceProperties);
 provider.connect();

When this plug-in is installed the user can use the "echo" command in the Shell. In the first image shown below a user is in the process of entering an echo command.

In the following image the echo command has executed and its result is shown in the output area.