Labs/Ubiquity/Writing A Search Command: Difference between revisions

← Older edit

Labs/Ubiquity/Writing A Search Command (view source)

Revision as of 12:45, 21 March 2010

338 bytes added , 21 March 2010

→‎Documentation of CmdUtils.makeSearchCommand

Satyr

73

edits

@@ Line 1: / Line 1: @@
 {{draft}}
-Author: Christian Sonne
+Author: Christian Sonne, satyr
 == Documentation of CmdUtils.makeSearchCommand ==
@@ Line 122: / Line 122: @@
 === postData ===
-Supplying postData will make Ubiquity use POST instead of GET when retrieving the results. It can be either a string ie: "q={QUERY}&hl=en" or as an object ie:
+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.:
-<code>{"q": "{QUERY}", "hl": "en"}</code>
+* <code>"q={QUERY}&amp;hl=en"</code>
+* <code>{q: "{QUERY}", hl: "en"}</code>
 === parser ===
@@ Line 130: / Line 131: @@
 Via a number of options, you can tell mSC how to parse the data returned by the search provider.
-'''NB:''' all selectors used in the following sections are either paths into the json data in dot-notation, or [http://docs.jquery.com/Selectors 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]]
+All selectors used in the following sections are either paths into the JSON data in dot-notation, or [http://docs.jquery.com/Selectors 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 ====
-mSC supports two types of parsers, namely "json" and "html". If not specified, it assumes you want the html parser.
+Specifies the type of remote data to retrieve. (same as <code>[http://api.jquery.com/jQuery.ajax/ jQuery.ajax()]</code>'s <code>dataType</code> option). If <code>"json"</code> is passed, the parser switches to JSON mode.
-==== url ====
+==== url / postData ====
-Alternative url used in case the preview uses a different service or API than the execute function, ie: "http://ajax.googleapis.com/ajax/services/search/web?v=1.0&q={QUERY}"
+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 html 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".
+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 html parser, all details for each individual result must be contained in each container.
+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 html 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.
+'''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 html 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.
+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. Unless [[#href]] is specified, this needs to match either an anchor, or a parent of an anchor, in which case the first such will be used.
+'''NB:''' This options is required if you use the parser.
-==== preview ====
+==== body ====
-Selector for the preview of the result. If using the html 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 preview.
+Selector for the content of the result.
 ==== href ====
-Selector for the preview of the result. If using the html 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 preview.
+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 preview 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.
+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 ====
+==== 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.
+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 (<code>"title", "body", "href", "thumbnail"</code>) that should be treated as plain text.
+==== log ====
+Function to which the command logs the reponse data and parsed results.
 === Other ===
@@ Line 172: / Line 183: @@
 == Examples ==
-=== The bare essentials ===
+=== The bare essential ===
- CmdUtils.makeSearchCommand({
+<pre>CmdUtils.makeSearchCommand({url:"http://google.com/search?q=%s"})</pre>
-   name: "Google",
-   url: "http://www.google.com/search?q={QUERY}",
- });
-=== Adding a preview ===
+=== Adding preview ===
- CmdUtils.makeSearchCommand({
+<pre>
-   name: "YouTube",
+CmdUtils.makeSearchCommand({
-   url: "http://www.youtube.com/results?search_type=&search_query={QUERY}&aq=f",
+  name: "YouTube",
-   parser: {container: "div.video-entry",
+  url: "http://www.youtube.com/results?search_query={QUERY}",
-            title: "div.video-long-title a",
+  parser: {
-            preview: "div.video-description",
+    container: "div.video-entry",
-            thumbnail: "img.vimg120"}
+    title: "div.video-long-title a",
- });
+    body: "div.video-description",
+    thumbnail: "img.vimg120",
+  },
+});
+</pre>
 === Using the JSON parser ===
- CmdUtils.makeSearchCommand({
+<pre>
-   name: "Google",
+CmdUtils.makeSearchCommand({
-   url: "http://www.google.com/search?q={QUERY}",
+  name: "Google",
-   parser: {type: "JSON",
+  url: "http://www.google.com/search?q={QUERY}",
-            url: "http://ajax.googleapis.com/ajax/services/search/web?v=1.0&q={QUERY}",
+  parser: {
-            container: "responseData.results",
+    type: "json",
-            title: "titleNoFormatting",
+    url: "http://ajax.googleapis.com/ajax/services/search/web?v=1.0&q={QUERY}",
-            preview: "content",
+    container: "responseData.results",
-            href: "url"}
+    title: "titleNoFormatting",
- });
+    body: "content",
+    href: "url",
+    html: ["body"],
+  },
+});
+</pre>
-=== Using functions in the parser ===
+=== Parsing XML / Using functions in the parser ===
- CmdUtils.makeSearchCommand({
+<pre>
-   name: "MovieZoo",
+CmdUtils.makeSearchCommand({
-   url: "http://www.moviezoo.dk/alle-produkter/soeg/{QUERY}",
+  url: "http://wunderground.com/cgi-bin/findweather/getForecast?query=%s",
-   parser: {
+  parser: {
-     container: "table.nyhedsbrev_tabel2",
+    type: "xml",
-     title: "tr:nth-child(2) tr tr:first-child b",
+    url: "http://api.wunderground.com/auto/wui/geo/ForecastXML?query=%s",
-     href: function(c) {return jQuery("a.nyhedsbrev",c).attr("href");},
+    container: "simpleforecast > forecastday",
-     preview: function(c) {var p = ""; jQuery("table table tr:not(:first)",c).each(function(){p += jQuery(this).text()+"<br>";});return p;},
+    title: "pretty",
-     thumbnail: "img.lister_img",
+    body: function() $("<div>").append(
-     maxResults: 3
+      $("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",
+    }),
+  },
+});
+</pre>
 === Searching with a different charset ===
- CmdUtils.makeSearchCommand({
+<pre>
-   names: ["video.baidu", "百度视频"],
+CmdUtils.makeSearchCommand({
-   url: "http://video.baidu.com/v?word={QUERY}",
+  names: ["video.baidu", "百度视频"],
-   charset: "gb2312",
+  url: "http://video.baidu.com/v?word={QUERY}",
-   parser: {
+  charset: "gb2312",
-     container: "#result td",
+  parser: {
-     title: ".r a",
+    container: "#result td",
-     thumbnail: "img",
+    title: ".r a",
-     maxResults: 20,
+    thumbnail: "img",
-   },
+    maxResults: 20,
- });
+  },
+});
+</pre>