Sunday, November 20, 2011

Linking to the power of Orion

In my last post, I mentioned our Orion command framework, which allows our pages to define the commands that a user can run on a particular page. We were evolving the command definition to include the specification of what parameters it requires.  While I focused more on the UI in the last discussion, now I'd like to talk about how this concept will allow you to link to Orion in interesting ways.

Let's follow a simple example.  One of the things a user can do from the Orion Git Repositories page is clone a git repository into an Orion folder. In the first iteration of the command framework, any work done after the user clicked the "Clone Repository" link was done in the command's callback.

cloneGitRepositoryCommand = new mCommands.Command({
 name : "Clone Repository",
 tooltip : "Clone an existing Git repository to a folder",
 id : "eclipse.cloneGitRepository",
 callback : function(item, commandId, domId, userData) {
  var dialog = new orion.git.widgets.CloneGitRepositoryDialog({
   serviceRegistry: serviceRegistry,
   fileClient: fileClient,
   func: function(gitUrl, path, name) {
     // do the real work
   }});   
  dialog.startup();
  dialog.show();
 }
});

But now we allow the command to specify that it requires a URL parameter. We also indicate that there are additional parameters that can be collected if the user wants to specify additional options. (These snippets are intended to show you how things work, but this interface will certainly change before the next release milestone.)

var cloneParameters = {};
cloneParameters.url = {label: 'Repository URL:', type: 'url'}; 
cloneParameters.options = true;  // indicate that we could collect additional options 

cloneGitRepositoryCommand = new mCommands.Command({
 name : "Clone Repository",
 tooltip : "Clone an existing Git repository to a folder",
 id : "eclipse.cloneGitRepository",
 parameters: cloneParameters,
 callback : function(item, commandId, domId, userData, parameters) {
  if (parameters && parameters.url.value) {
   // do the real work
  } else {
   // we could trigger a dialog to get the parameters, or report an error, etc...
 }
});

So far, we've just defined a command. Nothing is going to show up in the UI until we register a command contribution on a page. In the contribution, we can specify the DOM node where the command should be shown, such as a toolbar, and a key binding that can be used to trigger the same command via the keyboard. But the fun really starts now that we allow a URLBinding to be associated with a command. With a URL binding, a page can define a URL (fragment) query parameter that can be used to trigger command, and the parameter name of any value provided in the URL. For the clone command, the URL binding looks like this.

var urlBinding = new mCommands.URLBinding("cloneGitRepository", "url"));
commandService.registerCommandContribution("eclipse.cloneGitRepository", ..., urlBinding);

This means that the query parameter cloneGitRepository should trigger the command, and the value in the URL should be bound to the url parameter in the command. From Orion's point of view, opening the Git Repositories page with the following link calls the same code as if the user had clicked on the command in the UI and typed in the URL:

http://orion.eclipse.org/git/git-clone.html#/workspace/H?cloneGitRepository=ssh://myId@github.com/path/myId.github.com.git

One important note. A command invoked by a URL binding is not called by this URL. Rather the page is opened in a state for collecting the parameters. We just prefill the parameter information, and the user can hit the Enter key to start the clone, or click the More button to provide additional information. Our URL needs to be a stable GET. Reloading the URL multiple times should never alter the state of the resource on the page. So user intervention is always required in order to actually invoke the command. The URL binding, much like a key binding, simply gives the user a shortcut for starting the process.

We think the URL binding is a powerful concept. It allows us to start exposing linkable bits of function in a way that is completely separate from the code that defines the function. Being able to specify parameters in the URL syntax means that some other site can use its own logic to figure out what the user wants, and then link to an Orion page, providing contextual information.

Our favorite simple example is a bugzilla page that could use the product and component information in the bug definition to figure out which git repository the user might want to clone to look at the code. Another idea is the ability to author "cue card" style help systems that could guide the user through some set of tasks in Orion, simply by linking to the various commands involved in the steps.

We can't wait to see what you might do with this idea.

No comments:

Post a Comment