Class: cWebModalDialog

Properties  Events  Methods    Index of Classes

The Web Framework modal dialog class

Hierarchy

cObject
---cWebObject
------cWebBaseUIObject
---------cWebBaseDEOServer
------------cWebBaseContainer
---------------cWebWindow
------------------cWebView
---------------------cWebModalDialog

Library: Web Application Class Library

Package: cWebModalDialog.pkg

Description

Use the cWebModalDialog class to create the wrapper object for a modal dialog. A modal dialog is a view for some purpose that is displayed as a floating window above the underlying web application and must be explicitly closed in order to return to the rest of the web application.

A Web Framework modal dialog displays as a floating, dragable, resizable dialog panel in your browser. While it is active, you cannot interact with any controls in the view 'underneath' the modal dialog.

Example uses for modal dialogs in a web application are:
- Lookup lists (prompt lists)
- Configuration dialogs
- Login dialogs
- Any entry or display that requires modality.

A modal dialog will typically contain other web controls such as web panels, forms, buttons, tab dialog, etc. If the modal dialog will access your application's database then it will contain a data dictionary object structure.

If you wish to display a simple message dialog, then it is much simpler to use the ShowInfoBox, ShowYesNo, or ShowMessageBox messages than to create your own modal dialog for this purpose.

Mobile/Touch Use of Dialogs


Modal dialogs can be used in both a desktop-style or mobile/touch style Web Application. Normally, a mobile/touch web app would try to minimize the use of modal dialogs and keep them fairly simple when they need to be used. When used in this way, a modal dialog will appear to be a part of the current view in the drill-down view stack.

With either desktop or mobile/touch style you would use the Popup, OK, Cancel interface to activate or close a modal dialog (see below).

The cWebModalDialog class inherits but not support the drill-down Navigate interface used by views in a mobile/touch web application. Modal Dialogs are not added to the mobile/touch view stack and will not appear in the standard breadcrumb control.

Sample

Object oWebCalculator is a cWebModalDialog
    Set piWidth to 300
    Set piHeight to 125
    Set pbResizable to False
    Set psCaption to "Web Calculator"
    Set piColumnCount to 2

    Object oNum1 is a cWebForm
        Set peDataType to dtNumber
        Set piPrecision to 4
        Set psLabel to "First Number"
        Set piColumnSpan to 0
    End_Object

    Object oNum2 is a cWebForm
        Set peDataType to dtNumber
        Set piPrecision to 4
        Set psLabel to "Second Number"
        Set piColumnSpan to 0
    End_Object

    Object oOkButton is a cWebButton
        Set psCaption to C_$OK
        Set piColumnIndex to 0

        Procedure OnClick
            Send Ok
        End_Procedure
    End_Object 

    Object oCancelButton is a cWebButton
        Set psCaption to C_$Cancel
        Set piColumnIndex to 1

        Procedure OnClick
            Send Cancel
        End_Procedure
    End_Object 

    // used to initialize the dialog
    Procedure Popup Handle hoReturnObject
        WebSet psValue of oNum1 to 0
        WebSet psValue of oNum2 to 0
        Forward Send Popup hoReturnObject
    End_Procedure

    Procedure OnSubmit
        Send Ok
    End_Procedure

    // After completion, call this from the invoking object 
    // to get data from the dialog 
    Procedure GetResultValues Number ByRef N1 Number ByRef N2 Number ByRef nTotal
        WebGet psValue of oNum1 to N1
        WebGet psValue of oNum2 to N2
        Move (N1 + N2) to nTotal
    End_Procedure
End_Object

The above example demonstrates a simple calculator dialog that allows the input of two numbers and adds them together. Two web forms are used to enter the numbers and two buttons are used to close the dialog.

The dialog is activated by sending Popup. The oOkButton sends the OK message and the oCancelButton sends the Cancel message. Both messages will close the dialog, but the state of the pbCanceled property is set to True or False, accordingly.

When the dialog is closed via the OK message, then it will send OnCloseModalDialog to the object that invoked it (via Popup).

This dialog would be used from an invoking object in some other view in the following way:

Object oCalcButton is a cWebButton
    Set psCaption to "Calculate"

    Procedure OnClick
        Send Popup of oWebCalculator (Self)
    End_Procedure

    // standard callback method when modal dialog is invoked using Popup 
    Procedure OnCloseModalDialog Handle hoModalDialog
        Number n1 n2 nTotal
        // assume that this function no longer returns bCanceled.     
        Send GetResultValues of hoModalDialog (&n1) (&n2) (&nTotal)
        Send ShowInfoBox (String(n1) + "+" + String(n2) + "=" + String(nTotal)) "Calculation Complete"            
    End_Procedure
End_Object

The resulting addition is retrieved by calling GetResultValues.

See cWebPromptList for an example use of a data-aware modal dialog.

Object Name

Each modal dialog object in your web application must have a unique name.

Object Placement

Modal dialog objects are placed as the root object inside their own source file (e.g. CustomerLookup.wo). This source file is included in your web application by placing a Use statement inside your global cWebApp object, below the application's command bar.

The Studio's Workspace Explorer can generate the Use statement for you when you select the Add Component menu option.

If you create a lookup list for a particular table using the Studio wizard, then the wizard will place the Use statement for this lookup in the file containing the table's DataDictionary class.

Activating a Modal Dialog

Send Popup to activate a modal dialog. Popup expects an object handle as the first parameter. This object will be sent the OnCloseModalDialog event when the modal dialog is closed. The message can be customized by setting psReturnMessage.

Modal dialogs containing prompt lists (cWebPromptList) uses a custom method for activating and updating the modal dialog. Please see cWebPromptList for details.

Before sending Popup, you can initialize any web properties of your modal dialog using WebSet.

Object oButton is a cWebButton
    Set psCaption to "Question "

    Procedure OnClick
        WebSet psQuestion of oQuestionDialog to "What is your name?" 
        Send Popup of oQuestionDialog Self
    End_Procedure    
End_Object

The above example demonstrates a button object that activates a modal dialog (oQuestionDialog) in its OnClick event. Before the dialog is activated, a web property belonging to the dialog, named psQuestion is initialized to the value "What is your name?".

If the dialog's pbServerOnShow property is True, then the OnShow event will be sent to the dialog during popup.

The cWebModalDialog class inherits but not support the drill-down Navigate interface used by views in a mobile/touch web application. Modal Dialogs are not added to the mobile/touch view stack and will not appear in the standard breadcrumb control. i.e. do not send the NavigateBegin, NavigateCancel, NavigateClose or NavigateForward messages to a modal dialog.

Sample

Alternatively, you can send an intermediate custom method that accepts parameters and then calls Popup.

Object oOpenDialog_btn is a cWebButton
    Set psCaption to "Open Dialog"
    
    Procedure OnClick
        Send PopupTheDialog of oWebModalDialog Self "Param 1" "Param 2"
    End_Procedure
    
    Procedure OnCloseModalDialog Handle hoModalDialog
        String sResult
        
        Get DialogResult of hoModalDialog to sResult
    End_Procedure
End_Object

//  This is an example of how a dialog is called. You can pass any number of set up parameters 
//  which will use WebSet to configure controls or to store the values. Note that you cannot do
//  finds here yet because the DDO structure is not being synchronized with the client yet. 
//  Please use the OnShow event for that (you can use web properties to pass on information to 
//  the OnShow). We pass on the hReturnObj handle to the Popup method so that the 
//  OnCloseModalDialog is executed when the Ok message is send.

Procedure PopupTheDialog  Handle hReturnObj String sSetupParameter1 String sSetupParameter2
    // Initialize any object properites as needed via WebSet
    
    // Invoke the modal dialog    
    Send Popup hReturnObj
End_Procedure

//  In the OnShow you would perform any finds needed when opening a modal dialog.
Set pbServerOnShow to True
Procedure OnShow
    //  Find your records here
End_Procedure

//  This is an example of a method that would be called by the return object when 
//  OnCloseModalDialog is executed. It will use WebGet to get the result values from the 
//  controls. It can also use the DDO structure to get values of the record buffer here. If one 
//  return value is not enough consider using a Struct or ByRef parameters to return multiple 
//  values.
Function DialogResult Returns String
    String sResult
    
    //  Get the 'result' of the dialog when needed
    
    Function_Return sResult
End_Function


Closing a Modal Dialog


OK

Send OK to close a modal dialog with the intent of performing some application specific action, for example passing back a selected row in a prompt list.

The OK message will set the dialog's pbCanceled property to False. This indicates that the dialog was not closed by being canceled.

Before the dialog is closed, the callback message (typically OnCloseModalDialog) will be sent back to the callback object (the object handle passed to Popup). See Returning Data from a Modal Dialog (below).

If the dialog's pbServerOnHide property is True, then the OnHide event will be sent to the dialog during the close operation.

OnSubmit

Often you will want the Enter key to trigger the modal dialog to close like the OK operation. This can be handled via the OnSubmit event. Set pbServerOnSubmit to True to enable the OnSubmit event in a modal dialog.

Object oMyDialog is a cWebModalDialog
    Set pbServerOnSubmit to True
    // other settings go here...

    Procedure OnSubmit
        Send Ok
    End_Procedure
End_Object

In the above example, pbServerOnSubmit is set to True to enable the OnSubmit event on the server. The OnSubmit event is coded to close the dialog via the OK message.

Cancel

Send Cancel to close a modal dialog with the intent of not performing any further action. The Cancel message will set the dialog's pbCanceled property to true.

Set pbServerOnEscape to True to instruct the modal dialog to send a callback message (typically OnCloseModalDialog) to the callback object when the dialog is cancelled. By default, the callback is not sent during cancel.

If the dialog's pbServerOnHide property is True, then the OnHide event will be sent to the dialog during the close operation.

OnEscape

Set pbServerOnEscape to True to enable the OnEscape event in a modal dialog. This will ensure that the server is sent the OnEscape event whenever the application user hits the ESC button while inside the modal dialog.

Object oMyDialog is a cWebModalDialog
    Set pbServerOnEscape to True
    // other settings go here...

    Procedure OnEscape
        Send Cancel
    End_Procedure
End_Object

In the above example, pbServerOnEscape is set to True to enable the OnEscape event on the server. The OnEscape event is coded to close the dialog via the Cancel message.

Returning Data from a Modal Dialog


Retrieving Data

A common programming mistake is to send Popup to a modal dialog followed by code to retrieve web property values from that dialog, for example:

Object oButton is a cWebButton
    Set psCaption to "Question"

    Procedure OnClick
        Send Popup of oQuestionDialog Self
        WebGet psAnswer of oQuestionDialog  // THIS WILL NOT WORK!
    End_Procedure
End_Object

In a web application, the instruction to popup a dialog is simply added to the response data that is sent back to the client when all of the code associated with the request is completed. This means that the WebGet in the above code is executed before the client is even instructed to open the modal dialog. It is for this reason that modal dialogs use a callback mechanism when the dialog is about to close. It is inside the callback event (by default OnCloseModalDialog) that you will write code to retrieve data from the modal dialog.

Declaring a Callback Method

When a modal dialog is closed via the OK message, a callback message will be sent to a callback object. The callback object is the object handle that was passed to the Popup message that opened the modal dialog, see Activating a Modal Dialog (above). By default the callback message is OnCloseModalDialog.

Augment the OnCloseModalDialog event in the callback object to process data from the modal dialog. This event is sent before the modal dialog is closed so that all of the modal dialog's web property values will be available at the server during this event.

Set psReturnMessage to change the callback message that is sent when the modal dialog is closed. Note: The new callback method must declare the same parameters as the OnCloseModalDialog event and must be published using the WebPublishProcedure command. The WebPublishProcedure command declares the callback message as a secure part of the external interface of the callback object. Example:

Object oButton is a cWebButton
    Set psCaption to "Question"

    Procedure OnClick
        WebSet psReturnMessage of oQuestionDialog to "OnAnswer" 
        Send Popup of oQuestionDialog Self
    End_Procedure

    Procedure OnAnswer Handle hoDialog
        // do something
    End_Procedure

    WebPublishProcedure OnAnswer
End_Object


Switching Between Views and Dialogs

In desktop-style view navigations, the web properties set within a view are maintained when you switch between views. It is clear that this is the behavior you'd want with these kinds of views, as it allows you to switch between views without losing content. The key word here is switch.

With modal-dialogs (desktop style or drill-down), web property changes are not maintained across multiple invocations. In this case, you are not switching view, you are invoking a dialog and then conceptually closing it. The next time you invoke it, you are starting over. When starting over, all web properties are reset to their original value. The reason we do it this way is that this is the most controlled mechanism for handling dialogs. If the old web property contents were maintained (which would include data in forms, etc.) you would end up with whatever just happened to be in that last view. To make this more complicated, some web properties are being set by the server during the invocation and others are "left over" on the client. This is hard to control. We would advise that you WebSet your web properties each time the object is being invoked.

Drill-down views behave the same as modal dialogs. You can think of them as being invoked and then closed. When closed, you start all over. This is even more important with drill-down views, because the same view may be invoked from a number of different places in a breadcrumb, where they may do very different things. This makes the "left-over" client properties seem even more confusing.

There is a property that controls this - pbOverrideStateOnShow. By default, it is set to False in desktop-style views and set to True with modal dialogs and drill-down style views. If you set this to False, you will get the persistent web property value behavior. You will also have to deal with the "left-over" property value issue just discussed. Our advice would be to not change this property and to use the OnNavigateForward event or OnShow to set these properties during each invocation.

Database Access

You can provide database support for a modal dialog by creating a data dictionary object (DDO) structure.

Set the Server and Main_DD properties to enable data binding in your dialog's data entry objects (cWebForm, cWebList, cWebCheckbox, etc).

Refer to cWebView for more information on data-aware views and dialogs.

Restricting Access

Augment the AllowAccess event to determine whether the client session has rights to the dialog. If this function returns false then the client will not be allowed to show the dialog or perform any action in that dialog.

Sample

In this example, the dialog can only be accessed if the piUserRights property of the session manager is 1 or higher. See cWebSessionManagerStandard for more information.

Function AllowAccess Returns Boolean
    Boolean bAccess
    Integer iUserRights
    
    Forward Get AllowAccess to bAccess
    
    If (bAccess) Begin
        Get piUserRights of ghoWebSessionManager to iUserRights
        
        If (iUserRights < 1) Begin
            Move False to bAccess
        End
    End
    Function_Return bAccess
End_Function


Unloading Dialogs for Security

When a modal dialog is loaded and displayed on the client, a cached copy of the dialog (including sub objects and web property values) will remain even after the modal dialog has been closed. Normally, this does not present a security problem as the logged in user should already have access rights to the dialog in order to load it in the first place.

A potential security consideration occurs if, after a dialog has been loaded, the current user logs out and a new user, with different access rights, logs in. The safest approach here is to ensure that the entire web application is reloaded whenever a new user tries to log in. This will ensure that all cached data is removed from the client.

Send NavigateRefresh to the global cWebApp object (ghoWebApp) to reload the entire web application.

Sometimes you may wish to retain the web application's current state, but remove specific views or dialogs from the client. Send UnloadView to remove a specific view or dialog from the client.

Appearance

The appearance of a modal dialog 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 modal dialog.

Set pbResizable to control whether a modal dialog can be resized at runtime with the mouse.

Set pbShowClose, pbShowMax and pbShowMin to determine whether a modal dialog will display and support the standard close, maximize and minimize buttons in the dialog's caption bar.

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

See Also

cWebPromptList | Styling Web Applications