So far we have discussed how to modify the model batch and HTML form files to point at your TDBs. Once you understand how TACTweb gets its information from your form, you are in a better position to design your own special forms that interact with your TACT databases.
The material in this section assumes a basic technical understanding of CGI and HTTP. Here is a brief overview of these things.
TACTweb supports three types of queries from the WWW client:
Generally, TACTweb in its KWIC and Variable Context display will generate the HTML that includes hypertext links) to trigger this mechanism. You are unlikely to want to use this mechanism yourself.
Usually, most of your control of TACTweb will be gained by generating your own forms and using the "Post" mechanism. We'll describe this first. However, there are occasions when you may want to interact with TACTweb via a "Get" request -- we'll describe this below.
Forms in HTML allow you, the form designer, to present options to the FORM user that allows him/her to, by setting values in the form you have designed, pass information, and thereby control the server CGI software. As you have already seen, different form elements types such as text fields and selection lists can be combined into a single form. By changing the type of information you pass to TACTweb, and changing the form elements used to garner this information from your users, it is possible to generate a great variety of alternative forms for special purposes. There are examples below, and in the student tutorial material included with the TACTweb distribution. Generally, if you wish to tailor the TACTweb system for your own needs, you will do so by adapting the query HTML form you will provide for your users -- changing default settings, coding certain options on the form in such a way that they cannot be changed, etc. The next, and largest portion of this document, will outline how this is done, and will list the options available to you.
By changing the form specification on can radically change the options presented to your form user. To get an idea of the types of things that can be done, take a look at Computer Assisted Text Analysis: An Online Workbook, provided with the TACTweb documentation. There, you will find many examples of forms which are simplified specifically for the purposes of instructional use.
The following code fragment comes from there.
<FORM METHOD="POST" ACTION="/cgi-bin/dotactq.bat"> <OL> <LI>Type in your list of words (separated with commas!)<P> <INPUT NAME="query" VALUE="" INPUT SIZE=40 MAXLENGTH=40><P> <LI>Click on this button <INPUT TYPE="submit" VALUE="Submit Query"> to see a KWIC display of the list of words you specified.<P> <li>Remember to click the <STRONG>Back</STRONG> button to return here. </OL> <INPUT NAME="qcontext_unit" VALUE="word" TYPE="hidden"> <INPUT NAME="qcontext_before" VALUE="5" TYPE="hidden"> <INPUT NAME="qcontext_after" VALUE="5" TYPE="hidden"> <INPUT NAME="display_type" VALUE="KWIC" TYPE="hidden"> <INPUT NAME="dcontext_unit" VALUE="line" TYPE="hidden"> <INPUT NAME="dcontext_before" VALUE="3" TYPE="hidden"> <INPUT NAME="dcontext_after" VALUE="3" TYPE="hidden"> </FORM>
Note that here there are many "INPUT" elements, but that only one of them (with the name "query") is shown to the form user as a field. This form demonstrates the use of the "hidden" type of INPUT element which causes the browser to send back a value as if it were a part of the form, but doesn't give the form user a chance to alter the value it sends. The INPUT element "<INPUT NAME="display_type" VALUE="KWIC" TYPE="hidden">", for example, specifies a "display_type" of "KWIC", but doesn't show choice to the user and doesn't allow him/her to alter it -- due to the presence of the TYPE attribute of "hidden".
When TACTweb receives information about how someone filled in a form, it needs to be able to tell what entered values belong to what pieces of information -- it needs to know, for example, the the value "5" is associated with, say, the number of units to display before the located position, rather than after. This identification of what value is being provided in what field is the job of the NAME attribute in form elements. When a form is submitted, the browser will send not only the values it finds in the form, but also, for each value the name associated with it. TACTweb, in turn, is designed to look for certain names, and take the values associated with them as control information. In the rest of this document, we call form elements which have these names (and which can be used to pass information to TACTweb) "NAMEd Elements".
Even though the demonstration form tactweb.htm includes a number of the NAMEd elements, it doesn't contain them in all. In this section we describe all the possibilities.
Use the "display_type" element to specify the display TACTweb is to create. Legal values TACTweb will recognize are:
Where:
Note that the names must be given in all-caps. If not specified by you, TACTweb will generate a KWIC display. Be sure that, if you request a particular display type, or allow the form user to select a particular form type, that all the information that particular form will need is provided. The information the forms need, and the NAMEd Elements that provide them is summarized below.
Because only a fixed set of values are acceptable to TACTweb, the HTML form "SELECT" element is the form element ot use:
<SELECT NAME="display_type"> <OPTION VALUE="KWIC" SELECTED>KWIC <OPTION VALUE="VAR"> Variable Context Display <OPTION VALUE="DIST"> Distribution <OPTION VALUE="WORD"> Word List </SELECT>
Use the "ref_template" NAMEd INPUT element to control the TACT reference template TACTweb will use while generating a display. If the "ref_template" is not given, or is blank, the default template stored in the TDB will be used.
If you wish to allow your user to specify a template on their own, the INPUT element's "field" form is the best choice. In this example, an initial value that is to appear in the form when it is first displayed, and return to TACTweb unless changed is coded using the "value" attribute:
<INPUT NAME="ref_template" VALUE="$speaker,$act,$scene" INPUT SIZE=40>
Alternatively, if you wish to fix the reference template for a particular query to something different from the one in the TDB, you could code a hidden INPUT element:
<INPUT NAME="ref_template" VALUE="$speaker,$act,$scene" INPUT SIZE=40 TYPE="hidden">
TACTweb must be provided with a TACT query so that it knows what to search for in your TDB. For queries with collocation operators, TACTweb will also need to be told what measures to use for "nearness" of one word to another. The "query" NAMEd INPUT element is used to give TACTweb a query. The "qcontext_unit", "qcontext_before", "qcontext_after" can specify the "nearness measures".
A query must be provided in all TACTweb requests. If none is found in the form data that is passed to TACTweb it will generate an error' message and stop immediately. There are two ways to specify one via a form:
This more complex query format is useful when the you want to fix some portions of the query request (by means of a hidden INPUT element), and allow the form user to provide other parts. See an example, below.
Recall that the collocation operators require "context" data which indicates how near two objects need to be to each other to represent a collocation. The "qcontext_unit", "qcontext_before" and "qcontext_after" NAMEd INPUT elements provide this information. If, for example, a word need occur 5 words before or 5 words after another word to be considered a collocate, the appropriate values are:
If a word need occur in the same sentence as the target to be a collocate, appropriate values are:
(assuming, of course, that "sentence" was coded within the TDB database.)
Since TACTweb will only accept "qcontext_unit" values that correspond to TACT RefIDs for the TDB it is using, it is common practice to restrict your form user to legal values by using a SELECT element.
In the following example, the user is able to enter a query consisting of several lines. The Query Context is restricted to a WORD range. Default values of "5" are given for both the before and after ranges, and the "INPUT SIZE" and "MAXLENGTH" attributes are coded so that the form user cannot enter a number that is too large and so that the browser knows that it can display a small field.
<TEXTAREA NAME="query" ROWS=4 COLS=40></TEXTAREA> <B>Query Context (in words)</B> <INPUT NAME="qcontext_unit" VALUE="word" TYPE="hidden"> <P>Before: <INPUT NAME="qcontext_before" VALUE="5" INPUT SIZE=5 MAXLENGTH=5> After: <INPUT NAME="qcontext_after" VALUE="5" INPUT SIZE=5 MAXLENGTH=5>
Here is a second example which makes use of the ability to provide several separate query component in a single form. In this case, the form designer wants to ensure that the selection criteria provided by the form user is followed by a refinement which selects only those positions in the text spoken by Hamlet:
<INPUT NAME="query0" VALUE="(" TYPE="hidden">
<INPUT NAME="query1" VALUE="" INPUT SIZE=40 MAXLENGTH=40><P>
<INPUT NAME="query2" VALUE=");when speaker = Hamlet" TYPE="hidden">
Here, the query TACTweb receives will have three parts: the first part is simply the single character "(", the second part will come from a field in the form, and the third part will consist of ");when speaker = Hamlet". If the form user entered the specification, "ab.*", for example, the resultant full query would be "(ab.*);when speaker = Hamlet".
For the KWIC display four options are valid.
Values TACTweb will accept for the dorder option for the KWIC display are:
Where:
If dorder is not coded, a KWIC display will appear in NATURAL order.
This NAMEd ITEM element indicates whether TACTweb should show the line endings in the one line context it generates or not. TACTweb will accept the values:
If not coded, a KWIC display will include line ending markers.
Use the "kwiclen" NAMEd Element to specify the number of character (including reference info) that should appear in each KWIC line display. Meaningful values should be from 50-255.
Use the "kwiccentre" NAMEd Element to specify the position where the keyword should be in a KWIC display. Meaningful values must be less than the value associated with "kwiclen", and greater than the maximum length of the reference information being displayed.
In this form fragment, the user is presented with predetermined options: only the KWIC display will be generated, only in POSITION order, and with no line endings being shown:
<INPUT NAME="display_type" VALUE="KWIC" TYPE="hidden"> <INPUT NAME="dorder" VALUE="POSITION" TYPE="hidden"> <INPUT NAME="dbar" VALUE="NO" TYPE="hidden">
For the Variable Context Display the "dorder" NAMEd INPUT element is recognized, and works as it does in the KWIC display. In addition to "dorder", a group of 3 NAMEd INPUT elements control how much context is generated.
As in TACT, to specify a context for the display one must name a unit (in terms of a TDB RefID), and how many of these units should precede and follow the occurrence of that unit that includes the selected position. Note the similarity between this context, and the one used to select collocates within the query language (described above).
The NAMEd INPUT elements that control the display's context are:
If not coded, TACTweb will generate Variable Context displays showing 5 lines before and after the line containing the selected position.
Values TACTweb will accept for the dorder option for the Variable Context display are:
Where:
If dorder is not coded, a Variable Context display will appear in NATURAL order.
As in TACT, the Distribution Display can display results based on position in the text, by Reference ID, or by the headword form. Which is displayed is controlled by the NAMEd INPUT element "disttype".
This option controls the type of distribution display TACTweb will generate. TACTweb will recognize the following values:
Where
The NAMEd INPUT element "distposstart" (as a percentage of the entire text) indicates the starting end of the display. "distposend" controls the ending, and "distposby" controls the division points.
If not given, the distribution will be shown from the begining of the text to the end, in 10% divisions.
"distref" must be coded if a "REFERENCE" Distribution Display is requested. It indicates the name of the REFid on which the distribution should be created.
Optionally, you can also code a NAMEd item "distreforder" to control the ordering of the distribution-by-reference display -- either alphabetical by reference value, or in first order of occurrence of the reference in the text. Two values (must be coded in caps) that are supported are:
ALPHA, TEXT
An example of its used, coded as a select object is:
<SELECT NAME="distreforder"> <OPTION SELECTED VALUE="ALPHA">Alphabetical Ordering <OPTION VALUE="TEXT">Textual Ordering </SELECT>
or (in a hidden input object)
<INPUT TYPE="hidden" NAME="distreforder" VALUE="TEXT">
The Normalized Distribution Display works like the standard Distribution Display except the length of the columns is normalized -- made relative to the total number of words found in each group that it represented.
NAMEd Element "distref" must be coded for a Normalized Distribution Display. It indicates the name of the REFid on which the normalized distribution should be created. Note that the REFid must be for a TACT database "string" reference rather than a "numeric" reference, because it is only with the "string" reference type that information about the number of words is stored for each reference value.
If the "-d" option is coded when TACTweb is started, TACTweb will expect the name of the TDB to be given to it via the form data. The NAMEd INPUT element that does this is "tdb_file".
In this form fragment, the user is presented with a list of TDBs from which s/he can choose one. Note the use of the VALUE attribute in the OPTION element which allows the actual TDB to be passed to TACTweb, but the name of the play to be shown to the user.
<p>Select play here: <SELECT NAME="tdb_file"> <OPTION SELECTED VALUE="midsumme.tdb">A Midsummer's Night's Dream <OPTION VALUE="rjf.tdb">Romeo and Juliet <OPTION VALUE="hamlet.tdb">Hamlet </SELECT>
As was mentioned earlier, generally a form is used to collect from the user the information necessary to generate a query to TACTweb. However, it is occasionally useful to put a query into a standard hyperlink. Clicking here, for example, generates a KWIC display of all words beginning with "ab" in the Midsummer Night's Dream text.
To hide a query in a link uses the "Get" TACTweb query mechanism, and requires you to use the "query" part of a URL. For TACTweb, the format is:
<a href="/cgi-dos/dotactq.bat?Qab.*">
Note the href item, which contains a URL directory of "cgi-dos" and specifies the batch file dotactq.bat to run which will invoke TACTweb against the Midsummer.tdb database. Following the name of the batch file name in the URL is the "?" symbol, which announces the beginning of the URL query component. Following the "?" is the capital letter "Q" which will be given to TACTweb, and will tell it that you wish to provide a TACTweb query immediately following. The query itself ab.* can be any standard TACTweb query construct.
If necessary, other options can be specified following the TACTweb query. They are specified by providing one or more NAMEd Element names, an equal sign, and a value for that NAMEd element. If there are more than one NAMEd element needed, each name/value pair should be separated from each other (and the initial query) by a "&". To both specify a query and ask for a Variable Context display to be generated, for example, one could code:
<a href="/cgi-dos/dotactq.bat?Qab.*&display_type=VAR">
Web design Alex Stevens, content Geoffrey Rockwell or John Bradley. March 7, 1997