by Stefan Aufischer
last updated: 28.04.98
- 1 Introduction
- 1.1 Installation Hints
- 2 HTML-Form-Specification
- 2.1 Form: FORM
- 2.2 Input Field: INPUT
- 2.2.1 Text Field: INPUT TYPE=TEXT
- 2.2.2 Password Field: INPUT TYPE=PASSWORD
- 2.2.3 Check Box: INPUT TYPE=CHECKBOX
- 2.2.4 Radio Button: INPUT TYPE=RADIO
- 2.2.5 Image Pixel: INPUT TYPE=IMAGE
- 2.2.6 Hidden Field: INPUT TYPE=HIDDEN
- 2.2.7 Submit Button: INPUT TYPE=SUBMIT
- 2.2.8 Reset Button: INPUT TYPE=RESET
- 2.3 Selection: SELECT
- 2.3.1 Option: OPTION
- 2.4 Text Area: TEXTAREA
- 3 Form Submission
- 3.1 The form-urlencoded Media Type
- 3.2 Query Forms: METHOD=GET
- 3.3 Forms with Side-Effects: METHOD=POST
- 4 Oberon-Form-Elements
- 4.1 Types of FormElems
- 4.2 Inserting FormElems
- 4.3 Attributes of FormElems
- 4.4 Description of all FormElems
- 4.4.1 FormElems.FormElem
- 4.4.2 FormElems.TextField
- 4.4.3 FormElems.PassWord
- 4.4.4 FormElems.CheckBox
- 4.4.5 FormElems.RadioButton
- 4.4.6 FormElems.ImageElem
- 4.4.7 FormElems.HiddenElem
- 4.4.8 FormElems.SubmitButton
- 4.4.9 FormElems.ResetButton
- 4.4.10 FormElems.List
- 4.4.11 FormElems.TextArea
- 5 Examples
- 5.1 Text Field & Submit Button
- 5.2 Text Area
- 5.3 Check Boxes & Reset Button
- 5.4 Radio Buttons
- 5.5 Selections
- 5.6 Password & Hidden Fields
- 5.7 Image Pixels
Constructing a form is far less intimidating than it may appear at first. If you've already set up web pages using HTML, then you'll move naturally into setting up forms, which are also written using HTML tags embedded right in an ordinary HTML page.
If you are used to the Oberon textsystem and the mechanisms of the Oberon Webbrowser, it's even possible, to construct forms without writing any HTML code.
Note:
As with all other HTML, the appearance of a form can be dramatically altered by the browser used to view it. A great way to learn forms, as with other HTML, is to examine the work of others: feel free to look at the source of this documentation, or that of any other forms you are impressed by. Therefore use the "HTML.Source on"-command in the Browser menu of the Oberon Webbrowser. (It's recommendable to have a look at the examples in chapter 5.)
You can always jump to the List Of Contents by clicking on any header of this HTML page.
Examples: In case of submission each of the example forms in this documentation will be sent to the URL "http://www.chpc.utah.edu/bin/cgi-forms/env.sh". A page with your submission content and other interesting facts will be the result.
Use Forms.Tool to compile and install the FormElems onto your system and webbrowser.
See also: FormElems.FormElem.
The beginning and ending form tags enclose a sequence of input, textarea and select elements, along with document structuring elements. The attributes are:
- ACTION
- specifies the action URL for the form. The action URL of a form defaults to the base URL of the document. It is treated like a hyperlink.
- METHOD
- selects a method of accessing the action URL. The set of applicable methods is a function of the scheme of the action URL of the form. See section Query Forms: METHOD=GET and section Forms with Side-Effects: METHOD=POST.
- ENCTYPE
- specifies the media type used to encode the name/value pairs for transport, in case the protocol does not itself impose a format. See section The form-urlencoded Media Type.
The INPUT element represents a field for user input. The TYPE attribute discriminates between several variations of fields.
The INPUT element has a number of attributes. The set of applicable attributes depends on the value of the TYPE attribute.
See also: FormElems.TextField, Example
The default value of the TYPE attribute is `TEXT', indicating a single line text entry field. (Use the TEXTAREA element for multi-line text fields.)
Required attributes are:
- NAME
- name for the form field corresponding to this element.
The optional attributes are:
- MAXLENGTH
- constrains the number of characters that can be entered into a text input field. If the value of MAXLENGTH is greater the the value of the SIZE attribute, the field should scroll appropriately. (Note: The TextFieldElems.Elem from which the FormElems.TextFieldElem is derived doesn't support scrolling. Nevertheless you can type more than you can see.) The default number of characters is unlimited.
- SIZE
- specifies the amount of display space allocated to this input field according to its type. The default depends on the user agent.
- VALUE
- The initial value of the field.
See also: FormElems.PassWord, Example
An INPUT element with `TYPE=PASSWORD' is a text field as above, except that the value is asterisked as it is entered.
See also: FormElems.CheckBox, Example
An INPUT element with `TYPE=CHECKBOX' represents a boolean choice. A set of such elements with the same name represents an n-of-many choice field. Required attributes are:
- NAME
- symbolic name for the form field corresponding to this element or group of elements.
- VALUE
- The portion of the value of the field contributed by this element.
Optional attributes are:
- CHECKED
- indicates that the initial state is on.
See also: FormElems.RadioButton, Example
An INPUT element with `TYPE=RADIO' represents a boolean choice. A set of such elements with the same name represents a 1-of-many choice field. The NAME and VALUE attributes are required as for check boxes. Optional attributes are:
- CHECKED
- indicates that the initial state is on.
At all times, exactly one of the radio buttons in a set is checked. If none of the INPUT elements of a set of radio buttons specifies `CHECKED', then the user agent should check the first radio button of the set initially.
See also: FormElems.ImageElem, Example
An INPUT element with `TYPE=IMAGE' specifies an image resource to display, and allows input of two form fields: the x and y coordinate of a pixel chosen from the image. The names of the fields are the name of the field with `.x' and `.y' appended. `TYPE=IMAGE' implies `TYPE=SUBMIT' processing; that is, when a pixel is chosen, the form as a whole is submitted.
The NAME attribute is required as for other input fields. The SRC attribute is required and the ALIGN is optional as for the IMG element.
Note: The Oberon Webbrowser doesn't support alignment of images. See also: Documentation of the Oberon Webbrowser.
See also: FormElems.HiddenElem, Example
An INPUT element with `TYPE=HIDDEN' represents a hidden field. The user does not interact with this field; instead, the VALUE attribute specifies the value of the field. Required attributes are:
- NAME
- indicates that this element contributes a form field whose value is given by the VALUE attribute. If the NAME attribute is not present, this element does not contribute a form field.
- VALUE
- indicates a value to be submitted.
- See also: FormElems.SubmitButton, Example
- An INPUT element with
`TYPE=SUBMIT' represents an input option, typically a button, that instructs the browser to submit the form. Optional attributes are:
- NAME
- indicates that this element contributes a form field whose value is given by the VALUE attribute. If the NAME attribute is not present, this element does not contribute a form field.
- VALUE
- indicates a label for the input (button).
See also: FormElems.ResetButton, Example
An INPUT element with `TYPE=RESET' represents an input option, typically a button, that instructs the browser to reset the forms fields to their initial states. The VALUE attribute, if present, indicates a label for the input (button).
See also: FormElems.List, Example
The SELECT element constrains the form field to an enumerated list of values. The values are given in OPTION elements. Attributes are:
- MULTIPLE
- indicates that more than one option may be included in the value.
- NAME
- specifies the name of the form field.
- SIZE
- specifies the number of visible items. Select fields of size one are typically pop-down menus, whereas select fields with size greater than one are typically lists.
The Option element can only occur within a Select element. It represents one choice, and has the following attributes:
- SELECTED
- Indicates that this option is initially selected.
- VALUE
- indicates the value to be returned if this option is chosen. The field value defaults to the content of the OPTION element.
The content of the OPTION element is presented to the user to represent the option. It is used as a returned value if the VALUE attribute is not present.
Whether or not an option list is displayed as a drop-down listbox, a simple listbox, or a scrolling listbox is determined by the SIZE keyword in the SELECT tag. SIZE refers to the number of rows visible to the user at once. If the SIZE is one (the default), a drop-down listbox will appear. If the SIZE is greater than one, and the number of options is less than or equal to the SIZE, a simple list box is displayed. If the SIZE is greater than one, but the number of options available to the user is greater than the SIZE, a scroll bar will appear to the right of the listbox to allow the user to scroll through the options (scrolling listbox)
See also: FormElems.TextArea, Example
The TEXTAREA element represents a multi-line text field. Attributes are:
- COLS
- the number of visible columns to display for the text area, in characters.
- NAME
- Specifies the name of the form field.
- ROWS
- The number of visible rows to display for the text area, in characters.
The content of the TEXTAREA element is the field's initial value.
TEXTAREA signals the browser to produce a potentially multi-line field, and the ROWS and COLS attributes tell it how many lines long and how wide the field should be.
These tags limit the length of a line someone can enter (because there's no horizontal scrollbar in Oberon), but not how many lines of text can be entered.
The text between beginning and ending form tag will be taken as initial value.
An HTML user agent begins processing a form by presenting the document with the fields in their initial state. The user is allowed to modify the fields, constrained by the field type etc. When the user indicates that the form should be submitted (using a submit button, an image input, a text field, or a password field), the form data set is processed according to its method, action URL and enctype.
The default encoding for all forms is `application/x-www-form-urlencoded'. A form data set is represented in this media type as follows:
- The form field names and values are escaped: space characters are replaced by
`+', and then reserved characters are escaped as per [URL]; that is, non-alphanumeric characters are replaced by `%HH', a percent sign and two hexadecimal digits representing the ASCII code of the character. Line breaks, as in multi-line text field values, are represented as CR LF pairs, i.e. `%0D%0A'.
- The fields are listed in the order they appear in the document with the name separated from the value by
`=' and the pairs separated from each other by `&'. Fields with null values may be omitted. In particular, unselected radio buttons and checkboxes should not appear in the encoded data, but hidden fields with VALUE attributes present should.
If the processing of a form is idempotent (i.e. it has no lasting observable effect on the state of the world), then the form method should be `GET'. Many database searches have no visible side-effects and make ideal applications of query forms.
To process a form whose action URL is an HTTP URL and whose method is `GET', the user agent starts with the action URL and appends a `?' and the form data set, in `application/x-www-form-urlencoded' format as above. The user agent then traverses the link to this URL just as if it were an anchor.
If the service associated with the processing of a form has side effects (for example, modification of a database or subscription to a service), the method should be `POST'.
To process a form whose action URL is an HTTP URL and whose method is `POST', the user agent conducts an HTTP POST transaction using the action URL, and a message body of type `application/x-www-form-urlencoded' format as above. The user agent should display the response from the HTTP POST interaction just as it would display the response from an HTTP GET above.
(Part of the Oberon Webbrowser - Edit.Open Web.Tool )
All FormElems are derived from Texts.Elem and so can be placed, stored and loaded in any Oberon text. The FormElems are named after the HTML form tags and can be used the same way. For further instructions have a look at the documentation of the Oberon Webbrowser.
You can see all types of FormElems in the FormInsert.Panel ( Panel.Open FormInsert.Panel ) or in the Forms menu.
Each Elem can be inserted by setting the caret at the wanted position and then calling its insert command (e.g. FormElems.InsertSubmitButton). You can find all available insert commands in the Forms menu of the Webbrowser.
An easier way to insert FormElems into an Oberon text is to use the FormInsert.Panel. You can open it by choosing Panel.Open FormInsert.Panel in the Form menu. Now click with the middle mouse button on the listboxes FormElem that is intended to be inserted at the caret position.
Exception: To insert the form-beginning- and ending-tags make a selection. The inserted form-tags will enclose the selected text. (Forms should not overlap eachother!)
After inserting a FormElem it has default attributes. To change these attributes use the FormInspector.Panel.( Panel.Open FormInsert.Panel or FormInspect button of the FormInsert.Panel)
To inspect the attributes of a FormElem you must mark the element with the right mouse button. After that you can open the FormInspector.Panel ( Panel.Open FormInspector.Panel ) which will display all changeable attributes of the selected FormElem.
If you want to inspect another FormElem, you just have to mark it and press the Inspect button of the FormInspector.Panel.
To confirm your changes press the Apply button. (Attention: changes are made to the present marked element)
Exception: The elements FormElem, ImageElem, and HiddenElem are derived from WebElems and so can't be inspected by the FormInspector. Use the oberonspecific mechanism (interclick middle-right) to change their attributes.
Elements have a default value which is set when any reset button of the enclosing form is pressed. If not changed by the user, the default value equals the initial value of the element.
Example
Insert: FormElems.InsertFormElem
Generator: FormElems.NewForm(...)
Function: Represents the beginning or ending form tag.
Editing: Interclick middle-right on the icon
Information: Interclick middle-right on the icon (hold buttons longer than 250 ms)
Attributes:
- ACTION (URL)
- METHOD
- ENCTYPE (default = 'appliction/x-www-form-urlencoded')
User interaction: None
Example
Insert: FormElems.InsertTextField
Generator: FormElems.NewTextField(...)
Function: Single line text entry field. See also: Text Field.
Editing & Information: Mark and call Inspect from the Inpector.Panel
Attributes:
- Name - stored as NAME
- (Value (text in the field) - stored as VALUE)
- Size - stored as SIZE
- MaxLen - stored as MAXLENGTH
- DefaultValue
User interaction: After activating the elem and simultaneously setting the caret with the left mouse button, the user can enter any kind of characters. Attention: You should not insert any text elements. (Note: The TextFieldElems.Elem from which the FormElems.TextFieldElem is derived doesn't support scrolling when you type more characters than can be seen.)
Example
Insert: FormElems.InsertPassWord
Generator: FormElems.NewPassWord(...)
Function: Single line text entry field for obscured text. See also: Password Field.
Editing & Information: Mark and call Inspect from the Inpector.Panel. Attention: The Inspector shows the unencoded DefaultValue
Attributes:
- Name - stored as NAME
- (Value (text in the field) - stored as VALUE)
- Size - stored as SIZE
- MaxLen - stored as MAXLENGTH
- DefaultValue
User interaction: Same as in case of TextFields
Example
Insert: FormElems.InsertCheckBox
Generator: FormElems.NewCheckBox(...)
Function: n-of-many boolean choice. See also: Check Box.
Editing & Information: Mark and call Inspect from the Inpector.Panel
Attributes:
- Name - stored as NAME
- ValueStr - stored as VALUE
- DefaultValue
User interaction: Select or deselect a checkbox by clicking it with the middle mouse button
Example
Insert: FormElems.InsertRadioButton
Generator: FormElems.NewRadioButton(...)
Function: 1-of-many boolean choice. See also: Radio Button.
Editing & Information: Mark and call Inspect from the Inpector.Panel
Attributes:
- Name (r.buttons with the same name belong to the same group) - stored as NAME
- MyValue ) - stored as VALUE
- DefaultValue (names the one of the radio button group that is initially marked)
User interaction: Select a radio button by clicking it with the middle mouse button, all other radio buttons of the same group ( = with the same name) will get deselected.
Example
Insert: FormElems.InsertImage
Generator: FormElems.NewImage
Function: Submit form with x- and y-coordinates. See also: Image Pixel.
Editing: Interclick middle-right on the image
Information: Interclick middle-right on the icon (hold buttons longer than 250 ms)
Attributes:
- SOURCE URL
- NAME
User interaction: If the image is clicked with the middle mouse button, the form that contains the image, and additionally the coordinates of the mouse click, will be submitted. The interclick middle-left will also cause submission, but the result will be opened in a new viewer (See also: Submit Button, Form Submission).
Example
Insert: FormElems.InsertHidden
Generator: FormElems.NewHidden
Function: Invariable information for the CGI programm on the server. See also: Hidden Field.
Editing: Interclick middle-right on the icon
Information: Interclick middle-right on the icon (hold buttons longer than 250 ms)
Attributes:
- NAME
- VALUE
User interaction: None
Attention: This field will only become visible if you execute HTML.Elems on (of the Browser menu).
Example
Insert: FormElems.InsertSubmitButton
Generator: FormElems.NewSubmitButton(...)
Function: Submit form. See also: Submit Button, Form Submission.
Editing & Information: Mark and call Inspect from the Inpector.Panel
Attributes:
- Name (if given, the button will be submitted) - stored as NAME
- Value (inscription of the button and the value to be submitted ) - stored as VALUE
User interaction: Clicking with the middle mousebutton will submit the form that contains the clicked submit button. The interclick middle-left will also cause submission, but the result will be opened in a new viewer (See also: Submit Button, Form Submission).
Example
Insert: FormElems.InsertResetButton
Generator: FormElems.NewResetButton(...)
Function: Reset form - All enclosed FormElems are reset. See also: Reset Button.
Editing & Information: Mark and call Inspect from the Inpector.Panel
Attributes:
- Value (inscription of the button) - stored as VALUE
User interaction: Clicking with the middle mousebutton will reset the form that contains the clicked reset button.
Example
Insert: FormElems.InsertList
Generator: FormElems.NewList(...)
Function: List of text where single/multiple lines can be selected. See also: Selection.
Editing & Information: Mark and call Inspect from the Inpector.Panel
Attributes:
- Name - stored as NAME
- Size (vertical size) - stored as SIZE
- Multi (if checked, then multiple choices are possible) - stored as MULTIPLE
- ValueT (displayed text) - stored as OPTION tags & text between SELECT tags
- Keywords (text to be sent at submission - lines correspond to ValueT) - stored as VALUE
- DefaultValueT / DefaultValue (Text or string depending on Multi checkbox)
User interaction: Clicking with the left mouse button will activate the listbox. Clicking with the right mouse button on a line of an activated listbox will select this line. Selecting a line is also possible with the left mouse button - in this case and in case of a non-multi listbox all other lines will get deselected. A popup list (size = 1) selection is made by pressing the popup button with the middle mouse button and release it over the wanted line of the popup menu.
Attention: An empty line in the keyword text can cause submission contents with empty values!
Example
Insert: FormElems.InsertTextArea
Generator: FormElems.NewTextArea(...)
Function: potentially multi-line text field. See also: Text Area.
Editing & Information: Mark and call Inspect from the Inpector.Panel
Attributes:
- Name - stored as NAME
- Rows (vertical size) - stored as ROWS
- Cols (horizontal size) - stored as COLS
- DefaultValue
User interaction: Clicking with the left mouse button will activate the textarea and set the caret in it. After that you can handle the text like an Oberon text.
Attention: You should not insert any text elements.
Note: In case of submission each of the example forms in this documentation will be sent to the imaginary URL "http://www.chpc.utah.edu/bin/cgi-forms/env.sh". This will bring no results!
Here's the source HTML for the above form:
< FORM METHOD=POST ACTION="http://www.chpc.utah.edu/bin/cgi-forms/env.sh" >
Enter your name: < INPUT NAME=name >
< INPUT TYPE=submit VALUE="Test this form" >
< /FORM >
Note: If you can't see the red beginning and ending form tags, execute: WebElems.Elems on (in the Browser menu). As you can see, the input element is a text field, if you don't specify the type. Another possibilty to construct a textfield is:
Enter your name: <INPUT TYPE=text NAME=your_name>
Some other things we can do with a text input field are define an initial value for the field, and make it longer (or shorter):
Enter your name: <INPUT TYPE=text NAME=your_name SIZE=25 VALUE="Mr. X" >
results in
Note that the user could still type more than 20 characters in the above field, the browser just doesn't show the additional text. You can also limit the length of the text input by the user by including a "MAXLENGTH=..."in the INPUT field definition.
Enter your name: <INPUT TYPE=text NAME=your_name SIZE=25 VALUE="Joe Schmoe" MAXLENGTH=50>
Each form should have at least one field of type submit. In the above form this was the tag:
<INPUT TYPE=submit VALUE="Test this form">
This creates the button the user clicks when he has finished filling out a form, and should come after all the other input fields (for the sake of usability). If you omit the VALUE keyword, the button will be labeled "Submit".
When the user clicks the submit button, the browser collects the values of each of the input fields (text typed by the user, etc.) and sends them to the web server as described in chapter Form Submission
Use the TextArea element to create fields for entering large amounts of text.
<br>Enter your name and address:
<br><TEXTAREA NAME="address" ROWS=5 COLS=50></TEXTAREA>
<br>If available, enter your E-mail address:
<br><TEXTAREA NAME="email" ROWS=1 COLS=20>abc@xyz</TEXTAREA>
<br><INPUT TYPE=submit VALUE="Register">
<BR><INPUT TYPE=checkbox NAME="baseball" VALUE="Y" CHECKED>Baseball
<BR><INPUT TYPE=checkbox NAME="basketball" VALUE="Y">Basketball <BR><INPUT TYPE=checkbox NAME="football" VALUE="Y" CHECKED>Football
<BR><INPUT TYPE=checkbox NAME="hockey" VALUE="Y">Hockey
<BR><INPUT TYPE=checkbox NAME="soccer" VALUE="Y">Soccer
<BR><INPUT TYPE=submit VALUE="Test this form">
<INPUT TYPE=reset VALUE="Clear Choices">
<BR><INPUT TYPE="radio" NAME="sport" VALUE="soccer" CHECKED>Soccer
<BR><INPUT TYPE="radio" NAME="sport" VALUE="baseball">Baseball
<BR><INPUT TYPE="radio" NAME="sport" VALUE="basketball">Basketball
<BR><INPUT TYPE="radio" NAME="sport" VALUE="football">Football
<BR><INPUT TYPE="radio" NAME="sport" VALUE="hockey">Hockey
<SELECT NAME=platforms>
<OPTION>Windows
<OPTION>Macintosh
<OPTION>UNIX
</SELECT>
<SELECT NAME=platforms SIZE=3>
<OPTION>Windows
<OPTION>Macintosh
<OPTION>UNIX
</SELECT>
<SELECT NAME=platforms SIZE=3>
<OPTION>Windows
<OPTION>Macintosh
<OPTION SELECTED>UNIX
<OPTION>Amiga
<OPTION>Next
<OPTION>AppleII
</SELECT>
In our previous option list examples, the value returned to the ACTION program when the form was submitted was the same as the description of the option displayed to the user in the listbox. Here we'll see an example of how you can use small tokens to represent the options (to save space in a spreadsheet for which the data is destined, for example), while still displaying meaningful descriptions to the user. We'll also take a look at a multiple selection list.
Notice that when you submit this form, you get not the option description, but an abbreviated keyword for it: (Recommendation: Inspect the attribute "Keywords" of this list box)
What would you like to do today?
<SELECT NAME=today SIZE=5>
<OPTION VALUE=drink>Drink Expresso
<OPTION VALUE=read SELECTED>Read A Book
<OPTION VALUE=walk>Take A Stroll
<OPTION VALUE=talk>Talk With Friends
<OPTION VALUE=eat>Eat A Bagel
<OPTION VALUE=veg>Watch TV
<OPTION VALUE="Pig Out">Munch Teddy Grahams
</SELECT>
<INPUT TYPE=submit VALUE="Submit Decision">
<INPUT TYPE=reset VALUE="Reset to Default Selections">
Here's an example of an option list which uses the MULTI keyword to allow the user to select several of the options :
<SELECT NAME=what-to-wear MULTI SIZE=8>
The MULTIPLE keyword (which can be abbreviated to MULTI) is what permits the user to make more than one selection form the above option list.
Enter A Test Password: <INPUT NAME=password TYPE=password SIZE=8>
<INPUT NAME=invisible TYPE=hidden VALUE="Hidden Value">
Select your preferred day of the week:<BR>
<INPUT TYPE = IMAGE SRC = "week.gif" NAME = week>