SPIFACE version 2.00

SLAC 10 May 1995

What is SPIFACE?

SPIFACE is a simple interface between WWW and QSPIRES. Currently it is written as a REXX routine designed to be used as a cgi script.

SPIFACE can be used to create forms that users can fill in to perform SPIRES queries, or it can be used to perform SPIRES queries as the result of clicking on a WWW link. In either case SPIFACE is designed to be very simple to use, requiring no coding other than the HTML for the form or link itself, and possibly a SPIRES format to generate the requisite output.

Note

SPIFACE is derived from an earlier work called SPIFORM. SPIFACE is very similar to SPIFORM, but not completely backward compatible with the earlier version.

How do I use SPIFACE?

The simplest way to use SPIFACE is by exploiting the mapping it sets up between URL's and SPIRES commands. Consider the following URL: 

 http://www-spires.slac.stanford.edu/spires/find/freehep/www?author=johnson
Accessing this URL will cause SPIRES to use the FIND command to search the FREEHEP database using format WWW for records satisfying the search criterium AUTHOR=JOHNSON. (Try it by clicking here.)

URL syntax

The above example illustrates the general format for SPIRES URLS. They always begin with http://www-spires.slac.stanford.edu/spires. The following term (/find in the example above) specifies the spires command to be issued (currently only /find is supported, but others such as /browse will be added). The next term (/freehep in the example above) specifies the database to be used, and the third term (/www in the example above) gives the format to be used for output. Following teh ? is the database search specification (author=johnson in the above example).

More complex searches can be specified using & and | symbols to give multiple search terms. For examples: 


 http://www-spires.slac.stanford.edu/spires/find/freehep/www?author=johnson&date=1992
(Try it by clicking here.)

Modifying the Default SPIFACE behaviour

You can modify the default behaviour of SPIFACE by creating an options file. (See where does the option file go? below.) Each line of the options file is of the form: 
  Keyword = Value
The following keywords can be used in the options file.
COMMAND
The name of the command that QSPIRES will issue. This overrides the command implied by the URL.
SUBFILE
The name of the SPIRES subfile (database) that QSPIRES will search. This overrides the subfile implied by the URL.
MATCH
The term that QSPIRES will put between search terms, the default is AND
PRE
Normally SPIFACE will put a <pre> ... </pre> around the spires output automatically. If you do not want this specify a value of 0.
HEADER
Normally SPIFACE will generate a header before the SPIRES output. If you do not want this set the value of this switch to 0.
TRAILER
Normally SPIFACE will generate a trailer after the SPIRES output. If you do not want this set the value of this switch to 0.
OWNER
Use this switch to specify an owner for the generated output. For example owner = cottrell. This will automatically generate a /owner link at the bottom of the SPIRES output.
FORMAT
The format that QSPIRES will use for the output, the default is unspecified (i.e. the QSPIRES default for the subfile will be used).
FORMATS
A list of alternate formats that can be used. If specified the output from the query will contain a small form which will allow the user to switch between the formats specified.
LENGTH
QSPIRES limits the lengths of lines returned from SPIRES. This can cause truncation of lines, especially if they contain many references to long urls. The default value of LENGTH (through SPIFACE) is 150. This can be increased using the LENGTH element up to 2048 (but dont make it this long unless you have to, it can cause problems with QSPIRES running out of buffers).
NOMATCH
Specify an HTML file to be returned in the event that no matches are found in the database. (See specifying files).
HEAD
Specify an HTML file to replace the normal header generated by SPIFORM. (See specifying files).
TAIL
Specify an HTML file to replace the normal trailer generated by SPIFORM. (See specifying files).
SLACONLY
Restricts access to SLAC nodes only. The value is the name of an HTML file to be returned inb response to an attempt to access information from outside of SLAC. (See specifying files).

Specifying Files

Wherever a file can be spcified above, it must be specified as a simple file name with no directory (e.g. junk.html). If the URL for the query was 
  http://www-spires.slac.stanford.edu/spires/command/subfile/format?a=b
then SPIFACE will look for the file in the following directories, taking the first occurence it finds. 
  /afs/slac.stanford.edu/www/spires/command/subfile/format/
  /afs/slac.stanford.edu/www/spires/command/subfile
  /afs/slac.stanford.edu/www/spires/command
  /afs/slac.stanford.edu/www/spires

Where does the options file go?

The rules for searching for an option file are similar to those for searching for other files above, but in the case of the optioon file the directories are searched in the opposite order. In each directory if a file called spiface.opt is found it is read, and then the search continues with the next directory. Options specified in the most recently read options file override those specified in earlier options files.

Options specified at the lowest level will affect all SPIRES searches, unless overriden for a specific search. Specifying options at the subfile level causes those options to apply to all searches in that subfile (unless overriden at the format level).

Using SPIFACE with HTML forms

Consider the following very simple example: 
     <form action="/cgi-bin/spiface">
     Book Title <input NAME="TITLE">
     </form>
This would generate a form which would look like this:

Book Title

When filled in (with the value ELEPHANT for example) it would generate the following QSPIRES query. 

     QSPIRES FIND TITLE ELEPHANT
and show the results.

A second slightly more complex example: 

     <form action="/cgi-bin/spiface">
     Book Title <input NAME="TITLE"><br>
     Book Author <input NAME="AUTHOR">
     <input type="hidden" name="SUBFILE" value="BOOKS">
     <input type="submit">
     </form>
would look like this

Book Title
Book Author

and would generate a QSPIRES query of the form: 

     QSPIRES FIND TITLE ELEPHANT AND AUTHOR BABAR ( IN BOOKS

Hidden Elements

Note the use of a hidden element in the above form to specifiy which subfile should be searched. The following items are designed to be used with fields of type hidden within the form. They are used to pass additional information from the form to QSPIRES. Note that within an HTML form, fields of type HIDDEN are not normally visible on the screen, so the person filling in the form will not see these items.

Suppressing the AND between search terms

Normally SPIFACE automatically inserts the word AND between search terms. This can be changed using the MATCH keyword defined above, but occasionally it is convenient to just omit the AND between successive search terms completely. Consider the following example: 
     <form action="/cgi-bin/SPIFACE">
     Date <input NAME="MONTH"><input NAME="YEAR">
     </form>
This would generate a QSPIRES query of the form: 
      QSPIRES FIND MONTH JANUARY AND YEAR 1994
Instead one could use 
     <form action="/cgi-bin/SPIFACE">
     Date <input NAME="DATE"><input NAME="*">
     </form>
to generate a spires query of the form 
      QSPIRES FIND DATE JANUARY 1994
Note the use of the special value * for the name of the second field, which suppresses both the name and the preceeding AND in the QSPIRES query.

TonyJ