Difference between revisions of "Orion/Documentation/Developer Guide/Plugging into the shell"

From Eclipsepedia

Jump to: navigation, search
(initial)
 
(finish Console -> Shell updates)
Line 67: Line 67:
  
  
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.
+
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, and is shown a hint that argument "string" (the string to echo) is expected.
  
[[Image:orion-shell-command-example1.png]]
+
[[Image:orion-shell-command-example1.jpg]]
  
  
 
In the following image the echo command has executed and its result is shown in the output area.
 
In the following image the echo command has executed and its result is shown in the output area.
  
[[Image:orion-shell-command-example2.png]]
+
[[Image:orion-shell-command-example2.jpg]]

Revision as of 22:09, 2 October 2012

Contents

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, and is shown a hint that argument "string" (the string to echo) is expected.

Orion-shell-command-example1.jpg


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

Orion-shell-command-example2.jpg