KNS includes two actions that annotate search results. These two methods provide a mechanism to annotate search results on Google, Bing, and Yahoo.
Action Syntax
annotate_search_results(<selector_func>)
annotate_local_search_results(<selector_func>)
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 (or anything that evaluates to false in javascript) 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.
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/scriptreturn 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 with syntax, 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.
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):
Search Annotation
KNS includes two actions that annotate search results. These two methods provide a mechanism to annotate search results on Google, Bing, and Yahoo.
Action Syntax
annotate_search_results(<selector_func>)annotate_local_search_results(<selector_func>)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 (or anything that evaluates to false in javascript) 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
mydatasetwill 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
remoteoption providing the URL of the remote data service.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
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.
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.
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.prepend) - specifies how the annotation is placed relative to theelement_to_modify. Valid values are:prepend- make the annotation the first child of theelement_to_modify.append- make the annotation the last child of theelement_to_modify.before- make the annotation the sibling before theelement_to_modify.after- make the annotation the sibling after theelement_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.
"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."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
domainsoption.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
divwhich is inside an outerdiv. 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):
outer_div_cssdefaults to the following:{ "float": "right", "width": "auto", "height": <height>, "font-size": <font_size>, "line-height": "normal", "font-family": <font_family> }inner_div_cssdefaults to the following:{ "float": "left", "display": "inline", "height": <height>, "margin-left": <left_margin>, "padding-right": <right_padding> }ul_cssdefaults to the following:{ "margin": "0", "padding": "0", "list-style": "none" }li_cssdefaults to the following:{ "float": "left", "margin": "0", "vertical-align": "middle", "padding-left": "4px", "color": <text_color>, "white-space": "nowrap", "text-align": "center" }