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