Pretius APEX Enhanced Notifications

Oracle APEX dynamic action plugin

The plugin is dynamic action plugin providing notifications for Oracle APEX 5 and Universal Theme. Due to highly configurable attributes, the plugin can be used as presentation layer for AJAX callbacks. Translated messages from the database can be easly presented in two types of notification.

License

This plugin is currently available for use in all personal or commercial projects under MIT license. License has been included with this software.

Legal Disclaimer

The program(s) and/or file(s) are supplied as is. The author disclaims all warranties, expressed or implied, including, without limitation, the warranties of merchantability and of fitness for any purpose. The author takes no responsibility, assumes no liability for damages, direct or consequential, which may result from the use of these program(s) and/or file(s).

Documentation

Detailed documentation, usage guide, roadmap ang version changelog is available at Pretius GitHub repository.

Live demo

Demo presents possible configurations of the plugin with additional explaination.

Floating

Appearance

Supported positions

Single-line message with list

Inline

Inline notifications demo is based on default Universal Theme page template. APEX page implementing the plugin is embeded within the iframe.

Message source

This section describes possible notification message sources (static message / javascript based message). Read this section to understand the plugin flexibility.

Static text

Simpliest way to show notification. Provided Static string is displayed as notification message.

Function returning string

When using this option, attribute JavaScript function body must return string or number.

Example

var stringMessage = 'Function returning string';
return stringMessage;
or any JavaScript variable (String or Number) can be returned from function body: 
var location = window.location.href;
return location;

Function returning JSON

When using this option, attribute JavaScript function body must return JSON object with two attributes:
  • msg (String or Number)
  • list (Array of Strings)

Example

return {
  msg: "Function returning JSON",
  list: [
    "Message #1",
    "Message #2",
    "..."
  ]
}

Function returning string or JSON

This options combines functionalities of Function returning string and Function returning JSON. Attribute JavaScript function body must return JSON object or String/Number.
Use this option if you are not sure whether the message will be string or JSON object.

Dialog close event

To catch success message on dialog close event, the plugin has to be:
  • bound to Dialog close event.
  • attribute Message type set to Dialog page close message

Alternative

dialog close event provides returned message and APEX items using event data JSON object. It can be used to show notification when the plugin Message type is set to Funtion returning string or JSON. For example set the plugin Javascript function body to: 
return this.data.successMessage.text;
this.data refers event data object. You can inspect dialog close event data by using TRUE action Execute JavaScript code: 
console.log( this.data );

Notifications on custom event

The plugin can be bound with custom event and triggered from javascript: 
apex.event.trigger(pSelector,pEvent,pData);
To learn more about apex.event namespace read Oracle APEX documentation.

Example

When Message type is set to Function returning JSON and Javascript function body defined as 
return this.data;
triggering the plugin might look like: 
var pSelector = document, 
    pEvent = 'successFloatRight', 
    pData = {msg: "Custom event", list: ["line 1", "line 2", "..."]};

apex.event.trigger(pSelector,pEvent,pData);
This method can be used in AJAX callbacks to show Successs/Warning/Error message from DB.

Configuration error handling

If the plugin attributes are not configured correctly, the plugin raise error as floating notification. Read this section to understand configuration mistakes that lead to plugin crash.

jQuery selector provided in "Insert into" attribute does not exists.

This error is raised when Insert into attribute refers non-existing DOM object.

For example Insert into set to #non-ExistingId raise the error.

Function returning message contains JavaScript errors: [Syntax error message]

This error is raised when attribute JavaScript function body contains JavaScript syntax error.

For example JavaScript function body is defined as: 
return "Notification message"+;
The plugin raise error because "+" character should not be used in this context.

Function returning message returned invalid JSON object.

This error is raised when attribute Message type is set to Function returning JSON and attribute JavaScript function body returned invalid JSON object.

For example JavaScript function body is defined as: 
  return {
    text: '',
    list: [
      "Line 1", 
      "Line 2", 
      "..."
    ]
  };
The plugin expects JSON object with two attributes (msg and list) but got only one valid attribute. text attribute is unrecognized by the plugin and the error is raised.

Function returning message returned not supported JS object.

This error is raised when Message type is set to Function returning string or JSON and value returned from JavaScript function body attribute returned unrecognized value.

For example JavaScript function body is defined as: 
return this.data;
and the notification is triggered by custom event 
apex.event.trigger(document, 'showNotification', returnObject);
but returnObject is undefined.

Download

Please click on the button below

 

About the author

Bartosz Ostrowski
Bartosz Ostrowski

Oracle Application Express, PL/SQL and Frontend developer. IT consultant experienced in developing database and web applications using Oracle Application Express.
Oracle APEX enthusiast, plugin developer and active community member.

release 1.0 Set Screen Reader Mode On
Copyright © 2006-2017 Pretius