Skip to Main Content

Namespace: region

QuickNav

apex.region

The apex.region namespace contains global functions related to Oracle Application Express regions. The apex.region function provides access to a region interface for a specific region.

Since:
  • 5.1

Functions

(static) create(pRegionId, pRegionImpl)

This function is only used by region plug-in developers. It provides a plug-in specific implementation for the region.

Use this function to give a region plug-in a set of behaviors defined by pRegionImpl. The pRegionImpl parameter can provide its own implementation for standard methods (such as refresh, focus, widget) or omit them to get the default implementation. It can add its own methods as well. It should include a type string property that specifies the type of region. If the region is implemented with a jQuery UI style widget (using widget factory) then it should provide an implementation for the region#widget method and define the region#widgetName property so that the region#call method works.

Parameters:
Name Type Description
pRegionId string Region id or region static id. It is a best practice to give a region a Static ID if it is going to be used from JavaScript otherwise an internally generated id is used. The region id is substituted in the region template using the #REGION_STATIC_ID# string. The region id can be found by viewing the page source in the browser.
pRegionImpl Object An object that provides the methods and properties for the region interface. It should provide a string type property. It can provide any additional methods that would be useful to developers. A default implementation is provided for any standard methods or properties omitted. See region for the properties and methods supported by the interface.
Example

The following is region initialization code for a hypothetical region plug-in:

function initFancyList( pRegionId, ... ) {
    ...
    apex.region.create( pRegionId, {
        type: "FancyList",
        focus: function() {
            // code to focus region
        },
        refresh: function() {
            // code to refresh region
        }
    });
}

(static) destroy(pRegionId)

This function is only for region plug-in developers. It will destroy and remove the behaviors associated with a region element. It does not remove the region element from the DOM. It is not necessary to call this function if the region will exist for the lifetime of the page. If the region is implemented by a widget that has a destroy method then this function can be called when the widget is destroyed.

Parameters:
Name Type Description
pRegionId string Region id or region static id. It is a best practice to give a region a Static ID if it is going to be used from JavaScript otherwise an internally generated id is used. The region id is substituted in the region template using the #REGION_STATIC_ID# string. The region id can be found by viewing the page source in the browser.
Example

The following destroys the region interface but the region element remains on the page.

apex.region.destroy( someRegionId );

(static) findClosest(pTarget) → {region|null}

Returns the region that contains the pTarget element. Returns null if there is no pTarget element or if it is not in a region that has been initialized with a call to apex.region.create.

Parameters:
Name Type Description
pTarget Element | string A DOM element or CSS selector suitable as the first argument to the jQuery function.
Returns:
A region interface or null if the element corresponding to pTarget is not inside a region.
Type
region | null
Example

The following will refresh the region that contains a button with class refresh-button when it is clicked.

apex.jQuery( ".refresh-button" ).click( function( event ) {
    var region = apex.region.findClosest( event.target );
    if ( region ) {
        region.refresh();
    }
});

(static) isRegion(pRegionId) → {boolean}

This function returns true if and only if there is a DOM element with id equal to pRegionId that has had a region interface created for it with apex.region.create.

To support older regions that don't implement a region interface (by calling apex.region.create) the default implementation of apex.region will attempt to treat any DOM element with an id as if it were an Application Express region. This function allows you to distinguish true Application Express regions from arbitrary DOM elements.

Parameters:
Name Type Description
pRegionId string Region id or region static id. It is a best practice to give a region a Static ID if it is going to be used from JavaScript otherwise an internally generated id is used. The region id is substituted in the region template using the #REGION_STATIC_ID# string. The region id can be found by viewing the page source in the browser.
Returns:
true if there is an element with the given id that supports the region interface.
Type
boolean
Example

The following will only focus the region if it is an Application Express region.

if ( apex.region.isRegion( someId ) ) {
    apex.region( someId ).focus();
}