Field Components

Field Components display a piece of data inside a Database Form, Mailform, or any other kind of form component, usually for editing. They resemble HTML's form controls, but are much more comfortable to handle.

In general, a field converts its value into something suitable for display. This conversion ranges from trivial to sophisticated; for instance a fieldtext displays its string value unchanged, while a fieldtime can display its time value in a multitude of formats.

Upon form submission, the edited data has to be converted back into the internal representation. This conversion may fail if the user has entered invalid data (e.g. "30 o'clock" in a field that expects the time of day).

Field components share some common properties:

• Every field has a field name. For most fields this name must be unique within its panel. However, to provide radio buttons and some checkboxes, multiple fieldradio or fieldcheckbox components cooperate. These have to share a common name.
• A field's initial value is the value it displays when the form is first presented to the user, or after form reset.
• Fields may be disabled. A disabled field displays its value for viewing instead of editing. If you leave state on "Default" in the RADpage window, the state property of the field's panel is used instead. Selecting "display" always disables the field, selecting "enable" always enables the field.
• Fields that do not accept all possible user input have the descr and the errmsg property. Both properties must contain English text. descr describes acceptable input and errmsg is a diagnostic message. If the user entered invalid data errmsg is displayed. If errmsg in empty an error message is generated based on the descr.

Fields for typing in data

Component:fieldtextDetails
Display a text field on a form. The field optionally checks that input is present and remove superfluous spaces.

Property	Kind	Description
Name	String(10)	Field name.
Size	Integer	Field size in characters.
Maxlength	Integer	Limit to the length of the field's value.
Value	String(20)	Initial field value.
Mandatory	Checkbox	Check to require the user to fill out the field.
Trim	Checkbox	Check to trim leading and trailing white-space from value.
Empty	Checkbox	Check to allow input of empty strings. If not checked empty input means null.
Descr	String	A description of the field value.
Errmsg	String	An error message that is shown if the user enters a wrong value.
State	String(60)	Is field disabled ?
Password	Checkbox	Check to render input unreadable.

Component:fieldtextareaDetails
Text area field. Works like a text field but is displayed using multiple lines. The body of the component contains the default field content.

Property	Kind	Description
Name	String(10)	Field name.
Rows	Integer	Area height in characters.
Cols	Integer	Area width in characters.
Mandatory	Checkbox	Check to require the user to fill out the field.
Wrap	String(60)	Control automatic wrap. off Text is not automatically wrapped. Lines are sent to the Web server exactly as typed. virtual The display word wraps, but long lines are sent to the Web server as one line without any new-line markers. physical The display word wraps, and the text is transmitted as separate lines based on the wrap points.
Trim	Checkbox	Check to trim leading and trailing white-space from value.
Empty	Checkbox	Check to allow input of empty strings. If not checked empty input means null.
Descr	String	A description of the field value.
Errmsg	String	An error message that is shown if the user enters a wrong value.
Format	String(60)	Formatting in display mode
Env	String(60)	Text Block Formatting in display mode
Maxlength	Integer	Limit to the length of the field's value.
State	String(60)	Is field disabled?

Component:fieldintDetails
Integer field.

Property	Kind	Description
Name	String(10)	Field name.
Size	Integer	Field size in characters.
Value	Integer	Initial field value.
Format	String(60)	Display format.
Mandatory	Checkbox	Check to require the user to fill out the field.
Min	Integer	Minimal admissible value.
Max	Integer	Maximal admissible value.
Descr	String	A description of the field value.
Errmsg	String	An error message that is shown if the user enters a wrong value.
State	String(60)	Is field disabled?

Component:fieldrealDetails
Real number field.

Property	Kind	Description
Name	String(10)	Field name.
Size	Integer	Field size in characters.
Value	Real	Initial field value.
Format	String(60)	Display format.
Mandatory	Checkbox	Check to require the user to fill out the field.
Min	Integer	Minimal admissible value.
Max	Integer	Maximal admissible value.
Descr	String	A description of the field value.
Errmsg	String	An error message that is shown if the user enters a wrong value.
State	String(60)	Is field disabled ?

Component:fieldtimeDetails
Time field.

Property	Kind	Description
Name	String(10)	Field name.
Size	Integer	Field size in characters.
Value	String(20)	Initial field value.
Format	String(60)	Display format. The field value must match the display format or one of the optional input formats. For a list of format specifications see strftime. %c,%x,%p,%X and %Z are not supported yet.
Inputformats	String(60)	Optional input formats, separated by comma. The field value must match one of the input formats or the display format. For a list of format specifications see strftime. %c,%x,%p,%X and %Z are not supported yet.
Mandatory	Checkbox	Check to require the user to fill out the field.
Valtype	String(60)	Internal representation.
Descr	String(20)	A description of the field value.
Errmsg	String	An error message that is shown if the user enters a wrong value.
State	String(60)	Is field disabled?

Menus

A menu allows the user to choose from several options.

Component:fieldselectDetails
Selection menu.
It can only contain option, optionother, dboptions and fileoptions.

Property	Kind	Description
Name	String(10)	Field name.
Value	String(20)	Initial field value.
Multiple	Checkbox	Multiple selections allowed? If yes, values are separated by multisep.
Multisep	String(10)	Separator string for multi-value.
Displaysep	String(10)	Separator string for displayed multi-value.
Mandatory	Checkbox	Check to require the user to fill out the field.
Descr	String	A description of the field value.
Errmsg	String	An error message that is shown if the user enters a wrong value.
State	String(60)	Is field disabled?
Showoptions	Checkbox	Display options as components. Use this to edit options with the Component Editor, alternatively use content to edit the option tags.

Component:optionDetails
Selection menu option. The content is used as default option label and value.

Property	Kind	Description
Value	String(10)	Option value, defaults to contents.
Selected	Yes, No, Null	Is this option initially selected?
Nullvalue	Checkbox	If checked an empty value field returns null as field value otherwise the content of option.
State	String(60)	Use to disable the option.

Component:optionotherDetails
Selection menu option that prompts for its value.
This only works if the client has JavaScript enabled. Unless you are sure all your users have JavaScript enabled, please use an editable field like fieldtext together with a fieldchangebutton instead. This way users without JavaScript can still enter any value, albeit less comfortably.

The content of the component is show as label in the browsers select list.

Property	Kind	Description
State	String(60)	Use to disable the option.

Radio Buttons and Checkboxes

Radio buttons and checkboxes both display small, selectable controls. If the user presses a radio button, all other radio buttons with the same name are deselected. Thus the user can choose one of the given values.

All checkboxes with a common name belong together, too. Any number of them may be checked, i.e. they allow to choose a subset from a set of values.

Radio buttons and checkboxes work very much like menus with property multiple false and true, respectively. But of course they differ in visual appearance.

Component:fieldradioDetails
Radio button.
The set of radio buttons with a common name together edit a value.

Property	Kind	Description
Name	String(10)	Field name.
Value	String(20)	Value to use if box is checked.
Checked	Yes, No, Null	Is box initially checked?
State	String(60)	Is field disabled?

Component:fieldcheckboxDetails
A check box that selects one of two possible values. After submit the form field contains either the onvalue or the offvalue depending on the status of the checkbox.

If multiple is selected there can be several checkboxes with the same name on a form. In this case the form field contains a string of onvalues, seperated by the multisep character.

Property	Kind	Description
Name	String(10)	Field name.
Onvalue	String(10)	Field's value if checked.
Offvalue	String(10)	Field's value if not checked.
Checked	Yes, No, Null	Is box initially checked?
Multiple	Checkbox	Multiple checkboxes with the same name ?
Multisep	String(3)	Seperator character for values in the value string
State	String(60)	Is field disabled?

Switching between two values

Often you want to use a checkbox as a switch between two possible values. A single fieldcheckbox is not well suited for this task, because its two possible values are the empty set and the set containing the value of the checkbox, which is rather inconvenient. The following components address this issue.

Component:fieldcheckboxDetails
A check box that selects one of two possible values. After submit the form field contains either the onvalue or the offvalue depending on the status of the checkbox.

If multiple is selected there can be several checkboxes with the same name on a form. In this case the form field contains a string of onvalues, seperated by the multisep character.

Property	Kind	Description
Name	String(10)	Field name.
Onvalue	String(10)	Field's value if checked.
Offvalue	String(10)	Field's value if not checked.
Checked	Yes, No, Null	Is box initially checked?
Multiple	Checkbox	Multiple checkboxes with the same name ?
Multisep	String(3)	Seperator character for values in the value string
State	String(60)	Is field disabled?

Component:fieldboolDetails
Boolean field.

Property	Kind	Description
Name	String(10)	Field name.
Value	Checkbox	Check to set the initial value to `true'.
State	String(60)	Is field disabled?

Miscellaneous

Submitting files

Component:fieldfileuploadDetails
File select for upload.
The selected local file is submitted with the form.
Make sure the form has method "post" and enctype "multipart/form-data".

Property	Kind	Description
Name	String(10)	Field name.
Size	Integer	Field size in characters.
Value	String(30)	Initial field value.
Mandatory	Checkbox	Check to require the user to fill out the field.
Descr	String(20)	A description of the field value.
Ctname	String(10)	Field name to store the content type of the uploaded file.
Filename	String(10)	Field name to store the file name of the uploaded file.
Errmsg	String	An error message that is shown if the user enters a wrong value.
State	String(60)	Is field disabled?

Hidden fields

Component:fieldhiddenDetails
Hidden field.
The initial value is not displayed, but is submitted with the rest of the form. This may be handy when working with legacy CGI programs.

Property	Kind	Description
Name	String(10)	Field name.
Value	String(20)	Initial field value.

How to select a field component

There are quite a number of field components, and you might be unsure which is the right one to display a specific piece of data. Here are some simple rules:

• If there are only two possible values, e.g. "Yes" and "No", consider fieldcheckbox.
• If there are only a few possible data values, consider fieldselect and fieldradio.
• If there are only a few possible data values, but the user may choose more than one, consider fieldselect with property multiple checked, and fieldcheckbox.
• Consider the field that is appropriate for the value's type, for example fieldtext and fieldtextarea for a string, fieldint for an integer, fieldreal for a real number, fieldbool for a Boolean, fieldtime for a calendar time.