JSDoc: Namespace: region

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

Since:

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 or focus) or omit them to get the default implementation. It can add its own methods or properties 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. Note: jQuery UI is deprecated but the call method and widgetName property remain for backward compatibility.

Parameters:

Name	Type	Description
`pRegionId`	string	Region id or region HTML DOM id. This comes from the PL/SQL plug-in parameter `p_region.dom_id`.
`pRegionImpl`	object \| function	An object that provides the methods and properties for the region interface. All the properties of this object are copied to 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. This parameter can also be a function that is called during creation with a single object argument that is the base region interface. The function should add any needed functions or properties to the region interface.

Examples

The following is region initialization code for a hypothetical region plug-in. It provides implementations for the standard focus and refresh methods and adds a custom method to filter the list.

function initFancyList( pRegionId, ... ) {
    ...
    apex.region.create( pRegionId, {
        type: "FancyList",
        focus: function() {
            // code to focus region
        },
        refresh: function() {
            // code to refresh region, e.g:
            // const result = apex.server.plugin( ... );
            // result
            //   .done( ... )
            //   .fail( ... )
            //   .always( ... );
            // return result;
        },
        filter: function() {
            // code to filter the list
        }
    } );
}

// later the custom function can be used as follows
apex.region( regionId ).filter( ... );

The following example shows the same hypothetical region plug-in but using the function callback for pRegionImpl.

function initFancyList( pRegionId, ... ) {
    ...
    apex.region.create( pRegionId, function( baseRegion ) {
        baseRegion.type = "FancyList";
        baseRegion.focus = function() {
            // code to focus region
        };
        baseRegion.refresh = function() {
            // code to refresh region
        };
        baseRegion.filter = function() {
            // code to filter the list
        };
    } );
}

// later the custom function can be used as follows
apex.region( regionId ).filter( ... );

(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 DOM id. It is a best practice to give a region an HTML DOM id if it is going to be used from JavaScript otherwise an internally generated id is used. The region DOM id is substituted in the region template using the #DOM_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" ).on( "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 APEX region. This function allows you to distinguish true APEX regions from arbitrary DOM elements.

Parameters:

Name	Type	Description
`pRegionId`	string	Region id or region DOM id. It is a best practice to give a region a HTML DOM id if it is going to be used from JavaScript otherwise an internally generated id is used. The region DOM id is substituted in the region template using the #DOM_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 APEX region.

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

(static) multipleRefresh(pRegions, pOptionsopt) → {Promise}

Refresh multiple regions. Regions that support coalescing requests will be sent in a single ajax request using apex.server.process. Separate ajax requests will be sent for any others via calls to the region#refresh methods.

Parameters:

Name	Type	Attributes	Description
`pRegions`	Array.<string> \| Array.<region>		Array of region interfaces or region HTML DOM ids to refresh.
`pOptions`	object	<optional>	An options object passed to apex.server.process only for the single coalesced ajax request. It does not affect any ajax requests that may happen from calls to region#refresh methods. Because the coalesced ajax request is for multiple regions some of the options may not be applicable. The default is an option object with the `loadingIndicatorPosition` option set to "page". Also, if the `refreshObject` property is not set it will be automatically set to a jQuery collection of all the coalesced regions. This is so that each of the regions will receive the apex.event:apexbeforerefresh and apex.event:apexafterrefresh events if they support them.

Returns:

A promise that resolves when all ajax requests are complete. Any of the regions that do not return a promise from their region#refresh method will not be included in this completion promise.

Type: Promise

Examples

The following will refresh two chart regions with HTML DOM ids "chart1" and "chart2" using a single ajax request because the chart region supports coalescing refresh requests.

apex.region.multipleRefresh( ["chart1", "chart2"] );

This example is the same as the previous one except that it includes another region with HTML DOM id "other", which doesn't support coalescing requests, and shows how to run some code after all the ajax requests complete. This sends 2 ajax requests, 1 for region "other" and 1 for "chart1" and "chart2" combined.

apex.region.multipleRefresh( ["chart1", "chart2", "other"] ).then( () => {
     // put code here to run after all the requests have completed.
} );