dialogbeforeclose
This article is about the dialogbeforeclose UDB event handler.
dialogbeforeclose
The dialogbeforeclose event may be called from web pages developed in Web Designer and processed by a USoft page engine service.
| Event | Applies to | Occurs when |
|---|---|---|
dialogbeforeclose | Dialog controls | Immediately before a dialog closes |
This event is triggered on the dialog's own <dialog> element immediately before the dialog is closed, for the same kinds of dialog described for dialogopen: a custom Web Designer dialog, whose close is handled by DialogControl.methods().close() (controls/dialog-control.js), and a lookup, confirmation, or other data-input dialog, whose close is handled by DataInputControl.event() (controls/data-input-control.js). Both classes are subclasses of UdbControl.
Purpose
Despite its "before" name, dialogbeforeclose is not a cancelable event: by the time it fires, the decision to close the dialog has already been made, and nothing in the surrounding code inspects any value returned or set by your handler to abort the close. The dialog's close() call and the dialogclose event both follow unconditionally, immediately after dialogbeforeclose has fired. This is different from genuinely cancelable "before" events such as beforerollback or rowpredelete, where setting options.success = false in the handler does interrupt further processing. Use dialogbeforeclose only to run code that must execute while the dialog is still open (for example, to read its current field values before they disappear from the DOM); do not use it to try to prevent the dialog from closing.
How to use
Find or create an Event Listener object with Event Type = dialogbeforeclose. Event Listeners are in the Web Designer Controls catalog:
Insert the event listener into the dialog control. Insert a callClientScript action into the event listener. Use this action's Script property to code the behaviour that you want to see when the event occurs.
You are implicitly associating the event with an event handler function. This function has an options parameter. For available options, see the Options section at the end of this help topic:
function(*evt*, *options*){ ... }
Or you can create the event handler more explicitly by attaching a jQuery handler on the control's element.
No options object is passed to the event handler function by any of the current triggering call sites, so the event is a plain notification that the dialog is about to close. The underlying jQuery-style usdialog('close', value) method (used by system dialogs, usoft.module.controls.js) technically forwards an optional caller-supplied value as event data if one is passed to it, but none of the standard USoft dialog call sites currently supply such a value, and (as explained above) no code checks it to decide whether to proceed with the close.