Skip to Main Content

Namespace: message

QuickNav

Properties

Functions

apex.message

The apex.message namespace is used to handle client-side display and management of messages in Oracle Application Express.

Properties

(static) TYPE :object

Message type constants
Type:
  • object
Properties:
Name Type Description
TYPE.SUCCESS string Success message Value "success".
TYPE.ERROR string Error message Value "error".

Functions

(static) addVisibilityCheck((Function))

In order to navigate to items (page items or column items) that have an error (or anything else that can be in an error state), the error item must be visible before it is focused. Any region type that can possibly hide its contents should add a visibility check function using this method. Each function added is called for any region or item that needs to be made visible. This function is for APEX region plug-in developers.
Parameters:
Name Type Description
(Function) pFunction A function that is called with an element ID. The function should ensure that the element is visible if the element is managed or controlled by the region type that added the function.
Example
// For example let’s assume we have a Region plug-in type called 'Expander', that can show or hide its contents
// and can contain page items. For purposes of example, this plug-in adds an 't-Expander' class to its region
// element and also has an 'expand' method available, to expand its contents. This region should register a
// visibility check function as follows:
apex.message.addVisibilityCheck( function( id ) {
    var lExpander$ = $( "#" + id ).closest( ".t-Expander" );

    // Check if parent element of the element passed is an 'expander' region
    if ( lExpander$.hasClass( "t-Expander" ) ) {

        // If so, expander region must show its contents
        lExpander$.expander( "expand" );
    }
});

(static) alert(pMessage, pCallback)

Displays an alert dialog with the given message and OK button. The callback function passed as the pCallback parameter is called when the dialog is closed. The dialog displays using the jQuery UI ‘Dialog’ widget. There are some differences between this function and a browser’s built-in alert function: - The dialog style will be consistent with the rest of the app. - The dialog can be moved. - The call to apex.message.alert does not block. Any code defined following the call to apex.message.alert will run before the user presses OK. Therefore code to run after the user closes the dialog must be done from within the callback, as shown in the example. Note: If either of the following 2 pre-requisites are not met, the function falls back to using the browser’s built-in confirm:
- jQuery UI dialog widget code must be loaded on the page. - The browser must be running in ‘Standards’ mode. This is because if it is running in ‘Quirks’ mode (as is the case with some older themes), this can cause issues with display position, where the dialog positions itself in the vertical center of the page, rather than the center of the visible viewport.
Parameters:
Name Type Description
pMessage String The message to display in the alert dialog
pCallback function Callback function called when dialog is closed.
Example
// Displays an alert ‘Load complete.’, then after the dialog closes executes the ‘afterLoad()’ function.
apex.message.alert( "Load complete.", function(){
    afterLoad();
});

(static) clearErrors()

This function clears all the errors currently displayed on the page.
Example

The following example demonstrates clearing all the errors currently displayed on the page.

apex.message.clearErrors();

(static) confirm(pMessage, pCallback)

Displays a confirmation dialog with the given message and OK and Cancel buttons. The callback function passed as the pCallback parameter is called when the dialog is closed, and passes true if OK was pressed and false otherwise. The dialog displays using the jQuery UI ‘Dialog’ widget. There are some differences between this function and a browser’s built-in confirm function: - The dialog style will be consistent with the rest of the app. - The dialog can be moved. - The call to apex.message.confirm does not block, and does not return true or false. Any code defined following the call to apex.message.confirm will run before the user presses OK or Cancel. Therefore acting on the user’s choice must be done from within the callback, as shown in the example. Note: If either of the following 2 pre-requisites are not met, the function falls back to using the browser’s built-in confirm:
- jQuery UI dialog widget code must be loaded on the page. - The browser must be running in ‘Standards’ mode. This is because if it is running in ‘Quirks’ mode (as is the case with some older themes), this can cause issues with display position, where the dialog positions itself in the vertical center of the page, rather than the center of the visible viewport.
Parameters:
Name Type Description
pMessage string The message to display in the confirmation dialog
pCallback function Callback function called when dialog is closed. Function passes the following parameter: - okPressed: True if OK was pressed, False otherwise (if Cancel pressed, or the dialog was closed by some other means).
Example
// Displays a confirmation message ‘Are you sure?’, and if OK is pressed executes the ‘deleteIt()’ function.
apex.message.confirm( "Are you sure?", function( okPressed ) {
    if( okPressed ) {
        deleteIt();
    }
});

(static) hidePageSuccess()

Hides the page-level success message. Tip: As a theme developer, you can influence or override what happens when hiding a page-level success message. For more information, please refer to the apex.message.setThemeHooks function (specifically the beforeHide callback function, where you would need to check for ‘pMsgType === apex.message.TYPE.SUCCESS’ to isolate when hiding a page-level success message).
Example
// Hides the page-level success message.
apex.message.hidePageSuccess();

(static) setThemeHooks(pOptions)

Allows a theme to influence some behavior offered by the apex.message API. Call this function from theme page initialization code.
Parameters:
Name Type Description
pOptions Object An object that contains the following properties:
Properties
Name Type Description
beforeShow function Callback function that will be called prior to the default show page notification functionality. Optionally return false from the callback to completely override default show functionality.
 Callback passes the following parameters:
  • pMsgType: Identifies the message type. Use apex.message.TYPE to identify whether showing an error or success message.
  • pElement$: jQuery object containing the element being shown.
beforeHide function Callback function that will be called prior to the default hide page notification functionality. Optionally return false from the callback to completely override default hide functionality. 
Callback passes the following parameters:
  • pMsgType: Identifies the message type. Use apex.message.TYPE to identify whether showing an error or success message.
  • pElement$: jQuery object containing the element being hidden.
closeNotificationSelector string jQuery selector to identify the close buttons in notifications, defaults to that used by Universal Theme (“button.t-Button—closeAlert”). May be required by custom themes if you still want to have APEX handle the hide logic, and where messaging contains a close notification button with a different class.
Example

The following example shows beforeShow and beforeHide callbacks defined, that add and remove an additional class ‘animate-msg’ on the notification element, before the default show and hide logic. This will only happen for success messages because of the check on pMsgType.
Note: The callbacks do not return anything, therefore the default show / hide behavior will happen after the callback.

apex.message.setThemeHooks({
    beforeShow: function( pMsgType, pElement$ ){
        if ( pMsgType === apex.message.TYPE.SUCCESS ) {
            pElement$.addClass( "animate-msg" );
        }
    },
    beforeHide: function( pMsgType, pElement$ ){
        if ( pMsgType === apex.message.TYPE.SUCCESS ) {
            pElement$.removeClass( "animate-msg" );
        }
    }
});

(static) showErrors(pErrors)

This function displays all errors on the apex.message error stack. If you do not want to add to the stack, you must first call clearErrors(). Errors will display using the current app’s theme’s templates. For page level messages (where location = “page”), error messages use markup from the page template’s ‘Subtemplate > Notification’ attribute. For item level messages (where location = “inline”), error messages use markup from the item’s label template’s ‘Error Display > Error Template’ attribute.

Note Theme Developers should bear in mind the following:

  • To display errors for a theme correctly, it must define both of the template attributes described above. In addition, for inline errors the label template must reference the #ERROR_TEMPLATE# substitution string in either the ‘Before Item’ or ‘After Item’ attributes of your label templates.
  • As a theme developer, you can influence or override what happens when showing page level errors. For more information, please refer to apex.message.setThemeHooks, (specifically the beforeShow callback function, where you would need to check for ‘pMsgType === apex.message.TYPE.ERROR’ to isolate when showing page level errors).

Parameters:
Name Type Description
pErrors Object | Array.<Object> An object, or array of objects with the following properties:
Properties
Name Type Attributes Default Description
type string Must pass “error”, although may support different notification types in the future.
location string | Array.<string> Possible values are: “inline”, “page” or [ “inline”, “page” ].
pageItem string Item reference where an ‘inline’ error should display. Required when location = “inline”.
message string The error message.
unsafe boolean <optional>
 true Pass true so that the message will be escaped by showErrors. Pass false if the message is already escaped and does not need to be escaped by showErrors.
Example

In this example, we have 2 new errors to display. We do not want to add to any existing errors that may be displayed, so we first clear any errors. Because we are displaying 2 errors, we pass an array containing 2 error objects. The first error states ‘Name is required!’, and will display at both ‘page’ level, and ‘inline’ with the item ‘P1_ENAME’. The message text is considered safe and therefore will not be escaped. The second error states ‘Page error has occurred!’, and will just display at page level, and the message text is considered safe and therefore will not be escaped.

// First clear the errors
apex.message.clearErrors();

// Now show new errors
apex.message.showErrors([
    {
        type:       "error",
        location:   [ "page", "inline" ],
        pageItem:   "P1_ENAME",
        message:    "Name is required!",
        unsafe:     false
    },
    {
        type:       "error",
        location:   "page",
        message:    "Page error has occurred!",
        unsafe:     false
    }
]);

(static) showPageSuccess(pMessage)

Displays a page-level success message. This will clear any previous success messages displayed, and also assumes there are no errors, so will clear any errors previously displayed. Success messages will display using the current app’s theme’s template. Specifically for page success messages, the markup from the page template’s ‘Subtemplate > Success Message’ attribute will be used. Tip: As a theme developer, you can influence or override what happens when showing a page-level success message. For more information, please refer to the apex.message.setThemeHooks function (specifically the beforeShow callback function, where you would need to check for ‘pMsgType === apex.message.TYPE.SUCCESS’ to isolate when showing a page-level success message). Tip: As a theme developer, you can influence or override what happens when showing a page-level success message. For more information, please refer to the apex.message.setThemeHooks function (specifically the beforeShow callback function, where you would need to check for ‘pMsgType === apex.message.TYPE.SUCCESS’ to isolate when showing a page-level success message).
Parameters:
Name Type Description
pMessage String The success message to display.
Example
// Displays a page-level success message ‘Changes saved!’.
apex.message.showPageSuccess( "Changes saved!" );