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.
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.
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:
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.
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>
The search panel pattern file uses the pattern variables listed in Table 10.1.
<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">    <input type="submit" value=Search"></td></tr>
</form>
</table>
<hr>
<h5>$$copyright
</h5>
</body>
</html>
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:
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>The pattern variables in this pattern file are described in Table 10.2.
</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"">    <input type="submit" value="Search"></td></tr> </form> </table> <table width="100%">
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.
The pattern variables in this pattern file are described in Table 10.3.
<tr><td valign=top>
  <a href="$$NS-record-cgi"><img $$icon></a>  </td><td>
<a href="$$NS-record-cgi">
<strong>$$NS-doc-number: $$title</strong>>/a> <font size=-2>(Highlighted)</font>
<table width="100%">
<tr><td>   </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>
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>
The only pattern variable in this pattern file is $$copyright, which is defined in the sample iairs.ini as the copyright notice.
<h5>
</table>
</h5>
</body>
</html>
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>
The pattern variables in this pattern file are described in Table 10.4.
<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>  <a
href="/sbin/iarecord?<param1>=<value1>&<param2>=<value2>&...
"><img /sbin/iarecord?<param1>=<value1>&<param2>=<value2>&...
></a>  <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>&...
    $$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>  <a href="/sbin/iarecord?<param1>=<value1>&<param2>=<value2>&...
"><img /sbin/iarecord?<param1>=<value1>&<param2>=<value2>&...
></a>  <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>
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.