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.
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.
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.
Each modal dialog object in your web application must have a unique name.
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.
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.
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
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.
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.
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.
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.
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.
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
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.
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.
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.
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
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.
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.
cWebPromptList | Styling Web Applications