The apex.message namespace is used to handle client-side display and management of messages in Oracle Application Express.
Message type constants
Type:
Properties:
Name |
Type |
Description |
SUCCESS |
string
|
Success message Value "success". |
ERROR |
string
|
Error message Value "error". |
(static) addVisibilityCheck(pFunction)
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 |
pFunction |
function
|
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();
});
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!" );