Creating a text search interface

s a server administrator, you can create and maintain an end-user text search interface that allows clients to search your Web site. Included with the Netscape Enterprise Server are the components you need to create a text search interface. You can use these components as they are, or you can work with these components to customize a text search interface that's tailored to your user community's needs.

The following outlines what you need to do in order to create a text search interface:

Creating a new collection

Before creating a collection, you need to create the URL mapping for the directory that contains the documents you want to index. Creating the URL mapping prevents users from seeing the full path of a collection in the URL when viewing their search results; rather, the URL they see contains the mapping you create. Choose Content Mgmt|Additional Document Directories to access the form used to create URL mappings. For more information about URL mappings, see "Setting additional document directories" on page 44.

To create a new collection,

  1. Choose Index Documents|New Collection.
  2. Type a name for the collection. Use alphanumeric characters; the name should contain no spaces and follow the standard file-naming conventions for your operating system. The collection name will be used for collection maintenance and is what end users see when they use the text search interface. Make your collection names as descriptive and relevant to its files as possible.
  3. Type a description for the collection.
  4. Type the absolute path of the directory that contains the original files you want to index for the collection. The search engine will go to this directory for searching and retrieval.

    Caution! If you have sensitive documents in the collection directory that are protected by access control, you should store them in another directory. Although protected documents can be searched, and any matches in them to user-specified criteria will be listed in the search results, users cannot access any protected documents unless they enter a valid user name and password.

  5. Select whether to include the subdirectories for the directory that will be indexed.
  6. Select the type of file the collection will contain (ASCII or HTML). A collection can only contain one type of file.
  7. Type the name of a file (or wildcards, such as *.html) or a directory containing the files you want to add to the collection. If you enter a directory, make sure that it is relative to the directory you entered in Step 4.
  8. Click OK.
When you create a collection, URL mappings for the search CGI binaries are automatically added to the obj.conf file. If you install another server in an existing server root directory, the new server can also edit and manage any existing collections created with the original server. Users cannot search those collections until you add the URL mappings to the new server's obj.conf file.

Add the following lines to the default object in your obj.conf file:

NameTrans from="/ns-search" fn="search-find"
NameTrans from="/search" fn="pfx2dir" dir="[ServerRoot]/plugins/search/
vsearch" name="cgi"
NameTrans from="/ui" fn="pfx2dir" dir="[ServerRoot]/plugins/search/ui"
Service fn="search-service"cgi-path="[ServerRoot]/plugins/search/
vsearch/iarecord" type="magnus-internal/search"
Note
When adding the previous lines to your obj.conf file, substitute [ServerRoot] with your server root directory. Place the NameTrans directives with the existing NameTrans directives; place the Service directive with the existing Service directives.

Modifying a collection

Once you've created a collection, you can view and make modifications to it. You can view the contents of a collection and modify it by adding or removing documents or directories to it.

To view or modify a collection,

  1. Choose Index Documents|Edit Collection.
  2. Select the collection you want to view or modify from the drop-down list. Information about the collection you selected appears, such as the collection document root, creation date, last-modification date, status, and the number and names of any indexed documents.
  3. To add or remove documents or a directory from the selected collection, type the file name (or a wildcard pattern) or the directory path relative to the index directory you specified when you first created the collection (the collection document root in the list of information about the collection, as described in the previous step).
  4. If you entered a directory name in Step 3, choose whether to include its subdirectories.
  5. Depending on whether you're updating or removing documents or directories, click Update or Remove.

Managing collections

Periodically, you'll need to manage collections. You can perform the following collection management tasks:

To perform any of the previous collection management tasks,

  1. Choose Index Documents|Manage Collection.
  2. Select the collection you want to manage from the drop-down list. Information about the collection you selected appears.
  3. To optimize your collection, click Optimize. To repair your collection, click Repair. To remove your collection, click Remove.

Scheduling collections for reindexing

As you add and modify documents in your collections, the documents need to be reindexed to reflect the new information. You can schedule a collection to be automatically reindexed at a specific date and time by using the Server Manager. Information about collection reindexing is stored in the cron.conf file in the [ServerRoot]/admserv directory; the server's cron configuration options are stored in ns-cron.conf in the admserv directory.

To schedule a collection for reindexing,

  1. From the Server Manager, choose Index Documents|Timing Utility.
  2. Choose a collection from the drop-down list.
  3. Type the document name or directory path relative to the index directory you specified when you first created the collection (the collection document root).
  4. Click on the reindex checkbox.
  5. Choose the time reindexing will start from the drop-down list.
  6. Click the check box for the day(s) reindexing will occur.
  7. Click OK.
  8. Stop and restart the administration server. For more information about stopping and starting the administration server, see "Shutting down the administration server" and "Accessing the Server Selector" in Chapter 3.

Maintaining a list of non-search words

In the plugins/search/common/english directory of your server root directory, there is a file named vdk10.stp, which contains words the search engine will not index or search for. This file applies to all collections. Use a text editor to add or delete words you don't want the search engine to find when searching.

Using text search

The easiest way for users to access text search is by typing the text search URL in their network navigator (http://[yourserver]/search/iaquery). Using the search engine, users can search collections that you've created using the Server Manager. There are two sample search forms available: simple search and advanced search. Users can use the advanced search features to narrow and refine their search criteria.

Sample simple text search

The sample simple text search form allows you to search one collection at a time for information using free text search, which has no explicit syntax; that is, you can enter blocks of text to search, and the search engine will retrieve documents with similar style or content. Results are measured by document scores; the higher the score, the more likely the document will match the specified search criteria.

Sample advanced searching

The sample advanced searching form allows users to search one or more collections simultaneously using free text (literal) or Boolean searching to refine their search criteria (using the AND, OR, and NOT operators).

To use advanced searching:

  1. In the text search window, click on the Advanced Search link.
  2. Select the collection(s) you want to search from the Subject list box.
  3. Enter a word, words, or a phrase in the Search field.
  4. Choose whether you want to perform a literal (free text) or Boolean search. A literal (free text) search will find documents most similar to what you entered in Step 3. A Boolean search allows you to use operators such as AND, OR, and NOT for exact match searching.
  5. Enter the maximum number of documents you want returned from your query. (This is optional.)
  6. Click Search.

Customizing the text search interface

After you have created collections, you can work with the following to create a customized text search interface:

Text search CGIs

Text search CGIs and their associated pattern files build the HTML pages that users see when they click on a search icon or type a search CGI's URL. Search CGIs review each initialization file and replace the variables in the pattern files with their associated values from the initialization file or from the CGI parameters.

There are three search CGIs:

Pattern files

Pattern files are HTML files that define the layout of the text search interface. You associate a pattern file with a CGI and a set of pattern variables to create a specific portion of the interface. In the pattern file, you define the look, feel, and function of the text search interface.

A pattern file includes reserved and user-defined pattern variables. You can create user-defined variables to customize items such as background color, help text, banners, and so on. In some cases, the values are pathnames to the files that contain the actual text and graphics that these variables represent; in other cases, the values represent text and HTML.

Initialization files

The information associated with a pattern variable is stored in one of three initialization files. The search CGI reviews each initialization file for the following information:

The search CGIs replace the variables in the pattern files with their associated values from these initialization files.

The system.ini, iairs.ini, and dblist.ini are distinguishable by the types of pattern variables they use. The system.ini file contains reserved pattern variables for the web-server administrator to maintain. The iairs.ini and dblist.ini files contain name-value strings that correlate with pattern variables. To customize a text search interface, you create and define these variables. Use a text editor to define entries in iairs.ini to specify pattern variables to be used throughout your pattern files. The dblist.ini file is created and updated by the indexer.

Figure 10.2 shows a sample system.ini file, which is located in the plugins/search/admin directory in your server root directory. Note that pattern files (NS-query.pat, NS-ms-tocstart, and NS-ms-tocend) are given as relative paths from NS-ui-dir; this is true for dblist.ini.

Sample system.ini file

[iairapi]
NS-vdk-libpath = /usr/ns-home/plugins/search/common
NS-dblist-ini = /usr/ns-home/plugins/search/admin/dblist.ini
NS-searchset-dir = /usr/ns-home/plugins/search/tmp
NS-ui-dir = /usr/ns-home/plugins/search/ui

[iaquery]
NS-irs-file = /usr/ns-home/plugins/search/admin/iairs.ini
NS-query-cgi = /search/iaquery
NS-record-cgi = /search/iarecord
NS-toc-cgi = /search/iatoc
NS-max-records = 100
NS-largest-set = 200
NS-freetext-query = Free text
NS-boolean-query = boolean
NS-expert-query = explicit
NS-freetext-query-checked = checked
NS-boolean-query-checked = 
NS-expert-query-checked = 
NS-query-pat = /usa/NS-query.pat
NS-set-expiration = 36000
NS-ms-tocstart = /usa/HTML-tocstart.pat
NS-ms-tocend = /usa/HTML-tocend.pat
NS-query-and = AND
NS-query-or = OR
NS-query-not = NOT 
NS-date-time = %b-%d-%y %H:%M
NS-collection-select = multiple
Figure 10.3 shows the sample iairs.ini file, located in the plugins/search/admin directory in your server root directory.

Sample iairs.ini file

[query]
uidir = $$NS-server-url/ui
icondir = $$uidir/icons
htmldir = $$uidir/usa
banner = Netscape Communications Corporation
logo = src="$$icondir/srchlogo.gif" border=0 width=348
height=110
background =
query = internet communications
copyright = Copyright © 1995 Netscape Communications Corporation. All Rights Reserved.
help = $$htmldir/help.html
advhelp = $$htmldir/advhelp.html
mailto =mailicon = src="$$icondir/mailto.gif" border=0 width=35 height=25
[toc]
sitename = Site Name
uidir = $$NS-server-url/ui
icondir = $$uidir/icons
htmldir = $$uidir/usa
banner = Netscape Communications Corporation
logo = src="$$icondir/srchlogo.gif" height=55 width=174 border=0
icon = src="$$icondir/icon.gif" height=35 width=28 border=0
icon2 = src="$$icondir/icon2.gif" height=35 width=28 border=0
background =
help = $$htmldir/help.html
advhelp = $$htmldir/advhelp.html
querygif = src="$$icondir/query.gif" height=25 width=59 border=0
[record]
sitename = Site Name
uidir = $$NS-server-url/ui
icondir = $$uidir/icons
htmldir = $$uidir/usa
banner = Netscape Communications Corporation
logo = src="$$icondir/srchlogo.gif" height=55 width=174 border=0
previous = src="$$icondir/previous.gif" height=26 width=97 border=0
next = src="$$icondir/next.gif" height=26 width=97 border=0
querygif = src="$$icondir/query.gif" height=25 width=59 border=0
tocgif = src="$$icondir/toc.gif" height=25 width=59 border=0
background =
help = $$htmldir/help.html
advhelp = $$htmldir/advhelp.html
querygif = src="$$icondir/query.gif" height=25 width=59 border=0
Figure 10.4 shows an example dblist.ini file, which is located in the plugins/search/admin directory in your server root directory.

Sample dblist.ini file

[engineering]
file_format = html

idx_path = /usr/ns-home/plugins/search/collections/engineering
doc_root = /usr/ns-home/docs url_root = http://myserver.netscape.com:12345/ns-search url_base = http://myserver.netscape.com:12345
NS-doc-pat = /usa/HTML-record.pat NS-tocend-pat = /usa/HTML-tocend.pat NS-tocrec-pat = /usa/HTML-tocrec.pat NS-tocstart-pat = /usa/HTML-tocstart.pat
NS-highlight-start = <b> NS-highlight-end = </b>
[marketing] file_format = html
idx_path = /usr/ns-home/plugins/search/collections/marketing

doc_root = /usr/ns-home/docs url_root = http://myserver.netscape.com:12345/ns-search url_base = http://myserver.netscape.com:12345
NS-doc-pat = /usa/HTML-record.pat NS-tocend-pat = /usa/HTML-tocend.pat NS-tocrec-pat = /usa/HTML-tocrec.pat NS-tocstart-pat = /usa/HTML-tocstart.pat
NS-highlight-start = <b> NS-highlight-end = </b>
[hr] file_format = html

idx_path = /usr/ns-home/plugins/search/collections/hr

doc_root = /usr/ns-home/docs url_root = http://myserver.netscape.com:12345/ns-search url_base = http://myserver.netscape.com:12345
NS-doc-pat = /usa/HTML-record.pat NS-tocend-pat = /usa/HTML-tocend.pat NS-tocrec-pat = /usa/HTML-tocrec.pat NS-tocstart-pat = /usa/HTML-tocstart.pat
NS-highlight-start = <b> NS-highlight-end = </b>

Designing a text search interface

When defining a text search interface, keep the following in mind:

Determining search requirements

You need to decide what type of searching to provide for your users and the number of collections that will form the basis of the search. The text search interface allows you to specify either the free text or boolean search options in a search panel.

The search engine tokenizes or parses a user's search expression based on a set of syntax rules. A free text search allows a user to enter a word, or part of a word or a block of free text. The search engine retrieves documents that match the query entered by the user. For example, by entering the word region, the actual word region and all its stemmed variations (such as regions and regional) are searched.

When users perform a free text search, the result of their search is relevance ranked. This means that the search engine bases a word's relevance on the number of times the word or its stem occurs in the document, as well as across the collection.

A free text search allows a user to enclose words in quotes for literal meaning., which limits the search to the precise word in quotes. For example, by entering "region," none of the stemmed variations (such as regions and regional) are searched.

Designing the text search interface

To design a text search interface, think of the interface in terms of its three main stages:

The text search components provide flexibility in the design of your interface in relation to these stages. For example, you can design your interface to accommodate the entire search process using two HTML pages, instead of three (for example, you could design iatoc to show the full record output); you can create any number of pattern files for your search (for example, you could use different patterns for each collection in dblist.ini); or you can bypass the iaquery CGI and have users conduct their search through iatoc CGI directly.

Note
In the system.ini file provided, the NS-ms-tocstart and NS-ms-tocend macros and pattern files are set to point to the sample pattern files HTML-tocstart.pat and HTML-tocend.pat. These pattern files are used by iatoc if multiple colletions are searched simultaneously.

Designing each part of the text search interface

When designing each part of the text search interface, consider the issues involving the function of each part. In the three-stage model discussed in the previous section, users use a search panel to specify their search criteria, a table of contents lists search results, and a record screen used to view documents.

Search panel
Consider the following when designing the search panel interface:

Search results
When designing a table of contents that lists the search results for viewing, consider the format for the header and footer in each entry of the search results.

Record display
When designing the format for the record display, consider the layout for the text display. Attributes for the record display are determined by the type of document that the user specifies (for example, HTML or ASCII).

Using pattern variable and search CGI parameters

This section briefly introduces syntax used for pattern variables and CGI parameters.

By using pattern variables in pattern files, you can customize the search text interface and eliminate the need to update the actual document files (HTML pages) as information changes. For example, if the interface has graphics or text that changes periodically, you can define a pattern variable that points to a path name where that graphic or text is maintained and stored.

By calling a search CGI directly, you can bypass or further customize the search process. Each search CGI accepts a set of parameters. If the default pattern files are used, CGI calls are constructed through pattern variable substitutions.

Pattern variable syntax

A pattern variable is represented as a formatted name string with a special prefix. The prefix differentiates the pattern variable from other markup tags in an HTML page.

The syntax for pattern variables is:

pattern_variable_prefix || pattern_variable_name

pattern_variable_prefix specifies the special prefix to distinguish pattern variables from normal text or other HTML markup tag. The prefix is always $$.

pattern_variable_name specifies the name string in a pattern variable that follows the pattern variable prefix. The name string from the pattern variable identifies the applicable values that are provided in the NS-irs-ini and system.ini files.

Names consist of up to 32 characters, digits, or combinations of both. Characters can be letters A-Z in upper or lower case, hyphens (-), and underscores (_). Names are case sensitive.

Example:

The following pattern variables are embedded in the beginning of the Search Panel pattern file.

<html>
<body background="$$background">
<head>
<title>TEST:$$banner</title>
</head>
<a href="$$help"><img align=left $$logo></a><br clear=left>
<br>

The sample iairs.ini file included with the Netscape Enterprise Server contains values that correspond to pattern variables highlighted in bold above. The following is the part of the query section of that file. Note that the name strings and their values correspond to the name strings of the pattern variables in the pattern file.

You can create any number of variables in iairs.ini to customize the output of the HTML pattern files.

[query]
banner = Netscape Communication Corporation
logo = src="/ui/icons/head.hp.gif" border=0
background = /ui/icons/bkgd.1.gifquery = internet communications
copyright = Copyright &copy 1996 Netscape Communication Corporation.
All Rights Reserved.
help = /ui/usa/help.html
advhelp = /ui/usa/advhelp.html

Reserved pattern variables

Reserved pattern variables are used to:

Think of reserved pattern variables as macros that produce a specific action.

In the pattern file, you can identify the reserved pattern variables for substitution and those used to call CGIs by the $$NS- prefix. You can identify reserved pattern variables to be passed to the CGI via a form or the CGI argument by the NS-prefix.

The format of each attribute-value pair that is passed to the CGI argument is:

cginame?NS-variable=value&NS-variable=value& ...

For example:

          $$NS-toc-cgi?NS-search-pat=/file_path&

where /file_path is relative to the directory specified in system.ini's NS-ui-dir.

The name strings and values of some reserved pattern variables are defined in the system.ini file. The site administrator is responsible for updating the values contained for some of these pattern variables. For example, you can alter NS-largest-set to specify the maximum possible number of records returned from a search; you can also alter NS-max-record to specify the default maximum number of records. Other pattern variable values in this file, such as the ones required to call particular CGIs for a pattern file, contain values that should not be altered by the site administrator.

Do not define pattern variables beginning with $$NS, or change the values that are designated for these pattern variables without understanding the repercussions.

Invoking iaquery CGI

You can use iaquery search CGI to generate a Search Panel interface that allows users to specify their search criteria. The iaquery CGI builds the HTML page using a search panel pattern file whenever a user clicks on an HTML page with a search text icon, or provides the CGI URL.

The iaquery CGI reviews the system.ini initialization file for the default search panel pattern file. It also reviews iars.ini and dblist.ini. The iaquery CGI replaces the variables in the pattern files with their associated values from these files.

The iaquery CGI is invoked with the following mandatory and optional parameters. The format for the CGI call is:

/search/iaquery?<param1>=<value1>&<param2>=<value2>&...

Parameters for iaquery CGI

Following is a list of the mandatory and optional parameters that apply to iaquery CGI. For a description of each parameter, see the Summary of Reserved Pattern File Variables and CGI Parameters at the end of this chapter.

Mandatory Parameters to iaquery CGI

None

Optional Parameters to iaquery CGI

NS-collection
NS-ms-tocstart
NS-ms-tocend
NS-query-pat
NS-max-records
NS-tocrec-pat
NS-tocstart-pat
NS-tocend-pat

Optional Variables for use in Search Panel Pattern File (in addition to parameters to the CGI)

NS-collection-list
NS-collection-list-dropdown
NS-query
NS-query-and
NS-query-op
NS-query-or

Underlying pattern file examples

In the following examples, the iaquery CGI uses the NS-query.pat file, which is common to all document formats, to generate a search panel.

Search panel example
This example creates the sample search panel page that allows users to enter their search criteria. The name of the pattern file, NS-query.pat, is defined once, in system.ini and is the default search page used to conduct a free text search.

Shown below is the default for the search panel pattern file (NS-query.pat located in system.ini).

<html>
<head>
<title>$$banner</title> <head> <body background="$$background"> <img align=left $$logo><br clear=left> <br> <hr size=4> To search for an article, choose a subject, then enter a single word, several words, or a phrase. You can get <a href=$$help>search tips,</a> or perform an <a href="$$NS-query-cgi?NS-query-pat=/usa/NS-advquery.pat&"advanced search.</a><p> <table cellpadding=5> <tr>td align=right><b>Subject: <b></td> <form method="post" action="$$NS-toc-cgi"> <input type="hidden" name="NS-search-type" value="$$NS-freetext-query"> <td>$$NS-collection-list-dropdown</td></tr> <tr><td align=right><b>Search for: </b></td> <td align=left><input name="NS-query" size=40 value="$$NS-query">&nbsp&nbsp&nbsp&nbsp<input type="submit" value=Search"></td></tr> </form> </table> <hr> <h5>$$copyright</h5>
</body>
</html>
The search panel pattern file uses the pattern variables listed in Table 10.1.
Pattern Variables

Description

Reserved

If the pattern variable is optional, it is maintained by the System Administrator (SA). Otherwise, the pattern variable is mandatory and represents critical system information that should not be changed.

$$NS-toc-cgi

Specifies the name of the program that generates the TOC defined in system.ini. This variable is necessary to invoke iatoc.

$$NS-query

Specifies the query to iatoc. This variable is mandatory for iatoc.

$$NS-search-type

Specifies the tag for a selected query type. This variable is mandatory for iatoc.

$$NS-freetext-query

Specifies the free text search. This variable is optional. If this variable is not specified, then $$NS-boolean-query cam be specified. The default is free text.

$$NS-collection-list-dropdown

Expands to a drop-down list of collections. This variable is optional and can be used in place of NS-collection or NS-collection-list.

User-defined

You can change or create new values for these variables. All are optional.

$$background

Background color

$$banner

Name of content provider

$$help

Link to help file

$$logo

Content provider logo

$$copyright

Copyright notice

Invoking iatoc CGI

You can use iatoc search CGI to generate a search results item interface that allows users to choose a search item for display. The iatoc CGI builds the HTML page using a search results header, a search results item, and a search results trailer pattern file. This occurs whenever a user submits a search from the search panel page, clicks on an HTML page with a request for the iatoc CGI, or provides the CGI's URL.

The iatoc CGI reviews the system.ini initialization file for the location of the iaquery and iatoc CGIs and the value of the free text and boolean searches. It also uses dblist.ini to determine what pattern files to use for selected collections and iairs.ini to replace user defined variables in the pattern files.

The iatoc CGI is invoked with the following mandatory and optional parameters. The format for the CGI call is:

/search/iatoc?<param1>=<value1>&<param2>=<value2>&...

Parameters for iatoc CGI

Following is a list of the mandatory and optional parameters that apply to iatoc CGI.

Mandatory Parameters to iatoc CGI

NS-query
NS-collection
NS-search-type

Optional Parameters to iatoc CGI

NS-boolean-query
NS-boolean-query-checked
NS-freetext-query
NS-freetext-query-checked
NS-ms-tocstart
NS-ms-tocend
NS-query-and
NS-query-op
NS-query-or
NS-query-pat
NS-max-records
NS-tocrec-pat
NS-tocstart-pat
NS-tocend-pat
NS-toc-cgi

Optional Variables for use in Search Results Item Pattern File (in addition to the parameters to the CGI)

NS-collection-list
NS-collection-list-dropdown
NS-doc-name
NS-doc-number
NS-doc-path
NS-doc-score
NS-doc-size
NS-doc-time
NS-docs-found
NS-docs-searched
NS-insert-doc
NS-next-doc
NS-prev-doc
NS-rel-doc-name
NS-record-cgi
NS-query-cgi
NS-query-pat
NS-search-url
NS-url-base
NS-url-root

Underlying pattern file examples

In these examples, to generate a search panel, the iatoc CGI uses the following pattern files available with the Text Search module:

Search results header example
This example creates the header for the page that displays the search results. The pattern file in this example is constructed in a format similar to the search panel page and allows users to modify and resubmit the search if necessary.

Note
The search results header page in the sample re-uses the interface from the search panel page. Re-implementing the query interface in the search results header is a convenient way to offer users a mechanism to re-enter a search entry if the results are not sufficient.
Shown below is the resulting search results header page. Note that the items displayed for the search follow the header.

Shown below is the search results header pattern file (HTML-tocstart.pat located in dblist.ini) for the HTML document format.

<html>
<head>
<title><$$banner</title>html>
</head>

<body background="$$background"> <img align=left $$logo> <DIV align=right><h2>$$sitename</h2></DIV><br clear=left> <b>Search found $$NS-docs-found documents from $$NS-docs-searched in this subject.</b> You can get <a href=$$help">search tips,</a> or perform an <a href="$$NS-query-cgi&NS-query-pat=/usa/NS-advquery.pat&">advanced search.</a><p> <table cellpadding=5>
<form method="post" action="$$NS-toc-cgi"> <tr><td align=right><b>Subject: </b></td>$$NS-collection-list-dropdown</td> <input type="hidden" name="NS-search-type" value="$$NS-freetext-query"> <input type="hidden" name="NS-max-records" value="$$NS-max-records"> <td>$$NS-collection-dropdown</td></tr> <tr><td align=right><b>Search for: </b></td> <td align=left><input name="NS-query" size=40 value="$$NS-query"">&nbsp&nbsp&nbsp&nbsp<input type="submit" value="Search"></td></tr> </form> </table> <table width="100%">
The pattern variables in this pattern file are described in Table 10.2.
Pattern Variable

Description

Reserved

If the pattern variable is optional, it is maintained by the System Administrator (SA). Otherwise, the pattern variable is mandatory and represents critical system information that should not be changed.

$$NS-query-cgi

Specifies the name of the iaquery CGI. This variable is optional.

$$NS-toc-cgi

Specifies the name of the program that generates the TOC defined in system.ini. This variable is optional.

$$NS-docs-found

Specifies the number of search items that were retrieved during a search. This variable is optional.

$$NS-docs-searched

Specifies the number of documents searched. This variable is optional.

$$NS-query

Notifies the CGI of the value of a pattern variable. This variable is optional.

$$NS-search-type

Specifies the tag for a selected query type. This variable is optional.

$$NS-collection-list-dropdown

Expands to a drop-down list of collections. This variable is optional and can be used in place of NS-collection or NS-collection-list.

$$NS-max-records

Specifies the tag for a system defined maximum number of records

User-defined pattern variables
You can change or define the value of these pattern variables. All are optional.

$$background

Background color

$$banner

Name of content provider

$$querygif

Takes the user back to the Search Results Header page

$$help

Link to help file

$$logo

Content provider logo

$$sitename

Name of your site

Search results items
The search results items example creates the search results entries. In this example, when the user clicks the icon represented by pattern variable $$icon, the actual text for the document is shown with highlights by invoking iarecord.

Shown below is the search results items pattern file (HTML-tocrec.pat) for the HTML document format.

<tr><td valign=top>
&nbsp&nbsp<a href="$$NS-record-cgi"><img $$icon></a>&nbsp&nbsp</td><td>
<a href="$$NS-record-cgi">
<strong>$$NS-doc-number:  $$title</strong>>/a> <font size=-2>(Highlighted)</font>
<table width="100%">
<tr><td>&nbsp&nbsp&nbsp</td><td><I><A HREF="$$NS-url-base$$NS-rel-doc-name">$$NS-url-base$$NS-rel-doc-name</A>, <font size=-2>(Original) (Score $$NS-doc-score, Size $$NS-doc-size, Last modified $$NS-doc-time)</i>
</td>
</tr>

</table> </td></tr>
The pattern variables in this pattern file are described in Table 10.3.
Pattern Variable

Description

Reserved

If the pattern variable is optional, it is maintained by the System Administrator (SA). Otherwise, the pattern variable is mandatory and represents critical system information that should not be changed.

$$NS-record-cgi

Specifies the name of the iarecord CGI. This variable is mandatory.

$$NS-doc-score

Specifies the relevance ranking of the document. This variable is optional and is program generated.

$$NS-doc-size

Specifies the size of the document. This variable is optional.

$$NS-doc-time

Specifies the time when the document was created. This variable is optional.

$$NS-rel-doc-name

Specifies the relative document name (this variable plus NS-url-base provide the href). This variable is optional.

$$NS-url-base

Specifies the URL base. This variable is optional.

$$NS-doc-number

Specifies the number of documents in the results list. This variable is optional.

User-defined
You can change or create the value of these pattern variables. All are optional.

$$icon

Icon that represents the button used to call the program that generates the display record

$$title

Title from HTML <title> tag.

Search results trailer example

The search results trailer displays boilerplate text at the end of each search results items listing. In this example, the boilerplate text is the copyright notice and it also appears in all interface screens.

Shown below is the Search Results Trailer Pattern file (HTML-tocend.pat located in dblist.ini) for the HTML document format.

</table>
<h5></table>
</h5>
</body>
</html>
The only pattern variable in this pattern file is $$copyright, which is defined in the sample iairs.ini as the copyright notice.

Invoking iarecord CGI

You can use iarecord search CGI to generate a search results item interface that allows users to choose a search item for display. The iarecord CGI builds the HTML page using a search results header and search results item pattern file whenever a user clicks on an HTML page with a search text icon, or provides the CGI's Uniform Resource Locator (URL).

The iarecord CGI is invoked with the following mandatory and optional parameters. The format for the CGI call is:

/sbin/iarecord?<param1>=<value1>&<param2>=<value2>&...

Parameters for iarecord CGI

Following is a list of the mandatory and optional parameters that apply to iaquery CGI. For a description of each parameter, see the Summary of Reserved Pattern File Variables and CGI Parameters at the end of this chapter.

Mandatory Parameters to iarecord CGI

NS-search-set (generated by iatoc as part of the expansion of the NS-record-cgi)
NS-doc-offset (generated by iatoc as part of the expansion of the NS-record-cgi)

Optional Parameters to iarecord CGI

None

Optional Variables for use in Record Display Pattern File

NS-collection
NS-display-cgi
NS-doc-name
NS-doc-path
NS-doc-score
NS-doc-size
NS-doc-time
NS-docs-found
NS-docs-searched
NS-highlight-end
NS-highlight-begin
NS-insert-doc
NS-largest-set
NS-max-records
NS-query
NS-query-cgi
NS-query-pat
NS-search-type
NS-toc-cgi
NS-tocend-pat
NS-tocrec-pat
NS-tocstart-pat

Underlying pattern file example

In this example, to generate a document for display, the iarecord CGI uses HTML-record.pat pattern file available with the Netscape Enterprise Server. This section shows these pattern files in HTML format only.

Note
If the system cannot locate the pattern files or they do not exist, a default display is used for the Search Results Items and record display.
Record display example
The record display example uses a pattern file that displays the document text when the user clicks on the applicable icon ($$icon).

Shown below is the record display text pattern file (HTML-record.pat) for the HTML document format.

<html>
<head>
<title>/sbin/iarecord?<param1>=<value1>&<param2>=<value2>&... : $$title</title>
<base href="/sbin/iarecord?<param1>=<value1>&<param2>=<value2>&... ">
</head>
<body background="/sbin/iarecord?<param1>=<value1>&<param2>=<value2>&... ">


<table width="100%">
<tr><td><a href="/sbin/iarecord?<param1>=<value1>&<param2>=<value2>&... "><img /sbin/iarecord?<param1>=<value1>&<param2>=<value2>&... ></a>&nbsp&nbsp<a href="/sbin/iarecord?<param1>=<value1>&<param2>=<value2>&... "><img /sbin/iarecord?<param1>=<value1>&<param2>=<value2>&... ></a>&nbsp&nbsp<a href="/sbin/iarecord?<param1>=<value1>&<param2>=<value2>&... "><img /sbin/iarecord?<param1>=<value1>&<param2>=<value2>&... ></a></td><td align=right>Search text: /sbin/iarecord?<param1>=<value1>&<param2>=<value2>&... <br>
Collection: /sbin/iarecord?<param1>=<value1>&<param2>=<value2>&... &nbsp&nbsp&nbsp&nbsp$$NS-doc-number//sbin/iarecord?<param1>=<value1>&<param2>=<value2>&... </td></tr>
</table>

<hr>
/sbin/iarecord?<param1>=<value1>&<param2>=<value2>&... <hr>
<table width="100%"><tr><td>Search text: /sbin/iarecord?<param1>=<value1>&<param2>=<value2>&... <br>/sbin/iarecord?<param1>=<value1>&<param2>=<value2>&... //sbin/iarecord?<param1>=<value1>&<param2>=<value2>&... </td><td align=right>
<a href="/sbin/iarecord?<param1>=<value1>&<param2>=<value2>&... "><img /sbin/iarecord?<param1>=<value1>&<param2>=<value2>&... ></a>&nbsp&nbsp<a href="/sbin/iarecord?<param1>=<value1>&<param2>=<value2>&... "><img /sbin/iarecord?<param1>=<value1>&<param2>=<value2>&... ></a>&nbsp&nbsp<a href="/sbin/iarecord?<param1>=<value1>&<param2>=<value2>&... "><img /sbin/iarecord?<param1>=<value1>&<param2>=<value2>&... ></a>
</td></tr></table>
<hr>
<h5>/sbin/iarecord?<param1>=<value1>&<param2>=<value2>&... </h5>
</body>
</html>
The pattern variables in this pattern file are described in Table 10.4.
Pattern Variable

Description

Reserved

If the pattern variable is optional, it is maintained by the System Administrator. Otherwise, the pattern variable is mandatory and represents critical system information that should not be changed.

$$NS-query-cgi

Specifies the name of the program that takes the user back to the query page. This variable is optional.

$$NS-prev-doc

Specifies the previous document in the search results item list. This variable is optional and is program generated.

$$NS-next-doc

Specifies the next document in the search results item list. This variable is optional and is program generated.

$$NS-insert-doc

Displays the selected document. To display the entire HTML document, this variable is mandatory.

$$NS-highlight-start

Highlights the start string. This variable is optional.

$$NS-highlight-end

Highlights the end string. This variable is optional.

$$NS-query

Notifies the CGI of the value of a pattern variable. This variable is optional.

$$NS-docs-found

Specifies the number of search items that were retrieved during a search. This variable is optional.

$$NS-docs-number

Specifies the number of documents searched. This variable is optional.

User-defined
You can change or define the value of these pattern variables. All are optional.

$$title

The title field of the HTML record, unless a title attribute was defined in iairs.ini

$$background

Background color

$$help

Link to help file

$$logo

Content provider logo

$$querygif

Takes the user back to the search results header page

$$tocgif

Takes the user back to the search results item page

$$previous

Takes the user to the previous document in the search results item list

$$next

Takes the user to the next document in the search results item list

$$copyright

Copyright notice

Search CGI implementations

This section describes how to implement specific search features available with specific reserved pattern variables.

Specifying multiple collections in pattern files

The $$NS-collection-list and $$NS-collection-list-dropdown variables create a multiple-select list of publications based on the entries in the dblist.ini file. However, a user may want to limit a search to a specific collection or set of collections. In this case, the NS-collection parameter should be passed once for each collection.

For example:

/search/iatoc?NS-collection=collnameX
&NS-collection=collnameY&...

or in a form:

<...>
<... name="NS-collection" value=collnameX"...>
<..."name="NS-collection" value=collnameY"...>
<...>

Passing pattern name variable to other CGI programs

You can have the iaquery CGI invoked directly with an alternate $$NS-query-pat (rather than using the default specified in the system.ini file.) For example:

/search/iaquery?NS-query-pat=xxx&

or, through a form:

<...> <...name= "NS-query-pat" value = "xxx" ...>

Note that the path to the search pattern is absolute.

You can specify a search pattern name in your search panel pattern file. For example, assume that a search panel is invoked through /bin/iaquery?NS-query-pat=yyyy& in your site's HTML page. In the search panel pattern file, the pattern name variable is appended to the CGI. By passing the search pattern name into the iatoc CGI program, any Search CGI program (including iatoc) is able to use or return the query interface that initiated the search.

Specifying queries and attribute searches

A query passed to the iatoc CGI can consist of multiple queries and query operators. The basic variables to use in setting up queries are NS-query and NS-query-op. Each of these variables and their usage are addressed in the applicable sections that follow.

Simple query
For a simple query interface, use the NS-query variable. It contains the query string that is passed to the text search engine. The format is:

/search/iatoc?NS-query=query string&. . .

Example:

/search/iatoc?NS-query=internet+browsers&. . .

or, through a form:

<...name=NS-query? value="value"...>

Example:

<...name="NS-query" value=internet browsers"...>

Note that the rules for passing values in forms or as parameters to a CGI apply here as well. For example, blanks are replaced with '+', and special characters are escaped with the "%" notation.

Compound query through a CGI
To specify a compound query, use the NS-query-op variable. The value of NS-query-op can be either:

NS-query-and

NS-query-or

Both are defined in system.ini as AND (NS-query-and) and OR (NS-query-or). For example, to invoke the CGI directly requires the following format:

/search/iatoc?NS-query=query string&NS-query-op=operator
&NS-query=query string&...

Example:

/search/iatoc?NS-query=internet+browsers+AND+netscape&...

or,

/search/iatoc?NS-query=internet+browsers
&NS-query-op=AND&NS-query-netscape&...

Compound query through a form
You can specify compound queries in a form. For example:

<input name="NS-query" value="" size=30>
<input type="radio" checked name="NS-query-op" value="AND">
<input type="radio" name="NS-query-op" value="OR">
<input name="NS-query" value="" size=30>

or, if using a form that will be generated from a pattern file processed by one of the CGIs:

<input name="NS-query.1" value="$$NS-query.1" size=30>
<input type="radio" checked name="NS-query-op.1"
value="$$NS-query-and">
<input type="radio" name="NS-query-op.2" value=NS-query-or">
<input name="NS-query.2" value=:$$NS-query.2" size=30>

Note that in the above case, the variable names are extended with item identifiers. The CGIs will process these correctly and save the name-value pairs so that subsequent regeneration from these pattern files are properly filled in.