apex.region and apex.widget: Controlling APEX Components From JavaScript

The Region API

Every APEX region with a Static ID is accessible through apex.region(). This API provides methods common to all regions: refresh, focus, and widget access.

Refreshing Regions

// Refresh a report, chart, or any region
apex.region("orderReport").refresh();

// Refresh with callback
apex.region("orderReport").refresh();
// Listen for the After Refresh event instead:
apex.region("orderReport").element.on("apexafterrefresh", function() {
    console.log("Report refreshed with new data");
});

Getting the Widget Reference

// Interactive Grid
var ig = apex.region("myGrid").widget().interactiveGrid("instance");
var grid = apex.region("myGrid").widget().interactiveGrid("getViews","grid");
var model = grid.model;

// Interactive Report
var ir = apex.region("myIR").widget().interactiveReport("instance");

Checking If a Region Is Visible

// Useful before refreshing or manipulating
var regionEl = apex.region("myRegion").element;
if (regionEl.is(":visible")) {
    apex.region("myRegion").refresh();
}

Working With Tab Containers

// Switch to a specific tab programmatically
apex.region("myTabs").widget().aTabs("getTabs")[1].makeActive();

// Listen for tab change
apex.region("myTabs").element.on("atabsactivate", function(e, ui) {
    var activeTabId = ui.active.el$.attr("id");
    // Lazy-load content when tab becomes active
    if (activeTabId === "SR_tab2") {
        apex.region("expensiveReport").refresh();
    }
});

Region Element Access

// Direct jQuery access to the region's DOM element
var $region = apex.region("myRegion").element;
$region.addClass("highlight-region");
$region.find(".t-Report-cell").css("font-size", "12px");

// Hide/show with animation
$region.slideUp(300);
$region.slideDown(300);

Important: Static ID Required

The apex.region() API requires the region to have a Static ID set in the Page Designer. Without it, the region is not registered in the client-side region registry and cannot be accessed by name. Always set Static IDs on regions you plan to manipulate with JavaScript.