Namespace: message

Message type constants

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.

// 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" );
    }
});

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.

// Displays an alert 'Load complete.', then after the dialog closes executes the 'afterLoad()' function.
apex.message.alert( "Load complete.", function(){
    afterLoad();
});

// Displays an alert 'Load complete.' with extra options
apex.message.alert( "Load complete.", function() {
    afterLoad();
}, {
    title: "Update",
    style: "information",
    iconClasses: "fa fa-info fa-2x",
    okLabel: "Okay"
} );

Emits ARIA live assertive alert message for screen reader users. No visual changes rendered.

Use this function when meaningful dynamic changes to the UI are made that may not be perceivable to users of assistive technologies. It is best to keep the messages short and relevant. See also apex.message.ariaMessage.

When this function is called, assistive technologies will immediately notify the user, and could potentially clear the speech queue of previous updates emitted by apex.message.ariaMessage and apex.message.ariaAlertMessage.

apex.message.ariaAlertMessage( "Load complete" );

Emits ARIA live polite message for screen reader users. No visual changes rendered.

Use this function when meaningful dynamic changes to the UI are made that may not be perceivable to users of assistive technologies. It is best to keep the messages short and relevant. See also apex.message.ariaAlertMessage.

When this function is called, assistive technologies will notify users of updates but generally do not interrupt the current task (such as speech), and updates take low priority.

apex.message.ariaMessage( "Loading" );

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

apex.message.clearErrors();

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.

// Displays a confirmation message 'Are you sure?'
// If OK is pressed executes the 'deleteIt()' function
apex.message.confirm( "Are you sure?", function( okPressed ) {
    if( okPressed ) {
        deleteIt();
    }
} );

// Displays a confirmation dialog with extra options
apex.message.confirm( "Are you sure you wish to delete this record?", function( okPressed ) {
    if( okPressed ) {
        deleteIt();
    }
}, {
    title: "Warning!",
    style: "danger",
    iconClasses: "fa fa-trash fa-2x",
    cancelLabel: "No",
    confirmLabel: "I'm sure"
} );

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).

// Hides the page-level success message.
apex.message.hidePageSuccess();

Allows the theme or app to influence the auto-dismiss behavior of application success messages. Call this function from page initialization code in the Function and Global Variable Declaration property or in a JavaScript file in the application. If no dismiss preferences have been set using setDismissPreferences but the application auto-dismiss setting is turned on, success messages will follow the default application setting.

Note that it is important to take into consideration the accessibility impact auto-dismiss could have on users who may use special technology to view their screen or need longer than the default 5 seconds to perceive the message. Those users may not see or read a success message before it is dismissed from the page, and therefore could potentially miss the information in the message. Consider providing users with preference settings that use the dismissPageSuccess and dismissPageSuccessDuration properties of setDismissPreferences, to be able to opt out of the auto-dismiss functionality, and/or have control over dismiss duration.

apex.message.setDismissPreferences( {
    dismissPageSuccess: true,
    dismissPageSuccessDuration: 10000  // 10 second duration
} );

Allows a theme to influence some behavior offered by the apex.message API. Call this function from theme page initialization code.

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" );
        }
    }
});

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. A side effect of calling this function is that if there are page level errors, APEX will focus the errors container, please refer to apex.message.setThemeHooks (specifically property pageErrorsContainerSelector), and if only displaying inline errors it will try to focus the first inline error on the page following the display order.

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).

// 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
    }
] );

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).

// Displays a page-level success message 'Changes saved!'.
apex.message.showPageSuccess( "Changes saved!" );