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

These fields display a single-line text input control, except for fieldtextarea, which displays a multi-line text input control, also known as text area. Fieldtext and fieldtextarea display strings. The remaining ones convert their value into a string for display according to their format property.

Component:fieldtextDetails
Display a text field on a form. The field optionally checks that input is present and remove superfluous spaces.
Property Kind Description
NameString(10) Field name. 
SizeInteger Field size in characters. 
MaxlengthInteger Limit to the length of the field's value. 
ValueString(20) Initial field value. 
MandatoryCheckbox Check to require the user to fill out the field. 
TrimCheckbox Check to trim leading and trailing white-space from value. 
EmptyCheckbox Check to allow input of empty strings. If not checked empty input means null. 
DescrString A description of the field value. 
ErrmsgString An error message that is shown if the user enters a wrong value. 
StateString(60) Is field disabled ?  
PasswordCheckbox 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
NameString(10) Field name. 
RowsInteger Area height in characters. 
ColsInteger Area width in characters. 
MandatoryCheckbox Check to require the user to fill out the field. 
WrapString(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.
 
TrimCheckbox Check to trim leading and trailing white-space from value. 
EmptyCheckbox Check to allow input of empty strings. If not checked empty input means null. 
DescrString A description of the field value. 
ErrmsgString An error message that is shown if the user enters a wrong value. 
FormatString(60) Formatting in display mode  
EnvString(60) Text Block Formatting in display mode  
MaxlengthInteger Limit to the length of the field's value. 
StateString(60) Is field disabled? 

Component:fieldintDetails
Integer field.
Property Kind Description
NameString(10) Field name. 
SizeInteger Field size in characters. 
ValueInteger Initial field value. 
FormatString(60) Display format.  
MandatoryCheckbox Check to require the user to fill out the field. 
MinInteger Minimal admissible value. 
MaxInteger Maximal admissible value. 
DescrString A description of the field value. 
ErrmsgString An error message that is shown if the user enters a wrong value. 
StateString(60) Is field disabled? 

Component:fieldrealDetails
Real number field.
Property Kind Description
NameString(10) Field name. 
SizeInteger Field size in characters. 
ValueReal Initial field value. 
FormatString(60) Display format.  
MandatoryCheckbox Check to require the user to fill out the field. 
MinInteger Minimal admissible value. 
MaxInteger Maximal admissible value. 
DescrString A description of the field value. 
ErrmsgString An error message that is shown if the user enters a wrong value. 
StateString(60) Is field disabled ?  

Component:fieldtimeDetails
Time field.
Property Kind Description
NameString(10) Field name. 
SizeInteger Field size in characters. 
ValueString(20) Initial field value. 
FormatString(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.  
InputformatsString(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.  
MandatoryCheckbox Check to require the user to fill out the field. 
ValtypeString(60) Internal representation. 
DescrString(20) A description of the field value. 
ErrmsgString An error message that is shown if the user enters a wrong value. 
StateString(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
NameString(10) Field name. 
ValueString(20) Initial field value. 
MultipleCheckbox Multiple selections allowed? If yes, values are separated by multisep. 
MultisepString(10) Separator string for multi-value. 
DisplaysepString(10) Separator string for displayed multi-value. 
MandatoryCheckbox Check to require the user to fill out the field. 
DescrString A description of the field value. 
ErrmsgString An error message that is shown if the user enters a wrong value. 
StateString(60) Is field disabled? 
ShowoptionsCheckbox 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
ValueString(10) Option value, defaults to contents. 
SelectedYes, No, Null Is this option initially selected? 
NullvalueCheckbox If checked an empty value field returns null as field value otherwise the content of option. 
StateString(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
StateString(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
NameString(10) Field name. 
ValueString(20) Value to use if box is checked. 
CheckedYes, No, Null Is box initially checked? 
StateString(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
NameString(10) Field name. 
OnvalueString(10) Field's value if checked. 
OffvalueString(10) Field's value if not checked. 
CheckedYes, No, Null Is box initially checked? 
MultipleCheckbox Multiple checkboxes with the same name ? 
MultisepString(3) Seperator character for values in the value string  
StateString(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
NameString(10) Field name. 
OnvalueString(10) Field's value if checked. 
OffvalueString(10) Field's value if not checked. 
CheckedYes, No, Null Is box initially checked? 
MultipleCheckbox Multiple checkboxes with the same name ? 
MultisepString(3) Seperator character for values in the value string  
StateString(60) Is field disabled? 

Component:fieldboolDetails
Boolean field.
Property Kind Description
NameString(10) Field name. 
ValueCheckbox Check to set the initial value to `true'. 
StateString(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
NameString(10) Field name. 
SizeInteger Field size in characters. 
ValueString(30) Initial field value. 
MandatoryCheckbox Check to require the user to fill out the field. 
DescrString(20) A description of the field value. 
CtnameString(10) Field name to store the content type of the uploaded file. 
FilenameString(10) Field name to store the file name of the uploaded file. 
ErrmsgString An error message that is shown if the user enters a wrong value. 
StateString(60) Is field disabled? 

Hidden fields

A `hidden' field does not display anything, but submits its value unchanged. This is occasionally useful, especially if you work without a session.

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
NameString(10) Field name. 
ValueString(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:


This page was dynamically generated by the web application development tool RADpage of H.E.I.
© 1996-2017 H.E.I. All Rights Reserved.



Homepage
Intro/Features
Component Guide
  Application
  Generic
    Adaptive
    Repeaters
    Panels
    Fields
    Persistence
    Messages
    Caching
  Programmable
Programming
User Guide
FAQ
Mailinglist
Discussion Group
Services
Pricing/Register
Download
Frame
 
Contact
 
 
 
Search: