Yelling with Ubiquity

"yell" with ubiquity to find local businesses in the UK. This command performs extends ubiquity's ability to execute searches on the UK yellow pages directory - yell.com. In this post, we also dissect the command to learn how it's done.

To use it, simply visit my live commands page and click on subscribe button when presented with the option (you need to have Mozilla Ubiquity addon installed). Here's a brief explaination of the process. If you dont see the button, then either you dont have ubiquity installed or you are already subscribed to my commands. If so, Firefox should automatically pick up my new commands the next time you restart it.

For those of you who came here for more information on writing commands, this post is a continuation of my previous post. If you came here first, I would recommend looking at it for some basic scripts.

If you've already done that, let's move on!

Moving beyond the basic search.
It took me a better part of the hour to make. But with the learnings, I think I should be able to build the next one far quicker. The commands in the first post were simply able to accept search terms. For example,

search-scholar Okazhaki fragments

In here, the command is 'search-scholar', whereas the rest is search string (i.e. Okazhaki fragments). This works when you have simply one search box like most of google searches. But the next step is to get it to work with searches that have more than one criteria.

Analyzing our target website.
Yell.com, for instance has three (see screenshot). The first one is required. The remaining two are optional.

Before we start scripting away, let's look at what the actual search looks like. For instance, searching for "florists" located in "nw1" results in the following query string:

http://www.yell.com/ucs/UcsSearchAction.do?ssm=0&scrambleSeed=91142386&keywords=florists&companyName=&location=nw1&x=0&y=0&M=0

The part hightlighted is of our interest. Remove the field-value pairs which are empty values or contain values that we did not type in. The URL should now look like:

http://www.yell.com/ucs/UcsSearchAction.do?keywords=florists&companyName=&location=nw1

For the newbies, I've highlighted the field-value pairs. *Always* test this before you move on! Happily, this seems to work and does not seem to affect the search results in anyway. I've specifically left the companyName field on for now. We will look at that later.

This tell us, that whatever we put in

• "Search for" box goes comes up against the "keyword" field
• "Company name" box comes up against the "companyName" field and
• ""Located in" box comes up against the "location" field
  

Decide what your ubiquity command should look like
This means our ubiquity command should look like

yell {keyword} named {company name} in {Located in}

Make it a point to make it as obvious as possible.

The basic search script
So let's get scripting!! Based on my previous post, had this been a single box search the script would have look like

makeSearchCommand({
name: "yell",
url: "http://www.yell.com/ucs/UcsSearchAction.do?keywords={QUERY}",
icon: "http://www.yell.com/favicon.ico",
description: "Searches Yell.com for your words."
});

Fairly obvious? To test this, copy-paste the above in your ubiquity command editor and try it out. So we are happy that the basic search works.

The second search criteria
Now comes the new part - adding optional parameters. For now, lets just take the "Location" box. We want to make our ubiquity command do

yell florists in birmigham

So, we make the following changes to the above script

CmdUtils.CreateCommand({
name: "yell",
icon: "http://www.yell.com/favicon.ico",
description: "Searches Yell.com for your words.",
takes: {"keywords": noun_arb_text},
modifiers: {"in": noun_arb_text}
});

The changes are highlighted in yellow. Since our command has now moved beyond the basics, we need to change over to using the helper function CreateCommand(). The other two changed lines let's us define custom arguments to our "yell" command (see: Commands with arguments). The argument names are highlighted in blue. Chose these carefully as these are strings that the end-user sees. If you now copy-paste the above script your ubiquity command editor (remember to overwrite the previous script) and try using the command without any parameters, ubiquity should now show you the following:

yell (keywords) (in text)

Now, we change our script as shown below

CmdUtils.CreateCommand({
name: "yell",
icon: "http://www.yell.com/favicon.ico",
description: "Searches Yell.com for your words.",
takes: {"keywords": noun_arb_text},
modifiers: {"in": noun_arb_text},

execute: function( keywords, modifiers ) {

var msg = keywords.text + ' and ' + modifiers.in.text;
/* Show what we've got */
displayMessage( msg );
}

});

As before, the changes are highlighted in yellow. This bit took me a little while to understand. In ubiquity scripting you can pass functions as arguments to other function. In this case, we are calling the function CreateCommand() and we are defining the argument (named) "execute" to be a function as well. We are also specifying that this function will have two input objects as arguments named keywords and modifiers. The rest is simple, we are simply putting together the values and displaying a ubiquity notification message.

If you now copy-paste the above script your ubiquity command editor (remember to overwrite the previous script) and try ubiq-ing the following command:

yell florists in birmingham

You should see a ubiquity notification with the text "florists and birmigham". I feel I must mention that you may have noticed that both the command arguments are defined as noun_arb_text. This means that both the arguments can contain arbitirary text. So the command can also look like

yell Indian restaurants in UB1 6LE

Executing this will give you a ubiquity notification with the text "Indian restaurants and UB1 6LE".

Tying it all together
We are nearly done! We make a final modification to our script to tie it all together:

CmdUtils.CreateCommand({
name: "yell",
icon: "http://www.yell.com/favicon.ico",
description: "Searches Yell.com for your words.",
takes: {"keywords": noun_arb_text},
modifiers: {"in": noun_arb_text},
execute: function( keywords, modifiers ) {
var strKeyWords = keywords.text;
var strLocation = modifiers.in.text;

/* Put together our search URL */
var strURL = "http://www.yell.com/ucs/UcsSearchAction.do?keywords=" +
strKeyWords +
"&companyName=&location=" + strLocation;
/* Open the URL in a new window or tab */
Utils.openUrlInBrowser( strURL );
}
});

As before, the changes are highlighted in yellow. Since we are now able to get hold of, both the keywords and the location, it is only a matter of putting together the search url we discussed above. And to finish, open the url in a new tab or window using the help function Utils.openUrlInBrowser(). That's it!!

If you now copy-paste the above script your ubiquity command editor (remember to overwrite the previous script) and try ubiq-ing the following command:

yell Indian restaurants in UB1 6LE

You should see firefox open a new window or tab with search results at yell.com. To make sue you've understood this, modify to command so that the command can now take the form

yell Indian restaurant named Taj in North London

Add a few checks, and you should have a neat looking script ready for distribution :-) To see my finished version, feel free to look at the source code here.

Questions? Problems? Did i make a mistake? Ideas? Leave me a comment.