Ubiquity prides itself on not only making it easy for the average user to understand how ubiquity works, but also for making it easy for command authors to enhance it – and for good reason. Anyone should be able to write a simple command, to make their day just a little less tedious, just a little more efficient.

How it used to be

Now, making a search command has been very easy for a while, thanks to the excellent work of a handful of the core devels. To show how simple it has been, I’ll develop a command to search our own trac, and use this process to illustrate the recently added features.

First thing we do, is head over to Trac and do a search to see where it takes us. This url is quite human readable:
https://ubiquity.mozilla.com/trac/search?q=example
We can then create the search command with this simple code:

CmdUtils.makeSearchCommand({
  name: "Trac",
  url: "https://ubiquity.mozilla.com/trac/search?q={QUERY}",
  icon: "https://ubiquity.mozilla.com/trac/chrome/common/trac.ico",
  description: "Searches Trac for your words."
});

and that would work just fine. Go ahead, try it – just paste it into your command editor (note: wordpress is refusing to let me link this, so here you go instead: chrome://ubiquity/content/editor.html .) Now just bring up ubiquity and type “Trac example” and hit enter – you should end up at the same place as the link above.

Here is a screenshot of how it looks:

Screenshot of simple Trac search

“But what about a decent preview of the results?”, I hear you cry, “like the one the google search has, or wikipedia – you can even navigate it by using your keyboard!”. Well here’s the thing – those aren’t that simple to do. The more technically inclined can take a look at how it’s done here (note: you have to view source.)

As if this hurdle wasn’t enough – we should also be thinking about standardizing the way search commands look and feel. This is key in user experience: consistency.

Easy does it

Instead of having the user write a lot of semi-redundant javascript each time he or she wants to make a search command, or indeed at all, it is now possible to pass a simple parser argument to makeSearchCommand which makes Ubiquity do all the hard work for you – now doesn’t that sound nice?

The argument is called parser, and is an array of options: (note: this feature has only recently landed in hg, so you’ll have to run either ubiquity from source, or wait till version 0.1.7 or 0.2pre14, which will almost certainly include this feature)

container

a jQuery selector that can help you narrowing in your search for the actual results on the page

title

a jQuery selector that will match each of the titles in the results

preview

same as above, except it will match the preview data returned by the search engine (if left out, only titles will be previewed)

baseurl

a string prepended to the link in the title (should only be passed if the search engine returns relative paths)

Finding the right jQuery selectors to pass is still a bit more technical than what might be expected of the average user, and we hope to alleviate that problem sometime in the future, perhaps with a neat UI that helps you pick out the titles and previews with a simple mouseclick. For now though, let’s settle for this and move on with the demonstration.

For Trac, where the HTML is fairly clean, finding the right values was a breeze, and for the avid reader wanting to try this out for themselves, I recommend using Firebug along with its “inspect” feature.

As soon as we pass the parser option to makeSearchCommand like so:

CmdUtils.makeSearchCommand({
  name: "Trac",
  url: "https://ubiquity.mozilla.com/trac/search?q={QUERY}",
  icon: "https://ubiquity.mozilla.com/trac/chrome/common/trac.ico",
  parser: {container: "dl#results",
           title: "dt",
           preview: "dd.searchable",
           baseurl: "https://ubiquity.mozilla.com"},
  description: "Searches Trac for your words."
});

Will do a pretty good job of emulating all that hard work that would otherwise have gone into creating the preview. Again just paste the above into your command editor, or simply insert the parser argument by hand.
This is a screenshot of the new behaviour:

Trac search with preview

Of course in the future, this might very well be improved upon, better looking template, better error-handling, there are lots of potential improvements out there. And that is where I leave you – with the freedom to play around with this cool new feature, and the opportunity to help evolve this beyond its current state, and hopefully towards something better for everyone. The easiest way to do this is to try it out on your favourite sites, and report back here any bugs or shortcomings you may find.