Showing the Processing Icon/Mask on a Region instead of the Page

In some cases you may not want to show the processing icon (optionally with the mask) in the center of the page but rather a particular region the execution of PL/SQL code belongs to. This allows the user to interact with the page when you apply the mask overlay setting, except for interacting with the region being masked. In this case we can use the "Affected Element" of the dynamic action to control what element the icon/mask is applied to e.g.

Override the Success Message

In some cases you may want to override the success message being returned. You can easily do this by updating the following variable in your code e.g.

apex_application.g_x01 := 'My New Success Message!!';

Override the Success Message including a Title

In some cases you may want to override the success message being returned. You can easily do this by updating the following variable in your code e.g.

apex_application.g_x01 := 'My New Success Message!!';
apex_application.g_x02 := 'Success';

Override the Notification Type

In some cases you may want to override the success message being returned and also change the notification type. You can easily do this by updating the following variable in your code e.g.

apex_application.g_x01 := 'My new task completion message!!'; -- message
apex_application.g_x02 := 'Task Complete';                    -- (optional) title
apex_application.g_x03 := 'info';                             -- type [success|warning|info|error]

Or if you wanted to handle our own exceptions you could do something like this:

begin
    -- do something here first
    apex_util.pause(1); -- pause for demo purposes only
    
    -- raising a dummy exception for example purposes
    raise_application_error(-20001, 'Something went wrong');
exception
    when others then
        -- override the UC Notification
        apex_application.g_x01 := 'We just ran into a big problem!!'; -- message
        apex_application.g_x02 := 'Error'; -- title
        apex_application.g_x03 := 'error'; -- type
        rollback;
end;

Cancel Following Actions

In some cases you may want to stop further actions from continuing if you performed your own error handling. This can be achieved by setting the following APEX global variable in your code e.g.

apex_application.g_x04 := 'cancel'; -- stop/cancel following actions

Fire a Custom Event

In some cases when you run into an error you may want to perform some other dynamic action when this occurs. This can be achieved by setting the following APEX global variable in your code e.g.

apex_application.g_x05 := 'plsql-exception-20001'; -- fire custom event on the "body" tag

Putting these two features together will look something like this:

begin
    -- do something here first
    apex_util.pause(1); -- pause for demo purposes only

    -- raising a dummy exception for example purposes
    raise_application_error(-20001, 'Something went wrong');
exception
    when others then
        -- override the UC Notification
        apex_application.g_x01 := 'We just ran into a big problem!!';
        apex_application.g_x02 := 'Error';
        apex_application.g_x03 := 'error';
        apex_application.g_x04 := 'cancel'; -- stop/cancel following actions
        apex_application.g_x05 := 'plsql-exception-20001'; -- fire custom event on the "body" tag
        rollback; -- recommended since an expcetion has occurred
end;

Commit/Rollback/Raise

When you provide your own exception handler, you have the option of manually rolling back yourself and have control over the behavior of what happens next, as per the above demo.

If you don't rollback or re-raise the exception, any changes made before the exception will be committed as the APEX engine performs an implicit commit for you in every AJAX call. Alternatively, if you do issue a "raise;" statement, any changes will be implicitly rolled back for you, the notification type will be set to "error", and any following actions will be canceled e.g.

exception
    when others then
        -- Override the Notification
        apex_application.g_x01 := 'We just ran into a big problem!!';
        raise;
end;

Setting Popup LOV Display Values

Popup LOV Display Values can be set easily by using the DA's "Page Items to Return" where only the return value needs to be passed and the plug-in figures out the display value automatically.

Getting & Returning your CLOB directly into a Javascript Function

From v21.1 onwards you can now (optionally) get your CLOB value directly from a Javascript Function and (optionally) return the JSON result directly into a Javascript Function defined in the "Initialization Javascript Code". We are expecting two functions to be named "submitClob" and "clobCallback" e.g.

function(options) {
    var itemName = "P1020_MESSAGE";
    options.submitClob = function() {
        return JSON.stringify({
            message: $v(itemName)
        });
    };
    options.clobCallback = function(data) {
        apex.message.showPageSuccess(data.message);
    };
    return options;
}

Both buttons run the plug-in with Success Message and Error Message left empty. The toasts come from UC - Notifications, bound to the plug-in events and scoped to this region.

• Success - one toast, yours. The plug-in has no message unless you give it one.
• Error - two toasts. The plug-in always reports a failure itself, falling back to SQLERRM.

For a single toast in both cases, tick Report Through Events Only - next example.

Available Actions JSON

These extra instructions can be added by defining a JSON result with the any of the following attributes:

{
   "cancelActions": true,
   "clearErrors": true,
   "notification": {"type":"success", "message": "We just did what you wanted, yay!", "title": "Success"},
   "addClass": [{
      "selector": "#P1_ITEM1",
      "class": "some-class"
    },{
      "selector": ".t-Region",
      "class": "some-other-class"
   }],
   "removeClass": [{
      "selector": "#IG_REPORT1",
      "class": "some-class"
    },{
      "selector": ".t-Region",
      "class": "some-other-class"
   }],
   "itemErrors": [{
      "name": P1_ITEM1",
      "message": "Example error message",
      "position": ["inline","page"]
    },{
      "name": P1_ITEM2",
      "message": "Example error message",
      "position": ["inline","page"]
   }],
   "hideButtons": ["BUTTON1","BUTTON2"],
   "showButtons": ["BUTTON3","BUTTON4"],
   "enableButtons": ["BUTTON5","BUTTON6"],
   "disableButtons": ["BUTTON7","BUTTON8"],
   "hideItems": ["P1_ITEM1","P1_ITEM2"],
   "showItems": ["P1_ITEM3","P1_ITEM4"],
   "enableItems": ["P1_ITEM1","P1_ITEM2"],
   "disableItems": ["P1_ITEM3","P1_ITEM3"],
   "hideRegions": ["IG_REPORT1","FORM1"],
   "showRegions": ["IG_REPORT2","FORM2"],
   "setValues": [{
      "name": "P1_ITEM1",
      "value": "New Value",
      "suppressChangeEvent": false
   }],
   "setFocusItem": "P1_ITEM3",
   "refreshItems": ["P1_LOV1","P1_LOV2"],
   "refreshRegions": ["IG_REPORT1","CLASSIC_REPORT2"],
   "fireEvents": [{
      "selector": "body",
      "name": "my-custom-event1",
      "data": {}
   }, {
      "selector": "#IG_REPORT1",
      "name": "my-custom-event2",
      "data": {}
   }]
}

Hiding/Showing Actions

Lets have a look at hiding and showing regions, items, and buttons, which is a common task in many situations.

Setting Popup LOV Display Values

Popup LOV Display Values can be set in different ways: either using the extra instructions JSON and returning both the display and return value, or by using the DA's "Page Items to Return" where only the return value needs to be passed and the plug-in figures out the display value automatically.