Pre-General Availability: 2018-5-8

Interface: region

QuickNav

Properties

Methods

region

The region interface is used to access region related methods and properties. You get access to the region interface for a region with the apex.region function.

Plug-in developers can define the behavior of their region by calling apex.region.create.

Since:
  • 5.1

Properties

element :jQuery

The jQuery object for the region element.

Type:
  • jQuery

parentRegionId :string

Identifies the parent (master) region ID, if the region is the detail region of a master detail relationship.

Type:
  • string

type :string

Identifies the type of the region. Regions that don't implement a custom region interface have type "generic".

Type:
  • string

widgetName :string

For regions that are implemented with a jQuery UI style widget, this is the name of the widget. For other widget implementations it is null. It is used internally by the region#call method.

Type:
  • string

Methods

(static) getParentItems() → {Object}

Returns the parent region column values for the child region of a master-detail relationship. When the detail region does AJAX requests, parent item values (e.g. foreign key columns) must be added to every request. Only interactive grid regions are supported.

Returns an object containing these properties:

  • values: Array of name-value pairs for the parent item values
    • n: name of the parent item
    • v: value of the parent item
Returns:
Array of name-value pairs for the parent item values
Type
Object

(static) getSessionState(pItemsToSubmit) → {Object}

Regions such as Interactive Grid that support column items must implement this method so that the necessary session state can be sent to the server for processing ajax requests.

Returns an object containing these properties:

  • region: The region property contains any region specific data that needs to be sent to the server. The region object must include these properties:
    • id: this is the region id (not the region Static ID)
    • ajaxColumns: TODO think will all regions have this?
    • ajaxIdentifier: ajax identifier for the region plugin as returned by PL/SQL API apex_plugin.get_ajax_identifier
    • setSessionState: an object containing properties
      • values: this is an array of {n: NAME, v: VALUE, ck: CHECKSUM} objects for each column item in pItemsToSubmit
      • protected: this is the protected property of the model record metadata for the active record
      • salt: this is the salt property of the model record metadata for the active record
      TODO think what about master data model parentItems?
  • pageItems: The pageItems property is an array of page items. It contains all the items from pItemsToSubmit except column items that belong to this region are removed.
  • beforeAsync: Optional no argument function that must be called before any async operation begins that could update the value of any column items related to this region.
  • afterAsync: Optional no argument function that must be called after any async operation ends that could update the value of any column items related to this region. There can be multiple calls to beforeAsync and for each one afterAsync must be called.
Parameters:
Name Type Description
pItemsToSubmit Array.<string> An array of item names. It includes both page items and column items.
Returns:
region context object or null if the region doesn't support getting session state
Type
Object

alternateLoadingIndicator(pElement, pLoadingIndicator$) → {jQuery}

Return an alternative loading indicator for the given element. Not all regions have this method so check if it exists before calling. For regions that support column items and when the column items may not be visible on the screen at all times this allows the region to place the loading indicator in an appropriate location. This can return the loading indicator passed in or return a completely new loading indicator.

Parameters:
Name Type Description
pElement Element DOM element that may represent a column item.
pLoadingIndicator$ jQuery A loading indicator that can be inserted in to the DOM where desired and returned or ignored.
Returns:
loadingIndicator jQuery object or null if the region has no alternative for given element
Type
jQuery

call(pMethod, …arguments) → {*}

Calls a method on the widget associated with the region. This method only applies to regions that are implemented with a jQuery UI style widget.

Parameters:
Name Type Attributes Description
pMethod string The string name of the widget method.
arguments * <repeatable>
 Any number of arguments to be passed to the widget.
Returns:
The return value depends on the method called.
Type
*
Example

The call method is a shorthand for calling methods on a widget. The following example shows an Interactive Grid region with Static ID emp and two equivalent ways of invoking the getSelectedRecords method.

var records1 = apex.region("emp").call("getSelectedRecords");
// same result as this more verbose code
var records2 = apex.region("emp").widget().interactiveGrid("getSelectedRecords");

focus()

Cause the 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. 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.

The default implementation sets focus to the first element in the region that is capable of being tabbed to.

Example

The following example will focus the region with Static ID "myRegion".

var region = apex.region( "myRegion" );
region.focus();

gotoError(pErrorContext)

For regions that use an APEX model or column items this provides a way for the apex.message facility to link error messages to the source of the data entry error.

The default implementation does nothing

Parameters:
Name Type Description
pErrorContext Object an object with properties that identify the source of the error. TODO details on pErrorContext

refresh()

Cause the region to get new data from the server or otherwise refresh itself. Not all regions support refresh. Exactly what happens depends on the type of region.

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.

The default implementation triggers the apexrefresh event on the region element for backward compatibility with old regions that don't implement this interface.

Example

The following will refresh the region with Static ID "myRegion":

var region = apex.region( "myRegion" );
region.refresh();

widget() → {jQuery|null}

Returns the widget associated with the 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. See also the region#call method.

Returns:
jQuery object or null if there is no widget associated with the region.
Type
jQuery | null
Example

The following 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" );