Examples and Tutorial

The above descriptions are probably not clear without several examples. You can use these examples in several ways:

• View the form, and view the document source to see how the input fields are constructed.
• View the associated config file.
• Fill out the form and make a search. Note carefully how the output tells you exactly what query was made, along with the query results.
• Find an example close to your needs. Copy it to your directory, and modify as necessary.

This example shows the bare-bones minimum, taking all defaults. It has only one general input field. But the form is active, and you can type in various search words, or a full Verity Language query if you know the syntax. The two crucial parts are the <FORM> tag and the simple <INPUT> tag. You must understand these parts, or you won't get any further. By the way, since there is no config file in this example, the <FORM> does not need to mention any config file.

In addition to a general word query field, this example contains two <SELECT> boxes that specifically restrict the search to a given directory substree (i.e. restrict the search to URLs with specific words in them.)

Also, the two <SELECT> boxes illustrate the difference between single selection and multiple selection, and the difference between the operator that applies to each selection, and the moperator that connects the selections together.

This example shows how to make a more complicated query, giving the user the option to AND or OR the search words, and to limit the search to the TITLE field or URL field. In particular, it illustrates generating a single search term using multiple HTML tags. The HTML tags are associated with each other through the use of a common string in the NAME part of the tags.

This examples shows how to set the variables s_maxhits (for changing the max number of returned hits), s_sortby (for changing the order of returned hits), and s_resultsby (for changing the information displayed about each returned hit). It also uses a hidden field to restrict the search to a given set of URLs (ie a given subdirectory tree).

This is exactly like example 4. The only difference is that the hidden field is moved from the HTML form to the config file. This is the first, fairly minimal, use of a config file. The <SET> tag is used in the config file, and has the same effect as the <INPUT TYPE="hidden"> tag in the example 4 HTML file.

Of course, since a config file is used, the ACTION attribute in the <FORM> tag must now contain the path to this config file.

Back to the very simple query form, but with use of the config file to control the output format. This shows the simple use of the <response> tag in the config file.

Quite similar to example 6, but three <response> elements are used, with conditions based on the s_status variable. This lets you return different screens depending on OK, NOHITS, or ERROR conditions.

Similar to example 7, but the original HTML form is reproduced in the output, so that the user can easily do another search. The key point is that the VALUE attribute is used, along with the $query variable, so that the new default search is identical to the search just completed.

Note the tag:

<input type=text name="query" value="$query" size=50>

The key point is that $query is replaced with the value of the internal variable, after the search is completed, but before the HTML from the config file is rendered for output. Therefore, by the time the new HTML form is returned to the browser, this value is already set to the value from the previous query. You can see this by Viewing the Document Source on the returned HTML form, and comparing it with the <response> tag in the config file.

Very similar to example 8, but now the embedded HTML form is more complicated. Instead of just using <input> tags, now it includes a <select> box to set s_sortby. The problem is that we can't use the value of $s_sortby to directly set the selected value within the <select> box. So I invent some additional variables, and use the <eval> tags to set them, based on the $s_sortby variable. You have to see the config file to understand it.

We can pass search parameters to the CGI script through a URL, rather than use an HTML form. Here's a URL that will search for the string fortran, taking most defaults:

http://www.uic.edu/htbin/search/SearchUIC?query=fortran

Searches are always limited to a maximum number of hits, determined by s_maxhits. The actual number of hits is returned in the variable $s_nres, which may be equal to or less than $s_maxhits. However, it is not necessary to start the results at number 1. In fact, the first hit starts at s_starthits, and the last hit is returned in $s_stophits. And if there were potentially even more hits to be returned, the variable $s_more is set to + (a plus sign) and the variable $s_next is set to one more than $s_stophits. The upshot is that you can generate a link to search "The Next 10 hits" on your return HTML, using these variables.

The URL that generates the "Next 10" link is rather long, although similar in spirit to example 10. Here are the pieces:

element of URL	meaning
http://www.uic.edu	name of machine
/htbin/search/SearchUIC	name of cgi script
/depts/accc/webpub/search/config11.txt	name of config file
?	separator for arguments
query=$s_qstring	$s_qstring contains the complete verity query, and of course the query field can accept an entire complicated query.
&s_maxhits=$s_maxhits	retain the value of $s_maxhits
&s_sortby=$s_sortby	retain the value of $s_sortby
&s_starthits=$s_next	start the new search with the value of $s_next from the last search

That's right, you don't have to have an HTML file. Of course you knew that, because example 10 didn't use one. But in this case, We'll use a link to invoke the config file without doing a search. The config file will detect this, and display the HTML search form, after all. This is similar to example 8, where we embedded the HTML search form in the config file, so that the user could repeat or refine the search easily. Same idea, but in this case, we only need to define the form once in the config file, and skip the standalone HTML form.

Here's the URL to get this started:

http://www.uic.edu/htbin/search/SearchUIC/depts/accc/webpub/search/config12.txt

This is a full-featured example and uses most of the tricks discussed. As before, we don't need an HTML file, just a URL:

http://www.uic.edu/htbin/search/SearchUIC/depts/accc/webpub/search/config13.txt?xprt=0

• Has select boxes to control $s_sortby and $s_resultsby.
• Constructs a "Next 10" link on the fly.
• Gives different responses for error conditions.
• Puts a search form on the response page, with defaults set from the previous search.
• Constructs a new internal variable, $xprt, to allow toggling between a simple search screen and an advanced search screen.
• Keeps everything in a single config file.

Yes, you're just about done. But what if the config file doesn't act act you think it should? First thing to try is set the DEBUG attribute in the <search> tag. This will give you a list of variables and their values, as well as info on which <response> sections will be returned, and what their HTML values will be. This example is identical to example 13, with DEBUG set.

http://www.uic.edu/htbin/search/SearchUIC/depts/accc/webpub/search/config14.txt?xprt=0

Of course, the above URL gives the debug response for the search indicated in the URL (in the above case, no search at all). You can test other aspects by putting in different conditions into the URL. For example, to generate a debug response for a search for "fortran", use this:

http://www.uic.edu/htbin/search/SearchUIC/depts/accc/webpub/search/config14.txt?xprt=0&query=fortran