Ubiquity Command - Dissected

It's easy to create a Ubiquity command by yourself if you know JavaScript. Using Ubiquity command editor, you can start creating new commands such as this:

CmdUtils.CreateCommand({
  name: "ses-login-search",
  takes: {"adc60019fems or adc60037fems": noun_type_ses_url },
  modifiers: {"for": noun_arb_text, "with": noun_arb_text},
  homepage: "http://xteam.us.oracle.com/blogs/index.php?blog=10",
  author: { name: "Stanley Guan", email: "xmlandmore@gmail.com"},
  description: "Search adc60019fems or adc60037fems for keywords" +
     " with given userName/password",
  help: "Search server for keywords with given credentials." +
      "  If server name is not specified, default server will be used." +
      "  Specify credentials with usename and password (in that order) " +
      "  and separate them by space.",
  license: "GPL",
  preview: function(pblock, directObj, mods) {
    var server = directObj.text  createList(sesNicknames);
    var keywords = mods["for"].text  "keywords";
    var creds = mods["with"].text  "userName/password";
    pblock.innerHTML = "search " + server + " for " + keywords +
      " with " + creds;
  },
  execute: function(directObj, mods) {
    // This function gets executed when user hits ENTER.
    // You can have different approaches:
    //  1. Launch a new window to display command output.
    //  2. Replace selection with command output.
  }
});

In the above example, new command is named "ses-login-search" and it takes one direct object and two modifiers. This means that our command should look like this:

ses-login-search (adc60019fems or adc60037fems) for (keywords)
  with (username/password)

Ubiquity command parser supports natural language processing. You can choose verbs as your command names. Now it only supports single-word command names. So, you should use "-" to connect multiple words as we've done here. Our command will allow SES users to login and search at the same time. The direct object of our command is a server name. It can be either "adc60019fems" or "adc60037fems".

To pass more arguments, you can use modifiers. Modifiers are prepositional phrases (i.e., prepositions followed by nouns in English). In our case, we use "for" to specify keywords to be searched for and "with" to provide user's credentials.

Other parts of command include the following properties:

• homepage
• author
• description
• help

These properties are used to compose detailed description of our command on Ubiquity's command list. If our command were subscribed, it could look like this:



Help text provided in "help" property is also displayed in the preview pane when user type "help ses-login-search" in the command entry field as shown below:
As described in Ubiquity's UI Design , preview function is used by command designer to provide preview content (as defined by HTML snippet) to be displayed in the preview pane. For example, if your command is a search command, you can display top-ranked search results here for the user to see. Sometimes, if users find the result they need in the preview pane, they can click on the link and jump directly to the target URL and skip the command execution phase.

If users need to see the full command output, they can execute command (defined by the "execute" property) by hitting ENTER after command is fully specified. Two arguments are passed to "execute" function:

1. directObj (i.e., direct-object)
2. mods (i.e., modifiers)

They contain the command options as specified by the users. To access them, you use:

1. directObj.text for direct-object
2. mods["with"].text or mods["for"].text for modifiers
   

As I say, it's easy to create a new Ubiquity command if you know JavaScript. Hopefully, this post has provided enough information for you to begin with. To view more examples, you can find them from:

1. Commands in the wild
2. Ubiquity Herd