FORM
tag specifies a fill-out form within
an HTML document. More than one fill-out form can be in a single document, but
forms cannot be nested.
<FORM ACTION="url"> ... </FORM>
The attributes are as follows:
ACTION
is the URL of the query server to which the form
contents will be submitted; if this attribute is absent, then the current
document URL will be used.
METHOD
is the HTTP/1.0 method used to submit the fill-out
form to a query server. Which method you use depends on how your particular
server works; we strongly recommend use of (or near-term migration to)
POST
. The valid choices are:
GET
-- this is the default method and causes the fill-out
form contents to be appended to the URL as if they were a normal query.
POST
-- this method causes the fill-out form contents to be
sent to the server in a data body rather than as part of the URL. ENCTYPE
specifies the encoding for the fill-out form
contents. This attribute only applies if METHOD
is set to
POST
-- and even then, there is only one possible value (the
default, application/x-www-form-urlencoded
) so far. NOTE: If you want to use theInside aMETHOD
of typePOST
with the NCSA httpd you will need to get version 1.0a5 or later.
FORM
you can have anything except
another FORM
. Specifically, INPUT
,
SELECT
, and TEXTAREA
tags are used to specify
interface elements within the form.
Forms are not automatically visually differentiated from the rest of a
document. We recommend using the HR
(horizontal rule) tag before
and after a form to cleanly differentiate it from surrounding text and/or other
forms.
INPUT
tag is used to specify a simple
input element inside a FORM
. It is a standalone tag; it does not
surround anything and there is no terminating tag -- i.e., it is used in much
the same way as IMG
.
In Mosaic for X, various types of INPUT
tags are instantiated as
Motif widgets (text entry fields, toggle buttons, pushbuttons, etc.).
The attributes to INPUT
are as follows:
TYPE
must be one of:
NAME
are grouped into "one of many"
behavior)
NAME
is the symbolic name (not a displayed name -- normal
HTML within the form is used for that) for this input field. This must be
present for all types but "submit" and "reset", as it is used when
putting together the query string that gets sent to the remote server when the
filled-out form is submitted.
VALUE
, for a text or password entry field, can be used to
specify the default contents of the field. For a checkbox or a radio button,
VALUE
specifies the value of the button when it is checked
(unchecked checkboxes are disregarded when submitting queries); the default
value for a checkbox or radio button is "on". For types "submit" and "reset",
VALUE
can be used to specify the label for the pushbutton.
CHECKED
(no value needed) specifies that this checkbox or
radio button is checked by default; this is only appropriate for checkboxes
and radio buttons.
SIZE
is the physical size of the input field in characters;
this is only appropriate for text entry fields and password entry
fields. If this is not present, the default is 20. Multiline text entry
fields can be specified as SIZE=width,height
; e.g.
SIZE=60,12
. Note: the SIZE attribute should not be used to
specify multiline text entry fields now that the TEXTAREA tag is available.
MAXLENGTH
is the maximum number of characters that are
accepted as input; this is only appropriate for text entry fields and
password entry fields (and only for single-line text entry fields at
that). If this is not present, the default will be unlimited. The text entry
field is assumed to scroll appropriately if MAXLENGTH
is greater
than SIZE
. <FORM> ... </FORM>
, any
number of SELECT
tags are allowed, freely intermixed with other
HTML elements (including INPUT
and TEXTAREA
elements)
and text (but not additional forms). In Mosaic for X, SELECT
tags are instantiated as Motif option menus and scrolled lists.
Unlike INPUT
, SELECT
has both opening and
closing tags. Inside SELECT
, only a sequence of OPTION
tags -- each followed by an arbitrary amount of plain text (no HTML
markup) -- is allowed; for example:
<SELECT NAME="a-menu"> <OPTION> First option. <OPTION> Second option. </SELECT>The attributes to
SELECT
are as follows:
NAME
is the symbolic name for this SELECT
element. This must be present, as it is used when putting together the
query string for the submitted form.
SIZE
: if SIZE
is 1 or if the SIZE
attribute is missing, by default the SELECT
will be represented
as a Motif option menu. If SIZE
is 2 or more, the
SELECT
will be represented as a Motif scrolled list; the value of
SIZE
then determines how many items will be visible.
MULTIPLE
, if present (no value), specifies that the
SELECT
should allow multiple selections (n of many
behavior). The presence of MULTIPLE
forces the
SELECT
to be represented as a Motif scrolled list, regardless of
the value of SIZE
. OPTION
are as follows:
SELECTED
specifies that this option is selected by default.
If the SELECT
allows multiple selections (via the
MULTIPLE
attribute), multiple options can be specified as
SELECTED
. TEXTAREA
tag can be used to
place a multiline text entry field with optional default contents in a fill-out
form. The attributes to TEXTAREA
are as follows:
NAME
is the symbolic name of the text entry field.
ROWS
is the number of rows (vertical height in characters) of
the text entry field.
COLS
is the number of columns (horizontal width in
characters) of the text entry field. TEXTAREA
fields
automatically have scrollbars; any amount of text can be entered in them.
The TEXTAREA
element requires both an opening and a
closing tag. A TEXTAREA
with no default contents looks like this:
<TEXTAREA NAME="foo" ROWS=4 COLS=40></TEXTAREA>A
TEXTAREA
with default contents looks like this:
<TEXTAREA NAME="foo" ROWS=4 COLS=40> Default contents go here. </TEXTAREA>The default contents must be straight ASCII text. Newlines are respected (so in the above example there will be a newline both before and after "Default contents go here.").
action?name=value&name=value&name=value("
action
" here is the URL specified by the
ACTION
attribute to the FORM
tag, or the current
document URL if no ACTION
attribute was specified.)
Strange characters in any of the "name" or "value" instances will be escaped as usual; this includes "=" and "&". Note: This means that instances of "=" that separate names and values, and instances of "&" that separate name/value pairs, are not escaped.
For text and password entry fields, whatever the user typed in will be the value; if the user didn't type anything, the value will be empty but the "name=" part of the query string will still be present.
For checkboxes and radio buttons, the VALUE
attribute specifies
the value of a checkbox or radio button when it is checked. An unchecked
checkbox is disregarded completely when assembling the query string. Multiple
checkboxes can have the same NAME
(and different
VALUE
s), if desired. Multiple radio buttons intended to have "one
of many" behavior should have the same NAME
and different
VALUE
s.
GET
method (above), but rather than appending them to the URL specified by the
form's ACTION
attribute as a query, the contents are sent in a data
block as part of the POST
operation. The ACTION
attribute (if any) is the URL to which the data block is POST
ed.
METHOD="POST"
, use
ACTION="http://hoohoo.ncsa.uiuc.edu/htbin-post/post-query"
METHOD="GET"
, use
ACTION="http://hoohoo.ncsa.uiuc.edu/htbin/query"
query
and post-query
programs is
distributed with NCSA httpd, in the cgi-src
directory.
The fill-out form examples listed below use these query servers as their back ends, so you can see them in action and know what to expect with your own forms.
Important note: If you use the GET
method in your form,
you will notice that the example GET
server will choke if too much
data (more than a couple hundred bytes) is submitted at a time -- the server is
passing the data to the form-processing module via a shell command line, and the
maximum shell command line length is being exceeded. This problem does not
exist with the POST
method and server.
mailto
URLs aren't supported as actions yet, and also the Mosaic
2.0 support only includes a subset of the allowable types of input fields
(obviously "text" can also serve as "url", "int", "float", and "date" but
without intrinsic range/error checking).
INPUT
element of type TEXT
(in which case
Return in the text entry area submits the form) or at least one
INPUT
element of type IMAGE
(in which case a click
in the image submits the form).
NAME
of the text field is "isindex", then the submitted query
will be just like you are used to getting with ISINDEX
--
"url?querystring" (i.e., not "url?isindex=querystring"). This allows you to
use simple fill-out forms in your documents to point to existing query servers
(including Gopher and WAIS servers!). This of course assumes that the
POST
method is not specified for such forms.
Thirteen examples are available.
All of the examples now use METHOD=POST
.
We strongly, strongly recommend use of the POST
method with fill-out forms. One reason: with the GET
method, given
the way many servers (e.g. NCSA httpd) pass query strings from URLs to query
server scripts, you run an excellent chance of having the forms contents
truncated by hardcoded shell command argument lengths. With POST
(again, e.g., with NCSA httpd) you should be able to do a total end run around
such problems.
NCSA httpd 1.0 (the official release) should be out shortly and will contain
an example POST
fill-out form server.
Maintained by John Loomis, last updated 13 Feb 2001