Another couple of days have passed, so another round 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 too!

This is the part that broke your commands

And in more than one way. If you’ve tried some of the commands before the recent updates, you might have noticed that for some reason, certain queries wouldn’t return any previews, while other would work just fine. This is because some search engines return “strange” results in the middle of the normal results – and only do it sometimes – but the only way the parser knew which titles, previews and thumbnails fit together, was by their index in each of their own lists. This was a very fragile system, and while it it still available as fallback, using it isn’t recommended.

The main difference is that the parameter options.parser.container should no longer select the element that contains all the results, but rather it should select a list containing each result. Each results title, preview and thumbnail will then be found (if available) inside the result, and grouping is no longer dependant on indexes. This means that any given result can have a missing preview or thumbnail, and it won’t affect any of the others.

Obviously, changing the meaning of the parameter means you will have to rewrite any search command you have that uses it. I hope the benefit of stability will outweigh this initial annoyance.

JSON as promised

In my last post, I said I was going to be working on JSON support, and as of about 4 hours ago, initial support has landed in hg. I have successfully rewritten our default google and yahoo commands to use this new system, and still use the JSON API provided by the services, but as I don’t have much experience with this sort of interface, it is entirely possible that I have in some way limited the functionality and thus the compatibility with some services. If this is the case, the JSON support will of course be expanded.

A slight note on the usage is perhaps needed here. Let us take google as an example:

CmdUtils.makeSearchCommand({
  name: "Google",
  url: "http://www.google.com/search?q={QUERY}",
  parser: {type: "JSON",
           url: "http://ajax.googleapis.com/ajax/services/search/web?v=1.0&q={QUERY}",
           container: "responseData.results",
           title: "titleNoFormatting",
           preview: "content",
           href: "url"}
});

First you might notice that there are two fields called url, one outside the parser and one inside. In that order, the first one does exactly what it usually did, except it’s only used if the user presses return to go directly to the search page. The second is the one used for the actual searching if you pass type: "JSON" to the parser. If the API requires you to use POST, this works the same way as you’re used to.

Secondly, if you happen to be uncannily familiar with the structure of the JSON google returns, you might notice that the container parameter I talked about earlier in this very post doesn’t seem to be pointing to each result. Instead, it’s pointing to the container of all the results. If you think about it however, in the HTML-case, jQuery makes sure we are returned a list of results, but in JSON, the parent element holding the results is already a list of results – so it sort of makes sense.

The only other new thing is the addition of the options.parser.href parameter, which was automatically calculated in the HTML version. In JSON, the url is usually held in a separate field, so this is needed to make sure we actually link to the results.

What you can do to speed things up

These changes that break backward compatibility will happen less often – or hopefully not at all – if I get fast feedback and suggestions. The more you complain, the more likely I am to do something about it fast

To try these changes out, run Ubiquity from source, or wait for 0.1.7 or 0.2pre15 where they will most likely be included.