Labs/Ubiquity/Writing A Search Command

	THIS PAGE IS A WORKING DRAFT
	The page may be difficult to navigate, and some information on its subject might be incomplete and/or evolving rapidly. If you have any questions or ideas, please add them as a new topic on the discussion page.

Author: Christian Sonne, satyr

Documentation of CmdUtils.makeSearchCommand

In the rest of this document, we will refer to makeSearchCommand as "mSC".

name/names

The name(s) of the search command, ie: name: "Youtube" or names: ["Youtube", "Video"]

url

The url of the search provider, with the string "{QUERY}" (without the quotes representing the search word, ie: "http://www.google.com/search?q={QUERY}". If the provider uses POST instead of GET, see #postData.

defaultUrl

An optional url string that will be opened in the case where the user has not provided a search string.

icon

The icon used for the search command. If not provided, the favicon (favicon.ico) located at the root of the search providers domain will be used instead.

description

A description of your search command. If not provided, one will be generated from a localized template and the name of your search command.

preview

An optional preview string or function that can be used to display results in the Ubiquity preview. For more info see Labs/Ubiquity/Ubiquity_0.5_Author_Tutorial#Adding_a_Preview

To provide a consistent search experience, mSC can generate a preview for you with minimal work on your part. For more information on this, see #parser. If you leave out both preview and parser, the provided or generated description will be used instead.

charset

If your intended input and response cannot be represented properly by UTF-8, you can provide the required charset as a string. It must be a charset supported by nsIScriptableUnicodeConverter which means one of:

postData

Supplying postData will make Ubiquity use POST instead of GET when retrieving the results. It can be either a string or an object. i.e.:

• "q={QUERY}&hl=en"
• {q: "{QUERY}", hl: "en"}

parser

The parser makes it easy for you as a developer to provide an interactive preview with search results, consistent with other Ubiquity search commands.

Via a number of options, you can tell mSC how to parse the data returned by the search provider.

All selectors used in the following sections are either paths into the JSON data in dot-notation, or jQuery selectors. Note that the latter are NOT CSS selectors albeit very similar. Some features you might be used to from CSS are missing, whilst others still are added. Which you should use depend on your choice of #type.

Each selector can alternatively be a function that receives its context and returns the expected result for each mode.

• jQuery mode: jQuery object
• JSON mode: String if #container is specified. Object/Array otherwise.

type

Specifies the type of remote data to retrieve. (same as jQuery.ajax()'s dataType option). If "json" is passed, the parser switches to JSON mode.

url / postData

Alternative URL and/or POST Data used in case the preview uses a different service or API than the execute function. i.e.: "http://ajax.googleapis.com/ajax/services/search/web?v=1.0&q={QUERY}"

container

If using the jQuery parser, this must be a selector that matches each result, thus returning a list of result containers. When using the json parser it must match the parent of all the results, ie: "responseData.results".

It is important to note that in the case of the jQuery parser, all details for each individual result must be contained in each container.

NB: Whilst this is not strictly speaking a required option for the jQuery parser, it is highly recommended that you use it. If not present, mSC will attempt to consolidate the lists of titles, previews and thumbnails into individual results as best it can, but it is a much more fragile method of parsing.

title

Selector for the title of the result. If using the jQuery parser, it can alternatively be a function that receives a single argument (the jQuery result object) and must return a string that will be used as title.

NB: This options is required if you use the parser.

body

Selector for the content of the result.

href

Selector for the URL of the result.

NB: This option can usually be left out. If not present, mSC will attempt to find an anchor in the result matched by the #title option.

thumbnail

Selector for the thumbnail image of the result. If this does not match an image element, mSC will look for a child element that is an image, and use the first found as thumbnail.

maxResults

Integer specifying the maximum number of results displayed in the Ubiquity preview. If not specified, it will default to 4.

baseUrl

String used as base URL if #href and/or #thumbnail's src is found to be relative. If not provided, #url will be used instead.

plain

Array of strings naming selector properties ("title", "body", "href", "thumbnail") that should be treated as plain text.

log

Function to which the command logs the reponse data and parsed results.

Other

mSC passes on the options it gets to CmdUtils.CreateCommand, so most options not mentioned here but available in CreateCommand can be passed as well. Most notably are the meta data documented in Labs/Ubiquity/Ubiquity_0.5_Author_Tutorial#Documentation_and_Metadata.

Examples

The bare essential

CmdUtils.makeSearchCommand({url:"http://google.com/search?q=%s"})

Adding preview

CmdUtils.makeSearchCommand({
  name: "YouTube",
  url: "http://www.youtube.com/results?search_query={QUERY}",
  parser: {
    container: "div.video-entry",
    title: "div.video-long-title a",
    body: "div.video-description",
    thumbnail: "img.vimg120",
  },
});

Using the JSON parser

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",
    body: "content",
    href: "url",
    html: ["body"],
  },
});

Parsing XML / Using functions in the parser

CmdUtils.makeSearchCommand({
  url: "http://wunderground.com/cgi-bin/findweather/getForecast?query=%s",
  parser: {
    type: "xml",
    url: "http://api.wunderground.com/auto/wui/geo/ForecastXML?query=%s",
    container: "simpleforecast > forecastday",
    title: "pretty",
    body: function() $("<div>").append(
      $("conditions", this), "<br/>",
      $("<b>", {
        text: $("low > celsius", this).text() + "\u2103",
        style: "color:#66f",
      }),
      " \uFF5E ",
      $("<b>", {
        text: $("high > celsius", this).text() + "\u2103",
        style: "color:#f66",
      })),
    thumbnail: function() $("<img>", {
      src: "http://icons-pe.wxug.com/i/c/a/" + $("icon", this).text() + ".gif",
    }),
  },
});

Searching with a different charset

CmdUtils.makeSearchCommand({
  names: ["video.baidu", "百度视频"],
  url: "http://video.baidu.com/v?word={QUERY}",
  charset: "gb2312",
  parser: {
    container: "#result td",
    title: ".r a",
    thumbnail: "img",
    maxResults: 20,
  },
});