Funnelback logo

Documentation

Xml.cgi

Introduction

Xml.cgi provides a REST style API to the Funnelback Classic interface. It allows developers to integrate Funnelback results into their applications by making HTTP GET calls to xml.cgi and wrapping the resulting XML response.

The Modern UI provides 2 equivalents:

Getting XML Results from xml.cgi

The following sections give details on how to get results from xml.cgi

CGI Parameters

The xml.cgi script will support most of the CGI parameters accepted by the HTML Classic search interface (search.cgi), as well as CGI parameters accepted directly by the PADRE query processor. Please see the following documents for a list of these parameters:

At a minimum you will need:

  • query: Query terms
  • collection: The name of the collection to query

Construct a query URL to the live Funnelback search service

If the search service resides at http://company.com/search/xml.cgi and the query parameters passed into the wrapper script by the user were

  • query = leave form
  • collection = intranet

then the search URL will be http://company.com/search/xml.cgi?query=leave+form&collection=intranet

Fetch the XML results

Fetching the XML results is as simple as making an HTTP GET request at the URL constructed in the step above. How to do this depends on which language your wrapper script is in. In pseudocode, this could be done as:

query = "http://company.com/search/xml.cgi?query=leave+form&collection=intranet"
xml = http_get(query)

Displaying the Results

Once you have the XML results you can perform whatever processing you wish on them. One option is to display the results in a web page. The following sections give details on this.

Render the search results in HTML

It's up to you how to present your results, but there are a few things to keep in mind:

1. The cached result URLs returned in the XML are only absolute if the collection's ui_cache_link configuration setting is being used to point users back to an alternative server that stores the cached pages. When this is the case, the cached result link can be used as is.

In all other cases, the cached result link URLs are not absolute. For example,

<cache_url>cache.cgi?collection=intranet&amp;doc=http://company.com/forms/leave_form.htm<cache_url>

This means that you must either:

  1. prefix them with the Web server and path of the live Funnelback service, or
  2. develop a custom wrapper that will fetch the cached results page, or
  3. not display the cached result links.

Note that this also applies to the click.cgi links generated in the <click_tacking_link> element if the collection has click tracking enabled.

2. The next and previous result page links (e.g. Previous 1 | 2 | 3 | 4 | 5 | 6 | Next) are not explicitly included in the XML. This means that you will need to use the information provided in the <result_summary> element to construct these links yourself. For example, the <result_summary> element might look like:

<results_summary>
  <fully_matching>0</fully_matching>
  <partially_matching>1011880</partially_matching>
  <total_matching>1011880</total_matching>
  <num_ranks>20</num_ranks>
  <currstart>1</currstart>
  <currend>20</currend>
  <nextstart>21</nextstart>
</results_summary>

Each time a next or previous page link is clicked, a new query needs to be submitted to Funnelback. The CGI parameters start_rank and num_ranks can be used indicate which page of results should be presented to the user. For example, if twenty results are displayed per page of results and the user wishes to see the third page of results, the start_rank parameter will need to be 41 (the first forty are display on the first two pages). The URL for the third page of search results would look like:

http://company.com/find.asp?collection=intranet&query=leave+form&start_rank=41&num_ranks=20

The num_ranks parameter defaults to 10 when not specified. A quick calculation using the value of the <total_matching> element and the <num_ranks> element will determine how many results page links need to be displayed. Generally, no more than ten result page links are displayed at the bottom of the results page. If required, the user can continue to navigate through the results using the "Next" and "Previous" links which point to the results pages starting at <currstart> + <num_ranks> and <currstart> - <num_ranks> respectively.

3. If you wish to display query spelling suggestions on the results page you will need to construct the link and Did you mean... text based on the content of the <spell> element. For example, the <spell> element might look like:


<spell>
  <url>collection=intranet&query=funnelbeck%20search%20engine</url>
  <text>funnelbeck search engine</text>
</spell>

The <url> element contains the query string that can be used to submit the suggested query. Note that the <url> needs to be prefixed with the URL of your XML search wrapper.

The <text> element provides a human readable version of the suggested query for use in the Did you mean ... ? link text.

4. Results from the Contextual Navigation system will also be available in the xml.cgi output if Contextual Navigation has been enabled. Some typical results might look like:

<contextual_navigation>
 <cluster_nav level="0" url="/search/xml.cgi?collection=lear&query_prox=lear">lear</cluster_nav>
  <category name="type" more="0">
    <cluster href="/search/xml.cgi?collection=lear&query_prox=king+lear&stem=2&cluster0=lear" count="89">King...</cluster>
  </category>
  <category name="topic" more="0">
    <cluster href="/search/xml.cgi?collection=lear&query_prox=lear+of+all+these+bounds&stem=2&cluster0=lear" count="4">...of all These Bounds</cluster>
    <cluster href="/search/xml.cgi?collection=lear&query_prox=lear+on+a+bed+asleep&stem=2&cluster0=lear" count="3">...on a Bed Asleep</cluster>
  </category>
  <category name="site" more="0">
    <cluster href="/search/xml.cgi?query=lear&collection=lear&meta_u_phrase_sand=blue-funnelback-com" count="30">blue.funnelback.com</cluster>
  </category>
</contextual_navigation>

Here, the <cluster_nav> elements show the current browsing history (which clusters have been selected so far), and the <category> elements contain lists of suggestions for further query options wrapped in <cluster> elements.

Point the search form at the wrapper script

After testing the wrapper script thoroughly, modify your search form to point at the wrapper. In most cases this will mean changing the ACTION parameter to point to the URL of your search wrapper (e.g. http://company.com/find.asp ) instead of the live Funnelback service.

See also

top ⇑