cObject
---cWebObject
------cWebBaseUIObject
---------cWebBaseDEOServer
------------cWebBaseControl
---------------cWebBaseDEO
------------------cWebBaseForm
---------------------cWebForm
------------------------cWebColumn
---------------------------cWebColumnHighlight
Web list and grid controls provide the basis for creating multi-row, multi-column display and entry. Each column in a grid is represented by a column object. Web lists and grids (cWebList, cWebGrid) use the cWebColumn, cWebColumnButton, cWebColumnCheckbox, cWebColumnCombo, cWebColumnDate, cWebColumnImage and cWebColumnLink classes for column objects.
cWebColumn represents a column of text items, for example, a column of customer names.
A column can be used with or without a data binding. When used with a data binding, the column 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
Procedure OnLoad
Send Find of oCustomer_DD FIRST_RECORD Index.1
End_Procedure
Object oCustomerList is a cWebGrid
Set pbFillHeight to True
Object oCustomer_Name is a cWebColumn
Entry_Item Customer.Name
Set psCaption to "Customer Name"
Set piWidth to 50
End_Object
Object oCustomer_City is a cWebColumn
Entry_Item Customer.City
Set psCaption to "City"
Set piWidth to 50
End_Object
Object oCustomer_State is a cWebColumnCombo
Entry_Item Customer.State
Set psCaption to "State"
Set piWidth to 40
End_Object
Object oCustomer_Status is a cWebColumnCheckBox
Entry_Item Customer.Status
Set psCaption to "Active"
Set piWidth to 15
End_Object
End_Object
End_Object
The above sample demonstrates a web view (cWebView) containing a data dictionary and a grid (cWebGrid) whose rows and columns are populated from the data dictionary.
The grid contains four column objects, each with a data binding to the Customer table. Two cWebColumn objects are used to display the customer name and city text values; a cWebColumnCombo object is used to display a list of combo items to display and select a state; a cWebColumnCheckbox object is used to display the customer active status in a column of checkboxes.
The OnLoad event is fired when the view is first loaded to the client. This has been augmented to 'seed' the Customer data dictionary object (DDO) with the first record in the table. This seeding will cause the grid to fill its rows with data from the customer table starting with the record found in the OnLoad event.
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 column must have a unique name).
Column controls must be placed within a web list or grid object (e.g. cWebList or cWebGrid).
Text column objects support a data binding to display values from a database Table.Column. When the grid is connected to a data dictionary Server object and the column has a data binding, it will display column values from the binding table. Changes entered into the column 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 column control can be used without a data binding by accessing the control's value.
The psValue property allows you to get or set the value of the column's 'current row'.
See also: cWebGrid, psCurrentRowID and OnChangeCurrentRow.
An event is triggered whenever the current row 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 current row value is changed. Write an OnChange event handler in your Form object to perform some action when the current row 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 current row value changes.
If the grid has a server data dictionary server but the column does not have a data binding then a special event (OnSetCalculatedValue is triggered for the column whenever the row value needs to be updated. 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 column 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 column'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.
Text columns support data masking and the ability to set the alignment of the form's text.
If the column 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).
Columns 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 column's prompt button could activate a customer lookup list to select a customer.
If the column has a data binding then the data dictionary object's Field_Prompt_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 column 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.
If you need full programmatic prompt support without setting phoPrompt, use the following interface:
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.
Text columns support password entry by obscuring the typed characters. Set pbPassword to true to enable password entry.
Grid columns are ordered left to right according to the order of column object declarations in your code. In the above example, the leftmost column would be "Customer Name" and the rightmost column "Customer Status".
Set piWidth to determine the width of the column relative to all the columns in that grid, i.e. relative to the piWidth value of all the other columns.
The actual width of each column is determined by dividing the dividing the column piWidth value 'c' by the total piWidth of all columns 't', multiplied by the actual width of the grid 'g':
Column width = (c / t) * g
The cWebList and cWebGrid classes allow for a configurable column layout, which inlcudes moving and hiding columns.
pbAllowColumnReordering determines whether columns can be reordered by dragging them to a different position. Dragging is done by picking up the column by its header.
pbHidden indicates whether the column is currently hidden or not.
piPosition indicates the current position of the column in the list.
Set pbRender to false to create a hidden column. A hidden column can contain data but is not displayed on the client. Hidden columns provide a mechanism for storing additional row information, which, while needed for processing, should never be displayed.
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.
The colors of a column and the column caption are 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 column.
You can use pbAllowHtml to apply embedded HTML to the web column.
Set psCaption to give the column a title in the grid's header section.
If the grid is populated from a data dictionary structure and the column has a data binding, then each grid column with a data binding to an indexed table.column is sortable at runtime. The user can sort the column by clicking in the column header.
Sortable data bound columns will have the pbSortable property set to true by default. Set pbSortable to false to override the ability to sort a column at runtime.
See also cWebGrid and piOrdering, pbReverseOrdering, piSortColumn.