Appendix A: Canned Search

Warning: This page has not been updated to iVia version 5.

The canned_search program is a CGI script that can be used to perform searches on the iVia live database. This page shows how you can embed canned_search queries in your own documents.

As an alternative to constructing your queries by hand, you can use the canned search query generator. It provides an interactive form you can use to set complex query terms and search options, then generates an URL to perform the search.

The remainder of this chapter explains the different kinds of search that canned_search lets you perform.

Launching searches from your documents

The most common use of canned_search is to launch searches from other web pages, either by presenting as form to the user and asking them to enter a query term, or by embedding a hyperlink in the page for a user to click on.

The basic search form

The simplest form searches all the fields and categories. Figure 1 shows the form (top), and the HTML code that is used to generate it (bottom).

Figure 1: The basic search form
<form action="http://infomine.ucr.edu/cgi-bin/canned_search" method="post">
<input type="text" name="query" value="" size="40" maxlength="100" />
<input type="submit" value="Search" />
</form>

Restricting the fields and categories in a search form

We can restrict a search by providing fields and categories parameters. For example, the form in Figure 2 searches only for keyword and subject fields in the bioag category. (Note that the search results page will use the formatting for "Biological, Agricultural & Medical Sciences", and that only the KW and SU check boxes will be set in the search box at the bottom.

Figure 2: Restricting the fields and categories in a search form
<form action="http://infomine.ucr.edu/cgi-bin/canned_search" method="post">
<input type="text" name="query" value="" size="40" maxlength="100" />
<input type="hidden" name ="categories" value="bioag" />
<input type="hidden" name ="fields" value="KW,SU" />
<input type="submit" value="Search" />
</form>

Co-branding: setting the display theme

We can control the way the results are displayed by setting the theme parameter. The theme must be available on the server, as is described in Appendix B: Institutional co-branding with themes. Figure 3 shows how the theme can be set in a form.

Figure 3: Co-branding: setting the display theme
Use searching for
<form action="http://infomine.ucr.edu/cgi-bin/canned_search" method="post">
Use
<select name="theme">
<option value="defaults">the default theme</option>
<option value="titles">the titles-only theme</option>
<option value="simple">a simple theme</option>
</select>
searching for
<input type="text" name="query" value="" size="40" maxlength="100" />
<input type="submit" value="Search" />
</form>

Other options

We can control other options, like the number of results to show and the use of stemming. These parameters, shown in Figure 4, are called no_of_records_per_page and stemming respectively. Other parameters are detailed in the table of canned_search parameters.

Figure 4: Other options
Show with searching for
<form action="http://infomine.ucr.edu/cgi-bin/canned_search" method="post">
Show
<select name="no_of_records_per_page">
<option value="10">10 results</option>
<option value="20">20 results</option>
<option value="50">50 results</option>
</select>
with
<select name="stemming">
<option value="yes">stemming</option>
<option value="no">no stemming</option>
</select>
searching for
<input type="text" name="query" value="" size="40" maxlength="100" />
<input type="submit" value="Search" />
</form>

Searching for a list of records

The form in Figure 5 form uses canned_search to display records 2, 23, 234 and 2345. It doesn't actually perform a search, in the traditional sense; it simply retrieves the records by record number

Figure 5: Searching for a list of record ids.
<form action="/cgi-bin/canned_search" method="post">
<input type="hidden" name="record_id_list" value="2,23,234,2345" />
<input type="submit" value="Search" />
</form>

Searches launched from hypertext links

Searches that are linked from hypertext links, as opposed to forms, can also accept additional parameters. The canned search query generator provides an interactive form you can use to set complex query terms and search options, then generates an URL for use in hypertext links like these.

Figure 6: Searches launched from hypertext links
A search for forest in the bioag category.
<a href='http://infomine.ucr.edu/cgi-bin/canned_search?query="forest"'>
A search for forest in the bioag category.
</a>
We can create "special collections" by assigning them a unique keyword.
Search for dictionaries the using the keyword REFDICT using the "simple" theme
<a href='/cgi-bin/canned_search?query="REFDICT"&fields=KW&theme=simple'>
Search for dictionaries the using the keyword REFDICT using the "simple" theme
</a>
A search for agriculture "bibliographic databases"
<a http://infomine.ucr.edu/cgi-bin/ canned_search?query=agriculture%20"bibliographic%20databases"'>
A search for agriculture "bibliographic databases"
</a>
A search in a new window
<a target="newwindowname"
href='http://infomine.ucr.edu/ cgi-bin/canned_search?query="research%20summaries"&fields=KW'>
a search in a new window
</a>

Embedding search results in Web pages

We described above how canned_search themes can be used to alter the appearance of the result set. We can use canned_search with very simple search themes to embed result lists into web pages that are generated by PHP or server-side includes (i.e. SHTML pages).

Four simple themes are currently available: row_title_link, row_title_desc, p_title_link, and p_title_desc.

The row_title_link and row_title_desc themes return search results as though they were the body of a table, so that searches can be embedded into PHP pages with an "include" command. In each case, one record is returned on each row in the table, though the format differs slightly.

For example, the PHP command in Figure 7 is based on row_title_link. The topmost row contains the PHP command that is used to generate the subsequent rows: these rows are embedded automatically as this page is created. The list may change as the records in the live database changes.

Figure 7: The row_title_link theme
<?
include("http://infomine.ucr.edu/cgi-bin/canned_search? query=ucr-db-newspapers&fields=MI&ranking_type=T&theme=row_title_link");
?>

The row_title_desc theme will produce a similar (but more verbose) table.

The p_title_link and p_title_desc themes output each search results in a separate paragraph. For example, the following paragraphs are the output of a query using the p_title_link theme (they are indented using <blockquote> tags):

<? include("http://infomine.ucr.edu/cgi-bin/canned_search?query=ucr-db-newspapers&fields=MI&ranking_type=T&theme=p_title_link"); ?>

The table of canned_search parameters

The table below describes all the parameters to the canned_search program.

Table 1: The table of canned_search parameters
Option name Possible values Default value Description
query url-encoded strings   The text of the query.
categories all, or a top-level category (bioag, govpub, etc), or a semicolon-separated list of categories all The categories to search in.
fields ti, au, su, kw, an, mi, fu, or a semicolon-separated list of fields, or all. ti;au;su;kw The fields to search in.
theme defaults, titles, simple, or some other valid theme name defaults Themes are used to control the appearance of the canned_search2 output. Usually, no theme will be specified, and the defaults theme will be used.
no_of_records_per_page A number between 2 and 200. 10 The number of results to display on each page. Why is there a maximum? I do not know.
start_page_no a number 1 Results may be split into several pages. This specifies which page to use.
stemming yes or no yes Should stemming be used in the search?
ranking_type R or T R Use R to rank by Relevance, and T to rank by Title
search_space EXPERT_ONLY, CRAWLED_ONLY, or ALL_RECORDS EXPERT_ONLY Should the search be restricted to expert-created records, or to crawler-created records, or should both types be searched?
access all, Internet, free, only-fee-based, only-local, auto, or the name of an institution as specified in access_control.conf. auto Return a set of records based on the institution the searcher is associated with? If access is set to "all", then all the records will be searched. If access is set to "Internet", then all free and fee-based Internet resources will be searched (i.e. all records except local records). If access is set to "free", then all free Internet resources will be searched. If access is set to a campus name, all records readily available at that campus will be searched (e.g. for UCLA, all the free + UCLA fee-based records would be searched.) If access is set to "auto", then canned_search will attempt to auto-detect the user's campus, and if it fails will default to "Internet". The only-fee-based and only-local settings restrict the results to only fee-based or local resources respectively, and are generally used for debugging.
record_id_list comma-delimited list of record ID numbers   If set, canned_search lists the records instead of performing a search.
category * A single top-level category. Unused. A category to search in. You may repeat this argument as many times as you like, as in HTML forms with check boxes. This parameter is ignored if categories is used.
field * A single field. Unused. A field to search in. You may repeat this argument as many times as you like, as in HTML forms with check boxes. This parameter is ignored if fields is used.