Javascript API (#4 Message namespace)

Hello everyone and welcome again here in our Blog. In this post, we will show you how to use the message namespace, and as always, with a practical example.

The message namespace is one of the native apex namespaces provided to you. This namespace is used to handle client-side display and management of messages, such as error and success messages. 

When to use the message namespace?

you use this namespace when you want to show some messages to the users. A very common use-case is validation, for example, you have a required text field and you want to alert the user if he leaves it empty, or if the text field must be in Email format. You can also use the namespace to show a success message after a user successfully complete a process. These are some use-cases where you can benefit from the message namespace.

Message types

The namespace has two message types, ERROR, and SUCCESS. You can use the property TYPE to specify the type of message you want as we will see later in this post. 

Functions

The namespace provides some functions that you can use to perform some tasks. Below we will take a look at some of these functions.

alert()

The first function we will talk about is alert(), which is used to display the alert dialog with a message passed as a parameter and an Ok button, you can also provide a callback function that will be fired after the user responds to this alert. The dialog displays using the jQuery UI ‘Dialog’ widget and there are some differences between this function and a browser’s built-in alert function:

• The dialog style is 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.

Now let's have an example, go to our Demo app or create a new application if you don't already have one, navigate to the first page and create a new region with a button and let's name the button "show alert", now add a dynamic action to that button and set the true action to Javascript (please note that there is already an alert action provided to you, but in this series, we are the Javascript APIs) add the following code and run the application

apex.message.alert("some alert text", ()=>{

console.log("This runs after the dialog is closed");

});

Once the user clicks the show alert button, the dialog shows up with the message and an ok button. The user has to press the ok button to close the dialog, once he has done that, the callback function will be executed.

confirm()

Similar to the alert function, but here, the dialog has a cancel button beside the ok button. In this function, the callback function accepts a parameter that tells you whether the user pressed the Ok button or the cancel button, so you can perform different actions depending on the user input. This is useful when you want to warn the user before deleting something for example. 

Go back to the demo app, add a new button "Show Confirm", add a dynamic action to the button and add a true action that runs the following code

apex.message.confirm("some text", (okPressed)=>{

if (okPressed)

console.log("The user pressed the ok Button");

else

console.log("The user pressed the Cancel Button");

});

Run the application and open the console to see the output. 

showPageSuccess()

You can use this function to show the user a success message with a specific message, for example, when a user successfully filled out a form or to show that a transaction was successfully saved. 

Go to the demo app, add a new button "ShowSuccessMessage", add a dynamic action and change the true action to execute Javascript code then add the following code

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

Run the application and try it! 

hidePageSuccess()

As the name suggests, this function hides the page success notification. After you display a success message, it won't disappear until you hide it, one way to do that is using this function. 

Go back to the previously created dynamic action that shows the success message and change the code to the following

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

setTimeout(()=>{

apex.message.hidePageSuccess();

}, 1000);

This will set a timeout and the hide-message will be executed 1 second after it is displayed.

clearErrors()

This function clears any errors currently displayed on the page, we will use this function later in this post when we talk about showErrors() function

showErrors()

This function is used to display error messages to the user, when they enter a wrong value in an input text item or when something went wrong while saving a form. You can show the error message on a page level which means all error messages will be shown on the right corner of the page and the style will be inherited from the page notification template, or you can show the error message next to the item where the error occurred, in this case, the style will be driven from the item label template.  You don't need to worry about the style and the markup, you just have to specify the location where the notification will be displayed. The function accepts an object or an array of objects, in each object you can specify the message attributes e.g. location, message text, and so on. 

Go to the demo app, add a text item, give it the name "P1_ERROR_MESSAGE" and a button "ShowError"

Then add a dynamic action to the button, change the true action to execute Javascript code, and write the following code

apex.message.clearErrors();

apex.message.showErrors([

{

type: "error",

location: [ "page", "inline" ],

pageItem: "P1_ERROR_MESSAGE",

message: "Name is required!",

unsafe: false

},

{

type: "error",

location: "page",

message: "Page error has occurred!",

unsafe: false

}

]);

The first line in the code clears the error stack, in case the user had previous errors and, the second line adds two errors to the error stack and shows them. 

The first error in the array is an object, the type of the notification is an error and in the location attribute we want to show the error message on the page level and also next to the item, so in the pageItem attribute we should tell which page item is associated with this error message, the next attribute is the message we want to show and finally, the last attribute tells the function whether to escape the message text or not, in this case, the message text is considered as a safe message so it won't be escaped. 

the next error object is a page-level error and therefore we don't need to specify a page item. 

Run the application and you should see something like this

setThemeHooks()

If you want to change the default behavior of the notification messages or if you want to override the style then you need to use this function. It allows you to run a specific code before the show page notification functionality, and also before the hiding page notification functionality. Let's say for example you want the success messages to disappear 3 seconds after displaying, but if the message type is an error then you don't want it to disappear automatically. 

Go to our page where all items are and in the "Execute when page loads" write the following code (It is better to add this code in template initialization code, but for this demo is ok)

apex.message.setThemeHooks({

beforeShow: function( pMsgType, pElement$ ){

if ( pMsgType === apex.message.TYPE.SUCCESS ) {

setTimeout(function() {

$('.t-Alert').fadeOut('slow');

}, 2000);

}

},

beforeHide: function( pMsgType, pElement$ ){

console.log("This is before hide!");

}

});

The pMsgType parameter identifies the message type (as we said before, there are two types Error and Success), and the pElement$ parameter is the JQuery object that contains the element to being shown (the notification element, in our case, would be an HTML span element).

Go to the show success dynamic action and comment the code that hides the success message

Run the application and try it (you need to open the console to see the beforeHide message). 

So that's it in this post, we hope that you learned something :).

Demo

References:

• https://docs.oracle.com/en/database/oracle/application-express/21.2/aexjs/apex.message.html