Next / Previous / Contents / TCC Help System / NM Tech homepage

14. Forms: The form element

Your document can contain one or more forms that the user can fill out.

Each form is enclosed in a form block element with this content model:

element form
{ attribute action { xsd:anyURI },
  attribute method { 'get' | 'post' }?,
  attribute enctype { text }?,
  attribute onsubmit { text }?,
  attribute onreset { text }?,
  Common.attrib,
  ( fieldset | Block.class )+
}
action

Set the value of this attribute to point at a script that will be executed when the user clicks on the form's Submit button. For example, if this is a survey form, you might write a handler script named survey.cgi, and point it at with the attribute action='survey.cgi'.

method

This attribute selects how values are passed to the handler script. The value must be either 'get' or 'post'. For details, see Section 14.10, “Writing your form handler script”.

enctype

When you use “method='post'”, this attribute specifies which protocol you are using to transmit the form values. See Section 14.10, “Writing your form handler script”.

onsubmit, onreset

Actions to be taken when the form is submitted or reset. See Section 16, “Event attributes”.

Common.attrib

Form elements can carry all the usual attributes discussed in Section 15.3, “The common attributes: Common.attrib.

( fieldset | Block.class )+

Your form must be structured as a sequence of one or more block elements; see Section 9, “The block elements”.

You can also structure your form as a sequence of fieldset elements. See Section 14.8, “The fieldset element: Adding structure to a form.

The various controls that can appear on a form are described in succeeding sections:

14.1. The input forms control

An input element may represent one of several types of forms controls. Here is the content model:

element input
{ attribute name { text },
  attribute type
  { 'text' | 'password' | 'checkbox' | 'radio' | 'file' | 'submit'
    'image' | 'reset' | 'hidden'
  }?,
  attribute value { text }?,
  attribute checked { 'checked' }?,
  attribute size { xsd:nonNegativeInteger }?,
  attribute maxlength { xsd:nonNegativeInteger }?,
  attribute alt { text }?,
  attribute tabindex { xsd:nonNegativeInteger }?,
  attribute onchange { text }?,
  attribute onselect { text }?,
  attribute onfocus { text }?,
  attribute onblur { text }?,
  Common.attrib,
  empty
}
name

Use this attribute to give a control name to the element. The name must conform to the naming rules described in Section 6.2, “The ID datatype”.

type

Selects the type of control. See the sections for the various control types below.

value

This attribute specifies a value for the element. Refer to the table of control types below for its usage.

checked='checked'

For checkboxes, specify this attribute if you want the checkbox to be set (on) initially.

For radiobuttons, specify this attribute for the radiobutton that is on initially by default.

size

For text and password fields, this specifies the displayed size of the field as a number of characters. For example, size='10' would display a ten-character text field.

maxlength

For text and password fields, this specifies the capacity of the field. If the capacity exceeds the size, the field will scroll horizontally as the user enters more text than the displayed size.

alt

If the control is a graphic, use this attribute to supply alternate text for non-graphic users.

tabindex

See Section 15.7, “The tabindex attribute: Specifying tab traversal order”.

onchange, onselect, onfocus, onblur

See Section 16, “Event attributes”.

Common.attrib

You can attach to an input element any of the attributes described in Section 15.3, “The common attributes: Common.attrib.

empty

No content is allowed inside an input element.

Here are the sections describing the various input controls.

14.1.1. The text control

Creates a field where the user can enter one line of text from the keyboard. Use the size attribute to specify the size of the field, in characters; the default is 20. Use the maxlength attribute if you want to limit how much text the user can enter.

Here's an example of a text field and its associated label. See Section 14.2, “The label element: Label a control”.

  <input type="text" name="fave-color" id="fave-text"/>
  <label for="fave-text">What is your favorite color?</label>

14.1.2. The password control

A password field works the same as a text field, except that each character entered by the user is displayed as “*”, so that no one looking at the browser window can see what text has been entered. An example:

  <input type="password" name="pwd" id="pwd-field"/>
  <label for="pwd-field">Enter your secret name</label>

14.1.3. The checkbox control

Creates an unlabeled checkbox. If the control has a value attribute, that value is passed to the handler script as the value for this control's name. If no value is given, the value “on” will be sent to the handler.

If the control has checked='checked', the checkbox will be set (on) initially. Otherwise, it will initially be cleared (off).

Here is an example:

    <input type="checkbox" name="fish-license" id="eric"/>
    <label for="eric">Does your fish have a license?</label>

14.1.4. The radio control: radiobutton

Radiobuttons allow the user to select one of a set of mutually exclusive choices. All the radiobuttons in a set have the same name attribute, but each has a different value attribute. When the form is submitted, the value of the currently selected radiobutton will be sent to the handler script.

You should specify checked='checked' for one of the radiobuttons in a set; that radiobutton will be set initially.

Here's an example of a set of three radiobuttons.

The label above the radiobuttons is ordinary text. Note that each input element has the same control name (name attribute). Each radiobutton and its label are placed on a separate line by wrapping them inside a div element.

  Who should investigate the moaning noises?
  <div>
    <input type="radio" name="mystery" id="velma" value="Velma"
        checked="checked" />
    <label for="velma">Velma</label>
  </div>
  <div>
    <input type="radio" name="mystery" id="shag" value="Shaggy" />
    <label for="shag">Shaggy</label>
  </div>
  <div>
    <input type="radio" name="mystery" id="scoob" value="Scooby" />
    <label for="scoob">Scooby</label>
  </div>

14.1.5. The file control: Uploading user files

This control places two elements on a form: a text field, and a Browse button. The user can upload a file by clicking on the button and navigating to the file using his browser's customary file-browser facility.

Here is an example:

  <input type="file" name="user-file"/>

Note

When using this kind of control, be sure that the containing form element has an attribute “enctype="multipart/form-data"”.

14.1.6. The submit control

This control creates a Submit button on the form. Use the value attribute to specify the text that will appear on the button; the default text label is “Submit”.

For an example, see Section 14.1.8, “The reset control: Form clear button”.

14.1.7. The image control: A graphical submit button

An input element with a type='image' attribute creates a graphic Submit button. The src attribute points to the image file.

When the user clicks on this image, the form is submitted, and two name/value pairs are sent to the handler script. The first name/value pair contains the x coordinate where the user clicked on the image, relative to the top left corner; the name for this coordinate is the name from the name attribute with “.x” appended.

Similarly, the y coordinate where the user clicked is sent to the handler; the name is the control name with “.y” appended.

For example, suppose an element is defined like this:

  <input type='image' name='target' src='bullseye.png'/>

The graphic bullseye.png is displayed in the form.

If the user were to click on that graphic at a spot that is 39 pixels from the left side of the graphic, and 7 pixels from the top, the handler script would receive two name/value pairs: target.x=39 and target.y=7.

Note

Use of the type='image' control is not recommended, because blind users cannot use it. If you want to use graphic buttons but give the user choices, Use multiple Submit controls (either type='submit' or type='image'), and give each of them a different name. The handler script will be able to tell from the control name which Submit button was used. See also Section 14.3, “The button forms control”.

14.1.8. The reset control: Form clear button

Creates a Reset button on the form. Use the value attribute to specify the text that will appear on the button; the default text label is “Reset”.

The purpose of a Reset button is to restore the controls on the form to the values they have when the form is first displayed. In particular, a text control will have its value attribute filled in (if it has one); any radiobutton or checkbox with the checked='checked' attribute will be set, and others cleared; and so on.

Here is an example of a submit button and a reset button packed together on the same line by placing them inside a div element.

  <div>
    <input type="submit" value="Send"/>
    <input type="reset" value="Clear"/>
  </div>

14.1.9. The hidden control

You can pass data to the handler script without displaying it on the form by using an input element with type='hidden'. Use the value attribute to specify the data to be passed to the handler script.