(Classic) annotate()

annotate_search_results(<selector_func>)

annotate_local_search_results(<selector_func>)

KNS includes two actions that annotate search results. These two methods provide a mechanism to annotate search results on Google, Bing, and Yahoo.

Selector Function

These methods take the name of a javascript method that inspects each search result and returns the html for annotation. If no annotation is desired, return false and no annotation will be performed. The annotation method is called once for each search result, and is provided as an argument the DOM element of the search result for your evaluation. You can inspect the DOM element to evaluate the search result, and we also provide common data in a universal way. We recommend using these methods (shown in the example below) instead of extracting the same data yourself.

emit <<
function my_select(obj) {
  var domain = $K(obj).data("domain");
  var url = $K(obj).data("url");
  if(domain === "www.baconsalt.com") {
     return "<span>Good Food!</span>";
  } else {
    false;
  }
}
>>;
annotate_search_results(my_select);

The extracted data includes domain and url, and for local search results, includes a phone number and height of the element as well. The following example is a basic use of local search annotation.

emit <<
function my_select(obj) {
  var domain = $K(obj).data("domain");
  var url = $K(obj).data("url");
  var height = $K(obj).data("height");
  var phone = $K(obj).data("phone");
  if(phone === "8015551212") {
     return "<span>Call for Information!</span>";
  } else {
    false;
  }
}
>>;
annotate_local_search_results(my_select);

emit <<
function my_select(obj) {
  var domain = $K(obj).data("domain");
  var url = $K(obj).data("url");
  var o = mydataset[domain];
  if(o) {
     return "<span>Found in Dataset!</span>";
  } else {
    false;
  }
}
>>;
annotate_search_results(my_select);

Remote Data

In addition to an annotation method, you can perform a call to a remote service. This is helpful when using a very large dataset because the call is made after the page has loaded and the results are available. The remote data store is queried and passed information about the results that can be used to return specific annotation.

The downside of using remote data is that the data query happens after the page is loaded. Experience indicates that the user experience is quite good as long as the remote data store responds quickly. 

To use a remote dataset, do not provide a select function and use the remote option providing the URL of the remote data service.

annotate_search_results() with remote = "http://example.com/myservice?jsoncallback=?";

The service will be called providing information about search results, and the returned data will be used to perform annotations. The call is made using JSONP, and the service you call will need to respond in the appropriate way. An example of the call is provided below.

Note the json callback argument, and how it is used in the response. The callback takes the form

example.com/myservice?jsoncallback=?

KRL automatically replaces the '?' with a random method name that doesn't clash with the global scope. You do not have to specify the method name yourself.

http://example.com/myservice?jsoncallback=jsonp1260388341360&_=1260388347593&annotatedata=%7B%22KOBJ1%22%3A%7B%22url%22%3A%22http%3A%2F%2Fwww.cheese.com%2F%22%2C+%22domain%22%3A%22www.cheese.com%22%7D%2C+%22KOBJ3%22%3A%7B%22url%22%3A%22http%3A%2F%2Flive.gnome.org%2FCheese%22%2C+%22domain%22%3A%22live.gnome.org%22%7D%2C+%22KOBJ5%22%3A%7B%22url%22%3A%22http%3A%2F%2Ftwitter.com%2Fkethoi%22%2C+%22domain%22%3A%22twitter.com%22%7D%2C+%22%7D%7D

The annotatedata argument is a URL encoded JSON struct with the available extracted data. The unencoded version of the data in the above URL is below.

{
  "KOBJ1":{"url":"http://www.cheese.com/", "domain":"www.cheese.com"},
  "KOBJ2":{"url":"http://en.wikipedia.org/wiki/Cheese", "domain":"en.wikipedia.org"},
  "KOBJ3":{"url":"http://live.gnome.org/Cheese", "domain":"live.gnome.org"}
}

This GET request should return info about any results it wishes to annotate, in the following form:

jsonp1260388341360({"KOBJ3":"Annotate This!"});

Only elements needing an annotation should be returned. The String provided is HTML, and can include images or links.

When using remote data, you may see more then one call to your service for each page of results. Multiple requests are made when the required data cannot be encoded in a single request without exceeding URL length limitations.

You can also annotate search results with a remote datasource and a Javascript decorator function, the following is an example.

rule annotate_remote_decorator is active {
 
       emit <<
 
      function selector(data) { // data is the data returned by your remote data/script
               return data + "Extra annotation stuff"; 
     }
 
       >>
       annotate_search_results(selector) with remote = "http://www.example.com/path/to/script";
}
 

Annotation Options

The search annotation methods have the following options that can be used to modify default behavior. Options are specified using the withsyntax, as shown in the examples.

• name - (defaults to "KOBJ") - changing the name creates a "new" annotation box. Annotation with the same name are grouped together.
• sep - (defaults to "<div style='padding-top: 13px'>|</div>") - the separation element
• text_color - (defaults to "#CCC") - the default text color
• height - (defaults to "40px") - the height of the annotation div
• left_margin - (defaults to "15px") - the left margin in between the annotation and the result
• right_padding - (defaults to "15px") - right padding
• font_size - (defaults to "12px") - default font size
• font_family - (defaults to "Verdana, Geneva, sans-serif") - default font
• tail_image - (defaults to null) - background image for end of the annotation box
• head_image - (defaults to null) - background image for start of the annotation box
• placement - (defaults to prepend) - specifies how the annotation is placed relative to the element_to_modify. Valid values are:
  • prepend - make the annotation the first child of the element_to_modify.
  • append - make the annotation the last child of the element_to_modify.
  • before - make the annotation the sibling before the element_to_modify.
  • after - make the annotation the sibling after the element_to_modify.

An example call with options is shown below.

annotate_search_results(my_selector)
  with name = "myappannotation" and
       head_image = "http://example.com/headimage.png" and
       tail_image = "http://example.com/tailimage.png";

The following options are deprecated, and should be removed from use as soon as possible. Their functionality has been replaced as shown in the next section.

• results_lister - (defaults to "li.g, div.g, li div.res, #results>ul>li") - jQuery selector for finding relevant results to annotate. The default finds search results for Google, Yahoo, and Bing.
• element_to_modify - (defaults to "div.s,div.abstr,p") - the jQuery selector for finding the element to modify within the results returned by the result lister. The default finds the main body of a search result.

Annotating Additional Websites

You may wish to use Search annotation on sites that are not natively supported by the annotation actions. You can extend this functionality onto other websites or customize existing sites by use of the domains option.

annotate_search_results(my_selector)
  with domains = {"www.ebay.com": { "selector": ".lview.nol",
                                    "modify": "#anchors",
                                    "watcher": "",
                                    "urlSel": ".v4lnk" } };

Advanced CSS Customization

Search annotation can be customized using advanced CSS options. Local search results are not presented in a wrapper, so these options do not apply.

The structure of an annotation consists of list elements inside an unordered list inside an inner div which is inside an outer div. This structure allows for multiple annotations to exist without interfering with each other and allows the head and tail image treatment described above. For example:

annotate_search_results(my_selector)
  with inner_div_css = {"height" : "25px"} and
       placement = "after";

The following options use literal hashes to specify CSS properties that will be attached to each of the elements that make up an annotation (values in angle brackets represent variables set from the option values given above):

 {
 "float": "right",
 "width": "auto",
 "height": <height>,
 "font-size": <font_size>,
 "line-height": "normal",
 "font-family": <font_family>
}

{
 "float": "left",
 "display": "inline",
 "height": <height>,
 "margin-left": <left_margin>,
 "padding-right": <right_padding>
}

{
 "margin": "0",
 "padding": "0",
 "list-style": "none"
}

{
 "float": "left",
 "margin": "0",
 "vertical-align": "middle",
 "padding-left": "4px",
 "color": <text_color>,
 "white-space": "nowrap",
 "text-align": "center"
}