31.7 apex.message namespace

This function is for APEX region plug-in developers. 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.

Syntax

apex.message.addVisibilityCheck( pFunction )

Parameters

Example

The following example explains 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 a 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 lExpander$ is an 'expander' region
    if ( lExpander$.hasClass( "t-Expander" ) ) {

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

This function 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 application.

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

Syntax

apex.message.alert( pMessage, pCallback )

Parameters

Example

The following example displays an alert Load complete, then after the dialog closes executes the afterLoad() function.

This region should register a visibility check function as follows:

 apex.message.alert( "Load complete.", function(){
    afterLoad();
});

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

Syntax

apex.message.clearErrors()

Parameters

None

Example

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

 apex.message.clearErrors();

This function 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 is 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 alert function:

• The dialog style will be consistent with the rest of the application.

• The dialog can be moved.

• The call to apex.message.confirm does not block. 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.

Syntax

apex.message.confirm( pMessage, pCallback )

Parameters

Example

The following example displays a confirmation message Are you sure?, and if OK is pressed executes the deleteIt() function.

This region should register a visibility check function as follows:

apex.message.confirm( "Are you sure?", function( okPressed ) { 
    if( okPressed ) {
        deleteIt();
    }
});

This function hides the page-level success message.

Syntax

apex.message.hidePageSuccess()

Parameters

None

Example

The following example demonstrates hiding the page-level success message.

 apex.message.hidePageSuccess();

This function allows a theme to influence some behavior offered by the apex.message API. You can call this function from theme page initialization code.

Syntax

apex.message.setThemeHooks( pOptions )

Parameters

Example

The following example shows beforeShow and beforeHide callbacks defined. To add and remove an additional class animate-msg on the notification element, before the default show and hide logic. This will happen for success messages only by the quality of the check on pMsgType.

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

Syntax

apex.message.showErrors( pErrors )

Parameters

Examples

The following example first clears any existing errors displayed, and then displays two errors. To display the two errors, an array containing two error objects is passed to the showErrors call. The first error message is Name is required! and displays at both page level and inline with the item P1_ENAME. The second error messages is Page error has occurred! and displays just at page level. In both errors, 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
    }
]);

This function displays a page-level success message. This clears any previous success messages displayed, and also assumes there are no errors and clears any errors previously displayed. Success messages 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 is used.

Syntax

apex.message.showPageSuccess( pMessage )

Parameters

Example

The following example demonstrates a page-level success message Changes saved!.

 apex.message.showPageSuccess( "Changes saved!" );

The TYPE property is an object that contains properties (constants) that can be useful when calling some apex.message APIs. For example setThemeHooks.

Properties

Example

See apex.message.setThemeHooks for an example of how this can be used.