Class: cWebCombo

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

Use the cWebCombo class to display data in a drop-down combo list. A combo control appears in two parts: the top part displays the current value (i.e. the selected item). The second part is a list of items that can be selected.



A combo is ideal for data entry that requires the user to select from a finite set of valid values, for example a view asking for the 'state' field of an address.

See cWebParentCombo for creating combo controls that show related parent table data.

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

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

A web combo control 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
    
    Object oState is a cWebCombo
        Set piColumnSpan to 3
        Set psLabel to "State:" 
        Entry_Item Customer.State
    End_Object
End_Object

The above sample demonstrates a cWebView with a DataDictionary object (DDO) and a cWebCombo object with a data binding to the Customer table, State column. The DataDictionary validation rules for the state column are used to populate the control's combo list with valid state names.

Object oView is a cWebView

    Object oDayOfWeek is a cWebCombo
        Set piColumnSpan to 3
        Set psLabel to "Day of the Week:"

        Procedure OnFill
            Forward Send OnFill
            Send AddComboItem "MON" "Monday"
            Send AddComboItem "TUE" "Tuesday"
            Send AddComboItem "WED" "Wednesday"
            Send AddComboItem "THU" "Thursday"
            Send AddComboItem "FRI" "Friday"
            Send AddComboItem "SAT" "Saturday"
            Send AddComboItem "SUN" "Sunday"
        End_Procedure

        Set pbServerOnChange to True

        Procedure OnChange String sNewValue String sOldValue
            Forward Send OnChange sNewValue sOldValue
            Send ShowInfoBox ("New combo value is: " + sNewValue)
        End_Procedure
    End_Object
End_Object

The above sample demonstrates a cWebView containing a cWebCombo object. The combo is used to select a day of the week value. The combo list is populated with combo value-description pairs for each day of the week. The descriptive names (Monday, Tuesday, etc) will be displayed in the control and in the combo list. The combo values (MON, TUE, WED, etc) represent the object's valid range of values.

When a new item is selected from the combo list, the OnChange event is triggered, which displays an info box with the control's new combo value (i.e. one of MON, TUE, WED etc).

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

Combo controls must be placed within a web container (e.g. cWebPanel, cWebView or cWebModalDialog).

Combo controls may not be nested inside other web controls. You may not mix web panels and web controls as sibling objects.

Data Binding

Combo objects support a data binding to display values from a database Table.Column. When the control has a data binding, 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. 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 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, tooltip, control focus rules, control blur rules, and much more. These settings may also be controlled manually by setting properties.

Accessing the Control Value

The combo 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 combo 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 combo 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 combo object whenever a find or clear operation is performed on the data dictionary object. Write an OnSetCalculatedValue event handler in your combo object to generate a 'calculated' value for the control 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 combo control when the 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 the psValue property. 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 (only for data-aware objects). When pbAddEmptyItem is true, the value stored in psEmptyItemDescription is added to the combo list as the combo description.

You can set a default value using psValue.

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 combo control in a particular column of the parent container.

Set piColumnSpan to determine the width of the combo 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 combo control has a pre-determined height according to the web application's CSS theme (psTheme). You can also instruct a combo 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 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.

Set pbShowLabel to false to hide the label and remove space used the control's label. By default, pbShowLabel is true.

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 color of a combo 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 combo control.

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

cWebParentCombo | Styling Web Applications