Custom Output Formats and SGML Config Files

• Background
• Basic Usage Instructions
• Config File Format

SearchUIC is a generic CGI script that accepts information from an HTML form, optionally reads a config file from disk, runs a query on a search engine (which previously indexed Web pages at UIC), and presents the output. SearchUIC can be used by anyone publishing documents on one of the ADN Web servers (icarus and tigger, as of this writing), without requiring prior authorization from the Academic Computing and Communications Center.

You must prepare at least one of two files:

1. The original HTML form
2. A configuration file, to be read by the SearchUIC CGI script, which tells the script how to behave when your HTML form is submitted.

In more detail:

1. Prepare the HTML form, put it on the Web, and make sure the HTML is valid.
2. Prepare a configuration file for your form. This config file must also be placed on the Web on tigger or icarus, although it is not intended to be publicly viewed. The name of the config file is arbitrary, and each HTML form should have its own associated config file. For purposes of this documentation, I'll assume the config file is named config.sgml.
3. You will need to know the URL of this config file; more precisely, you will need to know the path part of the URL. That is, the URL without the "http://www.uic.edu/" host name part. For example, I have a file whose URL is http://www.uic.edu/~bobg/config.sgml; and, therefore the config file path is simply /~bobg/config.sgml. Make sure your config file is publicly readable, using the command chmod a+r config.sgml if necessary. If you can actually retrieve the config file with a Web browser using the proper URL, the permissions are fine.
4. Inside the HTML form itself, you will, of course, need an <form action=" ..."> tag. If your config file is on tigger (doesn't matter where the form itself is), then this tag should be:

   
   <form method="POST" action="http://www.uic.edu/htbin/search/SearchUIC/path_of_config_file"> 
   
   

   So, for the above example, it would be:

   
   <form method="POST" action="http://www.uic.edu/htbin/search/SearchUIC/~bobg/config.sgml">
   
   

   (If this were on icarus, use www2.uic.edu instead of www.uic.edu)
5. The format of the config file can be complicated, and will be discussed in the next section. For now, you can construct a minimal config file for testing. It should look like:

          <!DOCTYPE search SYSTEM 'Search-1.0.dtd'>
          <search name="mysearch">
          </search>
          

Note: If you use both an HTML form and a config file, and happen to have the same variable set in both, the value in the HTML form takes precedence.

The config file is defined by a set of tags, similar in spirit to HTML. But the actual tags differ because the meaning is different. If you leave most of the file blank, defaults will be assumed, but you can override these defaults to a large degree.

The tags are described below, but you may (i.e., will) be interested in examples. You might bring one up in a separate Web window to compare it to the tag descriptions below.

(For the technically interested, I invented a small tag set using SGML, a meta-language for define tag sets. HTML is another such example of an SGML-defined tag set. And, since you already know about how to specify HTML tags, the SearchUIC tags won't be too surprising.)

The SGML tags for the config file are of three general types.

Putting the search results into HTML responses

<input name="myname" type="text" >

You probably know that the quotes in the above <input> tag are not necessary unless the values of name or type have embedded spaces. Although it might be possible to use embedded spaces in the name of an input field, don't try this unless you have very strong proofreading abilities and/or like pain. If you do try this, make sure to use the ${myname} format to refer to variables.

There are a number of variables pre-defined for you, all of which start with $s_. You may need to reset some of these variables, either in the HTML form or in the config file. In general, your variables should be of the following form:

Internal Variables

These variables are read-only:

These variables can be read or set:

The <!DOCTYPE> tag

		<!DOCTYPE search SYSTEM 'Search-1.0.dtd'> 

I've defined 'Search-1.0.dtd' to point to 'Search-1.0b1.dtd' as of this writing. So you have a choice:

1. Use 'Search-1.0.dtd', which will always point to the current beta release, and to the production release later on. This might cause your config files to break if I have to change the DTD in incompatible ways. (This is possible, although unlikely, during beta testing.)
2. Use 'Search-1.0b1.dtd' which points to a specific beta release. This should be stable (or stably broken, depending). But when I release the production version, I'll remove all beta copies, so you'll have to change your tags at that point.

The <SEARCH> tag

The config file contains a (possibly large) element in the form: <SEARCH> ... </SEARCH> and all the other tags will sit inside. The <SEARCH> tag takes some attributes:

	<SEARCH DEBUG NAME="search_name">

The <SET> tag

Warning: The <SET> tag takes an if attribute. If the if attribute does not exist, the SET action takes place before the HTML file is read. But if the if attribute is set, the action takes place after the HTML file. This means that values set by the HTML file will override those SET statements that don't contain ifs, but may be overridden by SET statements that do contain ifs. It also means that the if attribute may depend on values contained the the HTML file, but not on values generated by the search itself. The format of this tag is:

<SET NAME="variable_name" VALUE="variable_value" >

The <EVAL> tag

Yes, it seems complicated. But proper use of this tag will let you present, as part of the result of a search, an HTML query form whose details depend on the original query form and on the outcome of the search. This is probably clearer in the examples.

The format is:

<EVAL NAME="variable_name" VALUE="expression" IF="if_cond">

The <RESPONSE> tag

	<RESPONSE NAME="mname" IF="if_cond" URL="url">

The sections are evaluated in order. If the first to evaluate to true contains a URL redirection, the output is redirected. Otherwise, all sections that evaluate to true are sent back to the client browser.

The body of a <RESPONSE> section should contain the HTML code to print. HOWEVER, the enclosed HTML tags must be protected from the SGML parser for this to work. This means that a response section should look like:

<RESPONSE NAME="resp1">
<![CDATA[
here is some <b>HTML</b> code
]]>
</RESPONSE>

Important Note: If you choose to use the <RESPONSE> tags to generate any part of the HTML response, you are entirely responsible for generating the whole response page, from the beginning <html> tag to the ending </html> tag. Don't presume that SearchUIC will do any of this for you, unless one of the following is true:

• You omit the <RESPONSE> tags, and let SearchUIC generate its default response.
• You use URL redirection within the <RESPONSE> tag.

The "if_cond" conditions for <EVAL> and <RESPONSE>

The optional if conditions specified in the <EVAL> and <RESPONSE> sections are expressions separated by Boolean ANDs and ORs. But the conditions are not totally general, because parentheses are not allowed, and the ANDs bind tighter than the ORs. Therefore

exp1 AND exp2 OR exp3 OR exp4 AND exp5

(exp1 AND exp2) OR (exp3) OR (exp4 AND exp5)

Each expression is evaluated as a string comparison or numeric comparison, depending on the operator used. Each expression should take one of the following forms. Note that each comparison operator must be delimited with blanks.