The apex.region API provides a single interface for all common region related functionality of Application Express. This API returns an Application Express region object, which is used to access region related functions and properties.
This API returns an Application Express region object for the given region id. The returned region object can then be used to access region related functions and properties.
Plug-in developers can define the behavior of their region by calling apex.region.create.
Parameters
Table 31-51 apex.region
| Name | Type | Description |
|---|---|---|
|
|
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 |
Returns
A region object is returned or null if there is no DOM element with an id equal to pRegionId. The region object has these properties and methods:
It may have additional properties or functions depending on the specific region. It is up to the region plug-in to document any additional properties or functions.
Example
This will not be used by itself, rather it is used to access item specific functions and properties, as documented in the following APIs.
See Also:
This region object function causes the Application Express region to take focus. Not all native or plug-in regions support taking focus. It is up to the specific region to determine where focus will go. The default behavior is to set focus to the first element in the region that is capable of being tabbed to. Some regions manage focus such that there is a single tab stop (or limited number of tab stops) and they may put focus to where the user last had focus within the region.
Parameters
None.
Example
The following example will focus the region with static id "myRegion".
var region = apex.region( "myRegion" ); region.focus();
This region object function refreshes the Application Express region. Typically this involves getting updated content or data from the server. Not all native or plug-in regions support refresh.
Note:
This function should be used in place of the legacy way of refreshing a region which was to trigger the apexrefresh event on the region element. For regions that still work this old way the default implementation of refresh will trigger the apexrefresh event.
Parameters
None.
Example
The following example will refresh the region with static id "myRegion".
var region = apex.region( "myRegion" ); region.refresh();
This region object function returns the widget associated with the Application Express region or null if the region isn't implemented with a widget. Some advanced region types such as Calendar, Interactive Grid, or Tree are implemented using a widget. This function provides access to the widget typically by returning a jQuery object for the widget element. You can then call widget methods on the jQuery object.
Parameters
None.
Example
The following example adds a row to an interactive grid by using the region widget function to access an interactiveGrid widget and then invoking the add-row action.
apex.region( "myGridRegion" ).widget().interactiveGrid( "getActions" ).invoke( "add-row" )
This function is only for region plug-in developers. It provides a plug-in specific implementation for the region.
Parameters
Table 31-52 apex.region.create
| Name | Type | Description |
|---|---|---|
|
|
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 |
|
|
Object |
An object that provides the functions and properties for the region. It should provide a string type property. It can provide any additional functions that would be useful to developers. A default implementation is provided for any standard functions or properties omitted. |
Example
The following is an example of what the region initialization code for a hypothetical region plug-in would do.
function initFancyList( pRegionId, … ) {
…
apex.region.create( pRegionId, {
type: "FancyList",
focus: function() {
/* code to focus region */
},
refresh: function() {
/* code to refresh region */
}
});
}
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
Table 31-53 apex.region.destroy
| Name | Type | Description |
|---|---|---|
|
|
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 |
Example
The following is an example of when the region is destroyed but the region element will remain on the page call:
apex.region.destroy( someRegionId );
This function returns true if and only if there is a DOM element with id equal to pRegionId that has had a region 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
Table 31-54 apex.region.isRegion
| Name | Type | Description |
|---|---|---|
|
|
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 |
Returns
true if pRegionId is the id of an Application Express region that implements the region interface and false otherwise.
Example
The following example will only focus the region if it is an Application Express region.
if ( apex.region.isRegion( someId ) ) {
apex.region( someId ).focus();
}
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
Table 31-55 apex.region.findClosest
| Name | Type | Description |
|---|---|---|
|
|
DOM Element | String |
A DOM element or CSS selector suitable as the first argument to the jQuery function. |
Returns
A region object is returned or null if the element corresponding to pTarget is not inside a region. See the return value of apex.region for details about the region object.
Example
The following example 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();
}
});