cObject
---cWebObject
------cWebBaseUIObject
---------cWebBaseDEOServer
------------cWebBaseControl
---------------cWebBaseDEO
------------------cWebBaseForm
---------------------cWebForm
------------------------cWebBaseSelectionForm
------------------------cWebColorForm
------------------------cWebColumn
------------------------cWebDateForm
------------------------cWebSuggestionForm
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.
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.
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).
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.
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.
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.
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.
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.
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).
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.
Form controls support password entry by obscuring the typed characters. Set pbPassword to true to enable password entry.
This control can be used as a valid drop target by registering it as such in a cWebDragDropHelper object.
The supported actions for this control are:
- C_WebDropOnControl
This allows the control to accept data dragged from elsewhere in the control (if configured that way) and can also be used to accept files when registered within a cWebDragDropFileHelper.
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.
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.
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.