annotate is not supported by the Node engine.

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);

It is common to use a dataset in search annotation, which allows lookup of information without embedding it all within your code. The following example shows lookup by domain within a dataset. In the following example, the dataset mydataset will need to be declared in the global block of the application.

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.

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.

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"
}