Skip to Main Content

Interface: templateReportRegion

QuickNav

Properties

Methods

templateReportRegion

The templateReportRegion interface is used to access the properties and methods of any Template Component Report region. You get access to the templateReportRegion interface with the apex.region function when passed the regionId (static ID) of a Template Component Report region.

Template Component Reports are server rendered regions and have only a few client side API methods. The contents of the report are called rows even if the template component UI may look different such as with cards where multiple cards/rows are on the same visual row.

Since:
  • 24.1

Extends

Properties

element :jQuery

The jQuery object for the region element.

Type:
  • jQuery
Inherited From:
Example

Get option element after initialization.

var value = apex.region( "myRegionId" ).element;

filterRegionId :string

For region plug-ins which support Faceted Search / Smart Filters it is possible to pass in the DOM ID of the facetsRegion region in order for APEX to bind the two together. If provided, the region will be automatically refreshed as the filters change. Further, if the region's refresh callback returns a Promise, APEX will also automatically perform the appropriate locking and unlocking of the facetsRegion region during refresh.

Type:
  • string
Inherited From:

type :string

The templateReportRegion type is "TemplateComponent".

Type:
  • string
Overrides:

Methods

firstPage() → {boolean}

Display the first page of rows. If pagination type is scroll then this simply scrolls to the top of the viewport and a new page of rows is added if needed. If pagination type is not scroll and not already on the first page the view is refreshed and shows the first page.

Returns:
true for success, false if a page is currently being rendered.
Type
boolean
Example

This example goes to the first page.

apex.region( "regionStaticId" ).firstPage();

focus()

Set focus to the templateReport if possible. If the view supports selection or focus then the last focused (current) row will be focused. Otherwise, the first focusable element within the report, if any, will be focused.

Overrides:
Example

This example puts focus in the report.

apex.region( "regionStaticId" ).focus();

getCurrentRow() → {jQuery}

Returns the current row as a jQuery object. The current row is the row that has or last had focus.

This is only applicable if the report supports selection or focus navigation.

Returns:
The current row or null if not supported.
Type
jQuery
Example

This example get the current row in the report.

var current$ = apex.region( "regionStaticId" ).getCurrentRow();
console.log( "make use of current row", current$ );

getCurrentRowValue() → {string}

Returns the value of the current row. The current row is the row that has or last had focus. The value of a row is its primary key in the data-id attribute.

This is only applicable if the report supports selection or focus navigation.

Returns:
The current row value or null if not supported.
Type
string

getSelectedValues() → (nullable) {Array.<string>}

Returns the value for each selected row. The value of a row is its primary key in the data-id attribute. This attribute is typically added with the #APEX$ROW_IDENTIFICATION# placeholder.

This is only applicable if the report supports selection.

Returns:
Array of selected record values. Returns null if selection is not supported.
Type
Array.<string>

getSelection() → (nullable) {jQuery}

Return the currently selected rows as a jQuery collection.

This is only applicable if the report supports selection.

Because this returns a jQuery collection it can only return selected rows that are currently in the DOM. When using virtual scroll pagination with show total count on, it is better to use templateReportRegion#getSelectedValues

See also templateReportRegion#setSelection.

Returns:
The selected row elements as a jQuery collection. Returns null if selection isn't supported or the report is not initialized.
Type
jQuery
Example

This example get the current selection.

var selection$ = apex.region( "regionStaticId" ).getSelection();
console.log( "make use of selected rows", selection$ );

lastPage() → {boolean}

Display the last page of rows. If pagination type is scroll this simply scrolls to the bottom of the viewport and a new page of rows is added if needed. pagination type is not scroll and not already on the last page the view is refreshed and shows the last page. This method only works correctly if the report knows the total number of rows.

Returns:
true for success, false if a page is currently being rendered.
Type
boolean
Example

This example goes to the last page.

apex.region( "regionStaticId" ).lastPage();

nextPage() → {boolean}

Display the next page of rows. If pagination type is scroll the viewport scrolls down one page and rows are added if needed. If pagination type is not scroll and not on the last page refresh the view to show the next page.

Returns:
true for success, false if a page is currently being rendered.
Type
boolean
Example

This example goes to the next page.

apex.region( "regionStaticId" ).nextPage();

previousPage() → {boolean}

Display the previous page of rows. If pagination type is scroll the viewport scrolls up one page and rows are added if needed. If pagination type is not scroll and not on the first page refresh the view to show the previous page.

Returns:
true for success, false if a page is currently being rendered.
Type
boolean
Example

This example goes to the previous page.

apex.region( "regionStaticId" ).previousPage();

refresh() → {Promise}

Refreshes the report with new data from the server.

Overrides:
Returns:
A promise that is resolved with no arguments when the refresh is complete.
Type
Promise

selectAll(pFocusopt, nullable, pNoNotifyopt)

Select all the rows in the report that can be selected. Triggers the apex.event:apexselectionchange event if the selection changes unless pNoNotify is true.

This is only applicable if the report supports multiple selection.

Parameters:
Name Type Attributes Description
pFocus boolean <optional>
<nullable>
 If true the first selected row is given focus.
pNoNotify boolean <optional>
 If true the selection change notification will be suppressed.
Example

This example selects all the rows in the report.

apex.region( "regionStaticId" ).selectAll();

setCurrentRow(pRow$, pFocusopt)

Sets the last focused row to the given pRow$. If pRow$ is not a row or not in the report container the current row is not changed.

This is only applicable if the report supports selection or focus navigation.

The apex.event:apexcurrentrowchange event is triggered any time the current row changes.

Parameters:
Name Type Attributes Description
pRow$ jQuery The row to make current.
pFocus boolean <optional>
 If true also focus the row.
Example

This example finds a particular row using jQuery and then makes it the current row and sets focus to it. In this example report rows have class "my-item".

var current$ = $( "#regionStaticId .my-item" ).first();
apex.region( "regionStaticId" ).setCurrentRow( current$, true );

setCurrentRowValue(pRowValue, pFocusopt)

Sets the last focused row to the one with the given pRowValue. If no row has the given value the current row is not changed. The row must be rendered in order to be made the current row. The value of a row is its primary key in the data-id attribute. This attribute is typically added with the #APEX$ROW_IDENTIFICATION# placeholder.

This is only applicable if the report supports selection or focus navigation.

The apex.event:apexcurrentrowchange event is triggered any time the current row changes.

Parameters:
Name Type Attributes Description
pRowValue string The value of a row.
pFocus boolean <optional>
 If true also focus the row.

setSelectedValues(pValues, pFocusopt, pNoNotifyopt) → {number}

Selects the report rows that correspond to the given values. The value of a row is the primary key in the data-id attribute. This attribute is typically added with the #APEX$ROW_IDENTIFICATION# placeholder. Triggers the apex.event:apexselectionchange event if the selection changes unless pNoNotify is true.

This is only applicable if the report supports selection.

Parameters:
Name Type Attributes Description
pValues Array.<string> Array of row values to select.
pFocus boolean <optional>
 If true the first row of the selection is given focus.
pNoNotify boolean <optional>
 If true the selection change event will be suppressed.
Returns:
Count of the rows actually selected or -1 if called before the report is initialized or there is no data or selection is not supported.
Type
number

setSelection(pElements$, pFocusopt, pNoNotifyopt)

Set the selected rows. Triggers the apex.event:apexselectionchange event if the selection changes unless pNoNotify is true.

This is only applicable if the report supports selection.

See also templateReportRegion#getSelection.

Parameters:
Name Type Attributes Description
pElements$ jQuery A jQuery object with row elements such as the return value of getSelection.
pFocus boolean <optional>
 If true the first row element of the selection is given focus.
pNoNotify boolean <optional>
 If true the selection change event will be suppressed.
Example

This example finds a particular row using jQuery and then selects it and sets focus to it. In this example report rows have class "my-item".

var toSelect$ = $( "#regionStaticId .my-item" ).first();
apex.region( "regionStaticId" ).setSelection( toSelect$, true );