Monday, December 19, 2016

Handling client-side messages in APEX 5.1

You may noticed that in APEX 5.1 there's new JS namespace apex.message that is used to handle client-side messages.

Unfortunately, there's no documentation for it yet so I'll try to make a quick introduction to some features that you can use.

Edit (12/2017) : The apex.message documentation is available here.

Important notice: all examples are made in APEX 5.1.0.00.43 which is currently only available on apex.oracle.com. Some features may change in production version.

Most important features/function in new JS library that you can use are:
  • apex.message.showPageSuccess - function to dynamically display standard APEX success message,
  • apex.message.hidePageSuccess - function that enables you to hide page success message
  • apex.message.showErrors - function to display page or inline error messages
  • apex.message.alert - function to call new APEX alert dialog
  • apex.message.confirm - function to call new APEX confirm dialog

Examples of how to the functions from above are available here.

Be careful when you use apex.message.alert or apex.message.confirm because they are a bit different than build-in browser functions alert() and confirm(). They don't block JS execution so you have to put code following the call into the callback function. For example, if we use following code:

apex.debug.log('Before APEX alert');
apex.message.alert('My Alert Message'
                 , function(){
                     apex.debug.log("You've pressed ok! ");
                   }
);
apex.debug.log('After APEX alert');

the output in JS console (before we click Ok button on alert dialog) will look like this:


And after you press Ok button it will look like this:

So, as you may see, JS code following the apex.message.alert call will execute before we even press Ok button (unlike calling browser's alert() function).

There are some additional advanced features available in new JS library like registering your own templates by calling apex.message.registerTemplates. You can also define custom hooks on some message events like beforeShow or beforeHide (see apex.message.setThemeHooks).

Go, explore and enjoy!