Jump to: navigation, search

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

(Service methods)
(2 intermediate revisions by 2 users not shown)
Line 1: Line 1:
= Overview of contributing services to the Shell page =
+
= Overview of contributing services to the Shell =
  
 
The <b>Shell</b> 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.
 
The <b>Shell</b> 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.
Line 12: Line 12:
  
 
;callback(args)
 
;callback(args)
: Takes the user-supplied command-line arguments (if any) as an argument, and optionally returns an HTML response string.
+
: Takes the user-supplied command-line arguments (if any) as an argument, and optionally returns a response string in plain text (no HTML is allowed).
  
 
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.
 
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.
Line 44: Line 44:
 
The following sample plug-in contributes an "echo" command to the Shell:
 
The following sample plug-in contributes an "echo" command to the Shell:
 
<pre>
 
<pre>
 +
<html>
 +
<head>
 +
<script src="http://orionhub.org/orion/plugin.js"></script>
 +
<script>
 
  var serviceImpl = {
 
  var serviceImpl = {
 
   callback: function(args) {
 
   callback: function(args) {
     return "<b>" + args.string + "<\/b>";
+
     return "'" + args.string + "'";
 
   }
 
   }
 
  };
 
  };
Line 58: Line 62:
 
   }]
 
   }]
 
  };
 
  };
  var provider = new eclipse.PluginProvider();
+
  var provider = new orion.PluginProvider();
 
  provider.registerServiceProvider(
 
  provider.registerServiceProvider(
 
   "orion.shell.command",
 
   "orion.shell.command",
Line 64: Line 68:
 
   serviceProperties);
 
   serviceProperties);
 
  provider.connect();
 
  provider.connect();
 +
</script>
 +
</head>
 +
</html>
 
</pre>
 
</pre>
  

Revision as of 15:15, 1 November 2012

Overview of contributing services to the Shell

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 a response string in plain text (no HTML is allowed).

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:

<html>
<head>
<script src="http://orionhub.org/orion/plugin.js"></script>
<script>
 var serviceImpl = {
   callback: function(args) {
     return "'" + args.string + "'";
   }
 };
 var serviceProperties = { 
   name: "echo",
   description: "Echo a string",
   parameters: [{
     name: "string",
     type: "string",
     description: "The string to echo back"
   }]
 };
 var provider = new orion.PluginProvider();
 provider.registerServiceProvider(
   "orion.shell.command",
   serviceImpl,
   serviceProperties);
 provider.connect();
</script>
</head>
</html>


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