Class: cWebPromptList

cObject
---cWebObject
------cWebBaseUIObject
---------cWebBaseDEOServer
------------cWebBaseControl
---------------cWebList
------------------cWebPromptList

The cWebPromptList is used to create is a web lookup list control. It is specifically designed to list data in a modal dialog (cWebModalDialog), allowing the user to select an item from the list. The selected item would be returned to the object that invoked the modal dialog.



In the Web Application Framework, prompt lists are primarily used in lookup dialogs. These dialogs are 'attached' to the data dictionary of the table being listed in the lookup via the Field_WebPrompt_Object data dictionary property. This property will automatically invoke the prompt dialog from any control that has a data binding to the referenced data dictionary table and column. See DataDictionary and Field_WebPrompt_Object for more information.

The cWebPromptList class is designed to work in coordination with the cWebModalDialog class, i.e. as a list inside a modal dialog. If you wish to implement a selection list inside a non-modal view (cWebView), then use the cWebList class instead.

Prompt lists

Sample

Object oSalesPLookup is a cWebModalDialog
    Set piColumnCount to 5
    Set psCaption to "Sales Person Lookup"
    Set piWidth to 450
    Set piHeight to 400

    Object oSalesP_DD is a SalesP_DataDictionary
    End_Object 

    Set Main_DD To oSalesP_DD
    Set Server  To oSalesP_DD

    Object oPromptList is a cWebPromptList
        Set pbFillHeight to True

        Object oSalesPID is a cWebColumn
            Entry_Item SalesP.ID
            Set psCaption to "ID"
            Set piWidth to 70
        End_Object 

        Object oSalesPName is a cWebColumn
            Entry_Item SalesP.Name
            Set psCaption to "Sales Person Name"
            Set piWidth to 262
        End_Object 
    End_Object 

    Procedure Popup Handle hoReturnObject
        Forward Send Popup hoReturnObject
        Send InitializePromptList of oPromptList
    End_Procedure 

    Set pbServerOnSubmit to True
    Procedure OnSubmit 
        Send Ok of oPromptList
    End_Procedure 
End_Object

The above example demonstrates a modal dialog (cWebModalDialog) with a prompt list for selecting a sales person. The selected sales person ID would be returned to the object that invoked the modal dialog. A sales person will be selected and the dialog closed when the user double-clicks a row in the list.

It is necessary to call InitializePromptList to fill the list with data. In the above example this is performed during the dialog's OnShow event (i.e. each time the dialog is shown).

The dialog's OnSubmit event has also been modified to force the prompt list to select the currently highlighted row and close the dialog. This simply means that if the user will press [Enter] anywhere in the dialog then the selection will be made.

General List Behavior

The cWebPromptList class inherits all of the rules, behaviors and attributes of the cWebList class including: Object Name, Object Placement, Data Binding, Size and Location, Sorting and Appearance.

Refer to cWebList for information on these topics.

Filling a Prompt List

It is necessary to initiate the process of filling a prompt list with data. Send InitializePromptList to the prompt list during the host dialog's OnShow event to fill the prompt list each time the dialog is activated.

If a the prompt list is data-aware, i.e. its data is served from data dictionary objects (DDOs) and its columns have data bindings and pbDataAware is True, then InitializePromptList will cause the list to be filled with the data provided by these DDOs.

It the prompt list is not data aware, i.e. pbDataAware is False, it will be necessary to implement the OnManualLoadData event to populate the prompt list.

Activating a Prompt List

Send Show to the modal dialog that hosts the prompt list to activate the prompt list.

Send InitializePromptList to fill the prompt list with data when the host dialog is activated. Usually you will send this inside the dialog's OnShow event. You will need to activate the OnShow event by setting pbServerOnShow to true in the dialog object.

Prompt lists do not use the cWebModalDialog interface for activating dialogs and returning information to the invoking object. cWebPromptList uses a custom method for activating and updating the modal dialog.

Modes of Operation

Set the peUpdateMode property to determine the mode of operation between the prompt list and its invoking object.

The above example uses the prompt list in its most commonly used mode. The prompt list is invoked by a data entry control that uses the same table as the prompt list. An item is selected and the invoking object's data dictionary is updated with the selected item's RowID. This is a relational update (peUpdateMode = umPromptRelational).

The prompt list can be used in other non-relational modes. It can be used to update just the psValue property of the invoking object, a value update (peUpdateMode = umPromptValue). It may be used in a custom fashion where the invoking object determines what is updated, a custom update (peUpdateMode = umPromptCustom). It can also be used without any invoking object at all, a non-invoking update (peUpdateMode = umPromptNonInvoking).

If you are using the umPromptCustom or umPromptNonInvoking update modes you will need to write special code to process the prompt list selections.

Closing a Prompt List

When a selection has been made the by the user, the selected row must be processed (according to the update mode - above) and the modal dialog that hosts the prompt list should is closed.

Send OK to the prompt list to process the selected row and close the host dialog.

Send Cancel to the prompt list to close the host dialog without processing the selected row.

Writing a Custom Update Handler

When using custom update (peUpdateMode = Custom), you will need to implement your own handler for retrieving the selected row data and updating the invoking data entry object (DEO).

Augment OnMoveValueOutByCustom to retrieve the selected row and update the invoking object.

In addition to OnMoveValueOutByCustom, you can use the prompt list's callback mechanism to send a callback message to the invoking DEO for retrieving the selected row.

WebGet psValue of the desired prompt list column object (cWebColumn) to retrieve the selected row's column value.

Get CurrentRowID of the prompt lists Server DDO to retrieve the RowID of the currently selected row.

Call GetInvokingObject to retrieve the object handle of the DEO that activated the prompt list, i.e. the invoking object.

Use WebGet psPromptUpdateCallback to retrieve the name of the invoking object's callback function. To execute the callback the function name must be converted into a function handle by calling WebMethodByName.

Prompt List Behavior

To simplify its use for the most common use cases, a prompt list exhibits the following default behavior:

A prompt object that is relational (peUpdateMode is umPromptRelational)

The prompt object uses information from the invoking object to determine which column to start in, how to seed the list and which index order to use.

The prompt object uses its own Data Dictionary Server.

Clicking on a column header of an indexed field changes the ordering. Clicking a second time reverses the order.

Switching columns (i.e. tabbing from one column to the next) will change the index ordering.

Non indexed columns are non-focusable.

You can search for a value in the indexed column via a search dialog. If you start typing the search dialog is invoked.

These behaviors can all be changed. Some of the important properties are:
pbAutoSeed - Determines if the list should be seeded from the invoking object.
pbAutoServer - Determines if the list should attempt to use the invoking DEO's DataDictionary server object. This lets you acquire and use the constraints of the invoking view.
piInitialColumn - Determines if the list should attempt to use the best column based on the invoking object as its choice for initial column and initial index ordering.
pbAutoSearch - Determines if a search window appears when you start typing, allowing you to search for data within the list.

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.

cWebList | cWebModalDialog