Class: cWebForm

Properties  Events  Methods    Index of Classes

The Web Framework form control for single line data entry

Hierarchy

cObject
---cWebObject
------cWebBaseUIObject
---------cWebBaseDEOServer
------------cWebBaseControl
---------------cWebBaseDEO
------------------cWebBaseForm
---------------------cWebForm
------------------------cWebBaseSelectionForm
------------------------cWebColorForm
------------------------cWebColumn
------------------------cWebDateForm
------------------------cWebSuggestionForm

Library: Web Application Class Library

Package: cWebForm.pkg

Description

Use the cWebForm class to display or edit a single line of text in your web application. A form is ideal for editing text fields in a web view or dialog (cWebView or cWebModalDialog). For example a view asking for the user's name, phone number, etc would use cWebForm controls for text input.



A form can be used with or without a data binding. When used with a data binding the form provides automatic support to display and allow editing of data from a database table.column. When used without a data binding you will use the class interface to read or write the control value.

Sample

Object oCustomerView is a cWebView
    Object oCustomer_DD is a Customer_DataDictionary
    End_Object

    Set Main_DD to oCustomer_DD
    Set Server to oCustomer_DD
    
    Object oCustomer_Name is a cWebForm
        Entry_Item Customer.Name
        Set piColumnSpan to 0
        Set psLabel to "Customer Name:"
    End_Object
End_Object

The above sample demonstrates a cWebView with a data dictionary object and a cWebForm object with a data binding to the Customer table, Name column.

Object oUserID is a cWebForm
    Set psLabel to "User ID:"
    Set peDataType to typeNumber
    Set piColumnSpan to 3
    Set piPrecision to 0
    Set piMaxLength to 6
    Set pbServerOnBlur to True

    Procedure OnBlur
        String sValue
        Forward Send OnBlur
        WebGet psValue to sValue
        Send ShowInfoBox sValue "The value is.."
    End_Procedure
End_Object

The above sample demonstrates the use of a cWebForm object with no data binding. This form only allows numeric entry of up to 6-digits and no decimal places. When the control loses focus, the OnBlur event is sent to the server which triggers an info box on the client that shows the control value. Note that pbServerOnBlur is set to true to ensure that the OnBlur event is sent to the server for this object.

Object Name

The Web Framework uniquely identifies each web object via a combination of the object hierarchy (object nesting), and object name. This means that web object names must be unique within their parent (i.e. each sibling web object must have a unique name).

Object Placement

Form controls must be placed within a web container (e.g. cWebPanel, cWebView or cWebModalDialog).
Form controls may not be nested inside other web controls. You may not mix web panels and web controls as sibling objects.

Data Binding

Form objects support a data binding to display values from a database Table.Column. When the control has a data binding then it will display the column value of the current record in the binding table. Changes entered into the control will update the table.column value in the correct way according to data dictionary data binding rules.

Use the Entry_Item command to set a data binding.

Sample

Entry_Item Customer.Name


Entry_Item expressions, e.g. (Inventory.Price + 100) are not supported in web object data bindings. Use OnSetCalculatedValue to define a data binding expression.

The data binding table.column must map to a data dictionary object in the server data dictionary object structure. Refer to the Data Dictionary Guide for more information.

A data binding provides data-aware behaviors that include:

 Finding, clearing, saving, and deleting records
 Prompt-object support
 Change verification (save, delete, and data-loss verifications)

A data binding also automatically provides the control's data type, input mask, tooltip, control focus rules, control blur rules, display formats (capslock, noput, displayonly, etc.) and much more. These settings may also be controlled manually by setting properties.

Accessing the Control Value

The Form control can be used without a data binding by accessing the control's value.

The psValue property allows you to get or set the current 'value' of the Form control.

An event is triggered whenever the control value changes. This event can be handled on the server by writing DataFlex code. It can also be handled on the client (browser) by writing JavaScript code. Writing a server-side DataFlex handler is the simplest way to handle change events.

Set pbServerOnChange to true to instruct the client to send the OnChange event to the server object whenever the control value is changed. Write an OnChange event handler in your Form object to perform some action when the control value changes.

To write a client-side change event handler using JavaScript, set the psClientOnChange property to the name of the JavaScript function that will execute when the control value changes.

If the control has a data dictionary server but does not have a data binding then a special event (OnSetCalculatedValue) is triggered for the form whenever a find or clear operation is performed on the data dictionary object. Write an OnSetCalculatedValue event handler in your Form object to generate a 'calculated' value for the control for each record in the server data dictionary object's table.

Data Type

If the form has a data binding (see above) then the data type, maximum number of characters and numeric precision are automatically set according to the data dictionary rules.

Set peDataType to manually select the form's data type (ASCII, Numeric, Date etc).

Set piMaxLength and piPrecision to manually set the maximum number of enterable characters and the maximum numeric precision respectively.

Data Format and Masks

The form control supports data masking and the ability to set the alignment of the form's text.

If the form has a data binding (see above) then data masking and horizontal alignment are automatically set according to the data dictionary rules.
Set psMask to manually assign a mask to the text displayed by the form.

Set peAlign to align the text to the left, right or center (alignLeft, alignRight, alignCenter).

Prompt Support

Form controls support OnPrompt events and embedded prompt buttons. Prompt support is ideal for activating a modal dialog from within the context of a form control. For example, a customer name form's prompt button could activate a customer lookup list to select a customer.

If the form has a data binding then the data dictionary object's Field_WebPrompt_Object setting for the binding table.column will provide automatic prompt button support. The OnPrompt event will automatically activate the referenced prompt object. Refer to the Data Dictionary Guide for more information.
If the form does not have a data binding or there is no data dictionary provided prompt object, then you can provide prompt support using the following interface.

Set phoPrompt to the object handle of a web dialog or view (cWebModalDialog, cWebView) to be activated by the OnPrompt event. The control's embedded prompt button will be automatically shown. This is the easiest way to provide prompt support outside of data dictionary prompt support.

Use the following interface if you need full programmatic prompt support without setting phoPrompt.

Set pbPromptButton to true to manually display an embedded prompt button within the control. Clicking the prompt button or pressing F4 within the form triggers the OnPrompt event on the server. Write an OnPrompt event handler in your form object to perform some action when the prompt button is clicked.

The server-side OnPrompt event can be disabled by setting pbServerOnPrompt to false. By default pbServerOnPrompt is true.
To write a client-side on prompt handler using JavaScript, set the psClientOnPrompt property to the name of the JavaScript function that will execute when the prompt button is clicked or if the user presses F4.

Password Support

Form controls support password entry by obscuring the typed characters. Set pbPassword to true to enable password entry.

Size and Location

Web controls are positioned by HTML flow layout (left to right, top to bottom). The relative position of the control in this flow is determined by the location of the object declaration in your code.

In addition to the flow layout, each web container is divided into a fixed number of equal-width columns (piColumnCount). Child controls are aligned to these columns to determine their horizontal position and width.

Set piColumnIndex to position a Form control in a particular column of the parent container.

Set piColumnSpan to determine the width of the Form control i.e., the number of columns occupied by the control. The actual width is determined by the number of columns and the width of the parent container.

For more information, see Positioning and Layout of Controls.

Each form control has a pre-determined height according to the web application's CSS theme (psTheme). You can also instruct a form control to occupy all available vertical height in its parent container by setting pbFillHeight to true.

Label Support

By default a portion of the control's width is reserved to display a descriptive label. By default, the label is displayed to the left of the control and consumes approximately 120px of the total width.

Set pbShowLabel to False to hide the label and remove space used the control's label. By default, pbShowLabel is True. The liberated space will be occupied by the actual control.

Set psLabel to the text string you want to display as a label.

Set peLabelAlign to position the label text to the left, right or center of the space allocated to the control's label (alignLeft, alignRight, alignCenter).

Set peLabelPosition to change the position of the space allocated to the control's label. By default, the label is positioned to the left of the control (lpLeft). The label can also be positioned above or to the right of the control (lpTop, lpRight).

Set piLabelOffset to change the amount of space that is consumed by the control's label. By default, the label consumes approximately 120px.

The label's text color is determined by the web application's CSS theme (psTheme). Set psLabelColor to directly override the label's CSS themed color.


Color

The color of a Form control is determined by the web application's CSS theme (psTheme). You can define additional or replacement CSS styles in your web application's application.css file. Set psCSSClass to the CSS class name you would like to be applied to a Form control.

Set psBackgroundColor and psTextColor to directly override the control's CSS themed color.

See Also

Styling Web Applications