Form Components

Form components display a record of data, usually for editing. Forms contain field and button components. Field components display individual fields of the data record and buttons perform programmable actions when pressed.

In contrast to HTML forms, RADpage forms can contain various RADpage field components with advanced functionality. Field components usually check and convert the field content and if necessary generate useful messages in case of input errors. RADpage forms are persistent (except for simpleform), that means form fields keep their values through several dialog steps, so errors are displayed correctly.

Forms need to be combined with programs to be useful. Each formbutton needs to be associated with a process routine that is executed when the button is pressed. Typically the action routine reads the data entered in the form and performs the desired action, by performing database statements, by changing form fields, by calling other components methods, etc. Also sessionRedirect can be called to navigate to another page.

A user program can at any time access the content of a form field. Form fields can be read or written. Usually form fields are persistent and change their values only if either the program changes a field or the user enters new data. Form fields are always stored in the internal format, field components automatically perform the necessary conversions.

A form can be disabled. This is useful to display the form data without allowing the user to enter data. Usually, however, enabling and disabling is controlled by a heitml program.

RADpage forms are (an important special case) of RADpage panels. All components that can contain field components are panels; there are display-panels to display data and panels to display data in an editable way. The latter class are the forms and the input/output panels.

Form Display

When a form is encountered on a page, it is displayed by sending an HTML form to the browser. If the form is displayed the first time, field components use their initial values. Afterwards the form fields keep their values unless changed by program or by user input or by a form reset.

Alternatively, a form can receive a value parameter that must denote a tuple containing all the form fields for display. The form will then use this tuple to store changed field values.

Form submission

After filling out the form, the user can press a submit button to request an action, e.g. a database query. This is called submitting the form, because it commonly submits the edited data record to the server to perform the action. The actual action is called form processing. If the edited data is invalid, for instance if the user forgot to enter some mandatory data, the form automatically redisplays the current values, and asks the user to correct the mistake.

There are two technical methods to submit a form; they are called get and post. The former is the default and should be used when it makes no difference whether the form is processed once or several times (such actions are said to be idempotent). A database search is a good example. If it does make a difference, as in a form to order things from an online shop, you should use post.

Form Processing and Error Handling

Form processing takes place when the browser submits the form to the server. Processing reads and checks all the data entered and stores it in internal data format. Afterwards, the action associated with the button is executed. Form processing takes place during the initialization phase of the page, i.e. before anything is displayed.

Error handling is crucial. If the user entered wrong data into a field, form processing notices this and redisplays the form with an appropriate error message. The action associated with the button is not executed in case of an error.

Note that this works differently compared to native HTML forms. An HTML form calls a script for form processing (CGI or whatever). The script can display error messages but not redisplay the form with embedded error messages (without explicitly programming a redisplay). From an HTML view, RADpage forms always have an action pointing back to the page containing the form. This is required to redisplay the form in case of an error. If the successuri attribute is given, however, after successful form processing a redirect is performed to display another page.

Form reset

While filling out the form, the user might want to start over, i.e. discarding his changes by resetting everything to its initial values. This is called resetting the form and is accomplished by pressing a reset button.

Accessing Form and Panel Fields

The following methods to access form fields work for any kind of panel, although they are most important for forms

• The panelfield(i) function returns the tuple of a current form. panelfield(0) contains the fields of the current panel, panelfield(1) the fields of the enclosing panel etc.
• The form object contains an attribute named ff, that contains the current values of all form fields. For example use page.dbform1.ff.test to access the field test of the form dbform1 on the current page.
• The formbutton's process routine gets a tuple of all form fields as parameter.

While the form is in error state, all fields with wrong data can not be accessed by the user program. The form object contains an attribute named ok that can be used to check the current status.

Application Security

It is a common security bug to put critical parts of an application in JavaScript or HTML. Note that it is easily possible for a hacker to manipulate the JavaScript programs or HTML pages and make them run differently. For example if you put a range check on an input field using JavaScript, it is easily possible to remove the check. This is why the RADpage field components perform checks twice, on the client and on the server.

Form Components

sesform is by far the most important form component. It has all the properties described above.

Component:sesformDetails
Session-mode form. This is the main form used in programs. Read more about the form programming .

Property	Kind	Description
Oid	Id
State	String(60)	Use to disable form fields.
Method	String(60)	HTTP method to submit the form data set. Value "post" should be used when form processing causes side effects, e.g. modifies a database, and if the form contains fieldfileupload.
Enctype	String(60)	Content type for method "post". Use "multipart/form-data" with fieldfileupload.
Successuri	String(60)	Continue with this URI after the form has been submitted successfully.
Fragment	String(10)	Section name (The # part of the action URI without the #). No effect on successuri.

The sleform component is a stripped down form, that can work without a session. Normally there is no reason to work without sessions except for very high traffic Web site.

A sleform keeps the fields content only as long as the user presses buttons of this form. If the user uses links or means to go to another page the form content is reset to initial values. Fields that are not displayed on the form but contained in the form tuple do not keep their values, unless hidden form fields are used.

Caution! You should be extremely careful with conditional components in session-less forms! Due to technical implementation details, the form should contain the same fields every time, or strange things may happen. If you need conditional components in a form, consider using a session form.

Component:sleformDetails
Session-less form.

Property	Kind	Description
Oid	Id	Id must be unique within the page.
State	String(60)	Use to disable form fields.
Method	String(60)	HTTP method to submit the form data set. Value "post" should be used when form processing causes side effects, e.g. modifies a database, and if the form contains fieldfileupload.
Enctype	String(60)	Content type for method "post". Use "multipart/form-data" with fieldfileupload.
Fragment	String(10)	Section name (The # part of the action URL without the #).

The simpleform is very special. All the other forms perform form processing themselves, while simpleform passes the edited data record to another URI, usually a CGI script.

Component:SimpleFormDetails
Simple form, very much like HTML form. HTML forms however can not contain field components. Select a SimpleForm if you want to program form processing in a classical way. Use a SesForm for object oriented form processing. Tutorial

Property	Kind	Description
State	String(60)	Check to disable form fields.
Method	String(60)	HTTP method to submit the form data set. Value "post" should be used when form processing causes side effects, e.g. modifies a database, and if the form contains fieldfileupload.
Enctype	String(60)	Content type for method "post". Use "multipart/form-data" with fieldfileupload.
Action	String(60)	URI of the form processing agent.
Fragment	String(10)	Section name (The # part of the action URI without the #).

Input/Output Panels

Consider a form to display an invoice. Let's say the database contains the relation "invoice" with a field "customerno" that is a unique key for the relation "customer". In plain words: an invoice record simply refers to a customer record instead of repeating the customer data (e.g. name and address) again and again in every invoice.

Remember that a form displays one record of data. But we've got two! Of course we could try to display each record in its own form. But that won't do, because each form would be submitted separately. What we need is a way to nest one `form' into another. However, the inner `form' is not really a form, because form properties like method and enctype are meaningless there.

For this reason, we prefer to introduce the concept of a panel as a component that can contain fields and other panels. Of course, any form is also an input/output panel. But a form is a panel that can be submitted. The outermost input/output panel must be a form, all inner panels must not.

Don't worry if you are a bit confused now; unless you need to nest panels, you can safely substitute form whenever we talk of panels.

Panels that require a session

Component:sespanelDetails
Session-mode panel. You must use this component inside a sesform. It can be used to process a group of fields as one unit.

Property	Kind	Description
Oid	Id
State	String(60)	Check to disable panel fields.

Panels that work without a session

Component:slepanelDetails
Session-less panel.

Property	Kind	Description
Oid	Id	Id must be unique within the page.
Fieldset	Checkbox	Create and HTML-Fieldset around the panel. This will visually group the enclosed fields.
State	String(60)	Check to disable panel fields.

Error Display

Each form or panel can display error messages in case the user entered wrong data. Normally the error messages are displayed at the end of the form. Using the panelerrors component the error display can be positioned anywhere else inside the form.

Component:panelerrorsDetails
Shows the error messages associated with the current panel. You can place this component once anywhere within a panel. If panelerrors is not used, the error messages are displayed using a default format at the end of the (enclosing) form. Panelerrors will also display the error messages of nested panels if these panels do not contain a panelerrors component.

Property	Kind	Description
Html	Checkbox	Display the error messages in HTML format. This should be switched off only if JavaScript is switched on and if all clients have enabled JavaScript.
Js	Checkbox	Display the error messages using JavaScript as an alert box. Note that this only works if the underlying browser supports JavaScript (and if the user did not disable JavaScript).
Color	String(60)	Color to display the error messages.
Size	String(60)	Font size to display the error messages.
Delim	String(60)	Delimiter to separate multiple error messages.

Buttons

There are two kinds of buttons, depending on property type. Reset buttons reset their panel, submit buttons submit the form.

Component:formbuttonDetails
Form button. The button must be used on a form. The value is used to render the button. Name must be a unique name for the button inside the form. Use the extend button to program an action that is performed when the button is pressed.

Property	Kind	Description
Name	String(10)	Button name, used internally to identify the button, must be unique within a form.
Value	String(10)	Button Label, appears as text on the button
Layout	String(60)	Input is a standard HTML submit button, image shows an image on the button, link creates a link (needs JavaScript), compatlink a link or button depending on the browser, button an HTML4.0 button (must occur just once at end of form), mbutton an HTML 4.0 button (needs JavaScript), and compatbutton an HTML 4.0 button or normal button depending on the browser;
Type	String(60)	Select the button's action: Value "reset" resets the fields to their initial values. Other values submit the form.
Src	String(20)	Image Url, only used for layout=image
Border	Integer	Border Size, only used for layout=image
State	String(60)	Is button disabled?