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.
I for one am happy for this change, but as you say improvements can be made. Here’s one:
The first thing that came to mind is an easy way to modify the {QUERY}, for instance with a command I’m developing one would enter “jump macbook cases” and the generated url should look like “http://www.jump.co.za/search/macbook+cases”. So somewhere along the line the spaces in the {QUERY} need to be replaced with +s, I see in the Ubiquity Code Documentation that it is possible, but a simplified solution would be nice, a function or perhaps replace:” “, with:”+”.
Otherwise I give three thumbs up (I keep a spare in my pocket).
Nice!
It would be interesting adding to makeSearchCommand the option doing a POST (not only a GET).
(with 0.2pre13 I don’t see any preview, execute is correct)
Thanks for explaining internal details.
@Wahooney
The +s are actually not needed (but are often used to make it easier for people for link (try pasting a link containing spaces into anywhere that auto-generates links from urls) – but the link actually works just fine without it.
@Alberto Santini
POST would indeed be a good idea, and there’s really no reason not to include it – in fact I’ve just written the code needed to do this, only problem is that we depend on CmdUtils.previewGet and there’s no POST equivalent (yet)
On a side note, as I said in the article: this was very recently added, so the parser argument will first be supported in 0.2pre14 and 0.1.7 – execute is (untill the POST-support lands) unaffected.
POST support was pushed in http://ubiquity.mozilla.com/hg/ubiquity-firefox/rev/5d63a9af1de0 – feel free to test it out and report back
[...] Geeks By Nature because we just can’t help it… « Making a search command – the easy way! [...]
[...] of updates is in order. Some of the changes I’ll mention here affect the previous articles: Making a search command – the easy way! and Making a search command – part 2, so if you’ve read them: read this one [...]
i tried to use makeSearchCommand to create command with post parameters, but it added a question mark before the parameter and doesn’t worked because of it.
when i look (with firebug and yslow) on the post parameters when i did manual search there wasn’t a question mark, and when i searched with my command it was a question mark.
what can i do to solve this problem?
thanks.
gilad.
Hi, I’m trying to create a search command for urbandictionary.com. I’m pretty sure it should look like:
CmdUtils.makeSearchCommand({
name: "urbandictionary",
url: "http://www.urbandictionary.com/define.php?term={QUERY}",
icon: "http://www.urbandictionary.com/favicon.ico",
parser: {container: "tbody",
title: "td.index",
preview: "td.definition"},
description: "Searches http://www.urbandictionary.com"
});
but I cannot get what I expect :-/
Some tips? I really need to understand how to create GET/POST search commands that use preview. Thanks
@gilad I’m pretty sure this got fixed some time ago – can you confirm that it is not an issue in the latest development version?
@harmen it looks to me like you are using the parser parameter as it is described in the above document, however, since then it has changed a lot – and most of those changes are described in the two following articles on this blog (there are other changes too though, but none should break anything – they are all just added features)
Now, urbandictionary is not an ideal place to start when you want to learn, because their markup does not group result-data (which would otherwise make parsing much more reliable), and moreover, it’s not really a search page, so the fact that no result is less than ideal (activating a result will get you a page load error)
Still, for the preview alone, this will do what you want:
CmdUtils.makeSearchCommand({
name: “urbandictionary”,
url: “http://www.urbandictionary.com/define.php?term={QUERY}”,
parser: {title: “td.word”, preview: “td.text”}
});
@christian
Thank you a lot! It works like a charm! I’d like to add tons of new search command. They are useful for my daily job. Some of them use POST method and/or give back messy html. Can you point me to some docs about using that parser in the right way and taking advantage of all its feature?
Thanks again,
hamen
@harmen
Well, aside from reading the docs for makeSearchCommand (this link should take you to your local copy: chrome://ubiquity/content/file.html#index.html#modules/cmdutils.js ) I’d advise you to read the two follow-up articles to this one: http://geeksbynature.dk/?p=24 and http://geeksbynature.dk/?p=30 (the last one has a part called “This is the part that broke your commands”, and skipping that would be unwise
If you run into a situation where the preview you want is not available as anything selectable in the result-page, you can (provided you run a very recent development version) supply a function to preview instead of a string selector, and this will get a single argument, namely the container of the entire result – this of course means that it will only work if you provide a container that groups the result-data. I only just recently pushed this feature, so it is largely untested – expect bugs and changes to the way it works in the future…
Thank you. I guess I gotta begin to run ubiquity from sources
I hope you find final implementation soon so we can start to heavily develop. Gee, I absolutely need to make quick POST requests and get results in a preview
Too much cool! Thank you for you help and keep on coding