Class: cWebColumnCombo

cObject
---cWebObject
------cWebBaseUIObject
---------cWebBaseDEOServer
------------cWebBaseControl
---------------cWebBaseDEO
------------------cWebCombo
---------------------cWebColumnCombo

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.



cWebColumnCombo represents a column of data items with an associated combo-list that allows the user to select a value, for example, a column representing the 'state' field of a customer address. The text in a combo column cannot be edited directly by the user. It can only be changed by selecting an item from the combo list.

A combo can be used with or without a data binding. When used with a data binding, the combo column provides automatic support to populate and modify the column data from a database table.column. Validation rules from the DataDictionary are used to build the combo list.

When used without a data binding, you will use the class interface to read or write the row values and populate the combo list.

cWebColumnCombo does not permit direct editing of the combo control's value other than selecting a new value from the combo list.

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
    
    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 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.

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 column must have a unique name).

Object Placement

Column controls must be placed within a web list or grid object (e.g. cWebList or cWebGrid).

Data Binding

Combo 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, then 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. Validation rules from the data dictionary are used to build the combo list.

Use the Entry_Item command to set a data binding.

Sample

Entry_Item Customer.Name

Entry_Item expressions, e.g. (GetState(Self)) are not supported in web object data bindings. Use the 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
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.

Using a cWebColumnCombo object to display related parent table values is not supported. We recommend using a cWebColumnSuggestion object for this.

Accessing the Control Value

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 column object to generate a 'calculated' value for each record in the server data dictionary object's table.

Filling the Combo List

The combo list is the list of items that drops down below the current row when the column's combo button is clicked. It contains the list of valid items that can be selected.

Each item in a combo list consists of two values: The combo value and the combo description. The combo value is the actual value associated with the selected combo item. This is the value that is returned when you get psValue of the current row. The combo description is the value that is 'shown' in the control and in the combo list for a given combo value. These dual values allow you to set up a combo control with a descriptive value visible to the user of your web application with a coded value that is stored in your database.

If you do not need this duality, then the combo value and combo description can be set to the same value for each combo item.

If the column has a data binding then the combo list will be populated automatically according to the data dictionary validation rules of the binding table.column. Refer to the Data Dictionary Guide for more information.

If the column does not have a data binding or the data binding does not define any validation rules, then you can manually fill the combo list using the following interface:

Augment the OnFill event to populate the column's combo list. Inside OnFill, send AddComboItem for each item you wish to add to the combo list.

If you want to support the ability to select a null value from the combo list then set pbAddEmptyItem to true. When pbAddEmptyItem is true, then the value stored in psEmptyItemDescription is added to the combo list as the combo description.

Data Type

If the column has a data binding (see above) then the data type is automatically set according to the data dictionary rules.

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

Size and Location

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

Caption

Set psCaption to give the column a title in the grid's header section.

Sorting

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.

Keyboard Navigation

Press F4 to drop down the combo list. Press Shift+DownArrow and Shift+UpArrow to navigate along the items in the combo list. Press DownArrow or UpArrow to move to the grid row below or above the current row, respectively.

Drag and Drop Support

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.

Use with CodeValidationTable

If you use a cWebCombo or cWebColumnCombo with a CodeValidationTable via a DataDictionary, the default will display the Code descriptions.

Sample

To display values instead of descriptions you can override AddComboItem like this:

Object oOrderHeaderTerms is a cWebCombo
    Entry_Item OrderHeader.Terms
    Set piColumnSpan to 5
    Set piColumnIndex to 0
    Set psLabel to "Terms:"
    Set peLabelAlign to alignRight

    Procedure AddComboItem String sValue String sDescription
        Forward Send AddComboItem sValue sValue
    End_Procedure
End_Object

Color

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.

See Styling Web Applications for more on the subject.