Pre-General Availability: 2018-5-8

Widget: tableModelView

QuickNav

Options

Events

Methods

tableModelView

Template driven view for a table model that supports pagination. Derived from tableModelViewBase. Does not support editing. Supports selection when using an iconList widget to handle the records.

The expected markup is an empty element; typically a div.

There are two ways to define the markup for the view. Configure with options beforeTemplate, recordTemplate, and afterTemplate for complete control over the markup. Or configure with options iconClassColumn, imageURLColumn, imageAttributes, labelColumn, linkTarget, linkTargetColumn, and linkAttributes for default list markup.

Initializer

$(".selector").tableModelView(options)

Creates a tableModelView widget.
Parameters:
Name Type Description
options Object A map of option-value pairs to set on the widget.
Since:
  • 5.1
Example

Create a tableModelView for name value paris displayed in a simple table.

  var fields = {
          PARTNO: {
              index: 0
          },
          PART_DESC: {
              index: 1
          }
      },
      data = [
          ["B-10091", "Spark plug"],
          ["A-12872", "Radiator hose"],
          ...
      ];
  apex.model.create("parts", {
          shape: "table",
          recordIsArray: true,
          fields: fields,
          paginationType: "progressive"
      }, data, data.length );
  $("#partsView").tableModelView( {
      modelName: "parts",
      beforeTemplate: '<table class="u-Report"><thead><tr><th>Part No</th><th>Description</th></tr></thead><tbody>',
      afterTemplate: '</tbody></table>',
      recordTemplate: '<tr><td>&PARTNO.</td><td>&PART_DESC.</td></tr>',
      pagination: {
          scroll: true
      }
  } );

Extends

Options

afterTemplate :string

Markup to render after the record data. For example "</ul>".

Type:
  • string
Default Value:
  • </ul>

autoAddRecord :boolean

Specifies if a new record should be automatically added when the model doesn't contain any data. If supported by the derived view a new record may be added when moving beyond the last record in the view while editing. Must only be true if the model and view are editable and the model allows adding records.

Type:
  • boolean
Inherited From:
Default Value:
  • false

beforeTemplate :string

Markup to render before the record data. For example "<ul>".

Type:
  • string
Default Value:
  • <ul>

collectionClasses :string

Extra CSS classes to add to the element that is the parent of the collection of records.

Type:
  • string

editable :boolean

Determine if the view allows editing. This is independent of the model editability. If true the view data can be edited according to what the model allows. Only applies if the view supports editing.

Type:
  • boolean
Inherited From:
Default Value:
  • false

Determine if the view will include a footer to show status and pagination controls and information. If true a footer is shown at the bottom of the view. If false no footer is shown.

Type:
  • boolean
Inherited From:
Default Value:
  • true

hasSize :boolean

This affects scrolling and how any header (if the view has a header) or footer position is handled.

Set to true if the view is in a container that has a specific height defined. When hasSize is true the record content will scroll within the bounds of the region.

Set to false if the view does not have a defined height. The view height will be as large as needed to contain the view records as determined by pagination settings. The view may scroll within the browser window. Other options may control if the header (if the view has a header) or footer sticks to the window.

The container width must always be defined.

Type:
  • boolean
Inherited From:
Default Value:
  • false

hideDeletedRows :boolean

Determine if deleted rows (records) are removed from the view right away or shown with a strike through effect to indicate they are going to be deleted. If true (and the view is editable) deleted records will not be visible, otherwise they are visible but have a visual indication that they are deleted. The actual records are not deleted on the server until the model is saved.

Type:
  • boolean
Inherited From:
Default Value:
  • false

highlights :object

Defines highlight color information for the view. Only applies to views that support highlighting. Style rules are injected into the document based on the highlight object.

The object is a mapping of highlight id to color definition.

Type:
  • object
Properties:
Name Type Description
* object A highlight ID. A unique ID for the highlight rule. The object can contain any number of highlight rules. The model record or field highlight metadata (see model.RecordMetadata) is used to associate the model data with the highlight rule. One of color or background must be given.
Properties
Name Type Attributes Description
seq number A number that defines the order of the CSS rule that is added.
row boolean If true the highlight applies to the record/row.
color string <nullable>
 The foreground color. If given, must be a valid CSS color value.
background string <nullable>
 The background color. If given, must be a valid CSS color value.
cssClass string <nullable>
 The class name for the rule. This is the class used in the rule and given to the appropriate element in the view so that the desired highlight colors are applied. The cssClass defaults to the highlight id prefixed with "hlr_" if row is true and "hlc_" otherwise.
Inherited From:

iconClassColumn :string

The CSS class column to use for the icon. At most one of iconClassColumn and imageURLColumn should be given.

Type:
  • string
Default Value:
  • null

iconListOptions :object

Additional options to pass to the iconList widget. See iconList for information about the options it supports.

Type:
  • object

imageAttributes :string

Attributes for the img element. Only used if imageURLColumn is specified.

Type:
  • string
Default Value:
  • null

imageURLColumn :string

The URL column of image to use for the icon. At most one of iconClassColumn and imageURLColumn should be given.

Type:
  • string
Default Value:
  • null

labelColumn :string

Name of the column that contains the label text.

At a minimum one of labelColumn or recordTemplate is required.

Type:
  • string
Default Value:
  • null

linkAttributes :string

Additional anchor attributes. Ignored unless a link is present.

Type:
  • string

linkTarget :boolean

If true the record metadata should contain a url attribute with the link target.

Type:
  • boolean
Default Value:
  • false

linkTargetColumn :string

The name of the column that contains the anchor href. If not given the href comes from the cell field metadata url property. If there is no url property then this column/cell is not a link.

Type:
  • string

modelName :string

Name of model that this view widget will display data from. Can include an instance as well. The model must already exist. This option is required.

Type:
  • string
Inherited From:

noDataMessage :string

Text to display when there is no data.

Type:
  • string
Inherited From:

pagination :object

Pagination settings.

Type:
  • object
Properties:
Name Type Description
scroll boolean If true the scroll bar is used to page through the results a.k.a infinite scrolling or virtual paging. If false then next and previous buttons are shown. Default is false.
loadMore boolean If true show a load more button rather than auto paging. Only applies if scroll is true and the model doesn't know the total rows. Default is false.
showPageLinks boolean If true show page links between buttons. Only applies if scroll is false The model must know the total number of rows for this to be true. Default is false.
maxLinks number The maximum number of links to show when showPageLinks is true. Default is 5.
showPageSelector boolean If true show a drop down page selector between the buttons. Only applies if scroll is false. The model must know the total number of rows for this to be true. Default is false.
showRange boolean If true the range of rows/records is shown. It is shown between the buttons unless showPageLinks or showPageSelector is true. The range is shown as "X to Y" if the model doesn't know the total rows and "X to Y of Z" if the model does know the total number of rows. Default is true.
firstAndLastButtons boolean Only applies if scroll is false. If true first and last buttons are included. For this to be true the model must know the total number of rows.
Inherited From:

progressOptions :object

Options object to pass to apex.util.showSpinner. The default depends on the hasSize option.

Type:
  • object
Inherited From:
Default Value:
  • { fixed: !options.hasSize }

recordTemplate :string

Markup to render for each record. Can use substitution tokens from the model using column names. In addition you use the following special substitution symbols:

  • APEX$ROW_ID - the record id
  • APEX$ROW_INDEX - the record index
  • APEX$ROW_URL - the record url
  • APEX$ROW_STATE_CLASSES - various record states such as is-inserted or is-deleted

At a minimum one of labelColumn or recordTemplate is required

Type:
  • string

rowsPerPage :boolean|null

Determine how many rows to show in one page. Only applies if pagination.scroll is false, otherwise this value is ignored. If null this value is determined by the viewport height

Type:
  • boolean | null
Inherited From:
Default Value:
  • null

selectionStatusMessageKey :string

The text message key to use for showing the number of selected rows/records in the footer. The message key must have exactly one parameter %0 which is replaced with the number of rows/records selected.

Type:
  • string
Inherited From:
Default Value:
  • "APEX.GV.SELECTION_COUNT"

Determine if the footer will stick to the bottom of the page. Only applies if hasSize is false and footer is true. If false the footer will not stick to the bottom of the page. If true the footer will stick to the bottom of the page.

Type:
  • boolean
Inherited From:
Default Value:
  • false

useIconList :boolean

If true use the iconList widget to display the records.

Type:
  • boolean

Events

pagechange

Triggered when there is a pagination event that results in new records being displayed.
Properties:
Name Type Description
event Event jQuery event object.
data Object Additional data for the event.
Properties
Name Type Description
offset number the offset of the first record in the page.
count number the number of records in the page that were added to the view.
Examples

Initialize the tableModelView with the pageChange callback specified:

$( ".selector" ).tableModelView({
    pageChange: function( event ) {}
});

Bind an event listener to the tablemodelviewpagechange event:

$( ".selector" ).on( "tablemodelviewpagechange", function( event ) {} );

selectionchange

Triggered when the selection state changes. It has no additional data. Only tableModelViews with useIconList true support selection.
Properties:
Name Type Description
event Event jQuery event object.
Examples

Initialize the tableModelView with the selectionChange callback specified:

$( ".selector" ).tableModelView({
    selectionChange: function( event ) {}
});

Bind an event listener to the tablemodelviewselectionchange event:

$( ".selector" ).on( "tablemodelviewselectionchange", function( event ) {} );

Methods

firstPage() → {boolean}

Display the first page of records. If pagination.scroll is true simply scrolls to the top of the viewport and a new page of records is added if needed. If pagination.scroll is false and not already on the first page the view is refreshed and shows the first page.

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

getActiveRecord() → {model.record}

Returns the active record or null if there is no active record. The active record is the one currently being edited.

Inherited From:
Returns:
active record
Type
model.record

getActiveRecordId() → {string}

Returns the identity of the active record or null if there is no active record. The active record is the one currently being edited.

Inherited From:
Returns:
active record id
Type
string

getIconList() → {object}

Return the iconList instance if option tableModelView#useIconList is true, and null otherwise.

Note: This returns the instance and not the jQuery object.

Returns:
iconList The iconList widget instance.
Type
object
Example

This example gets the iconList and calls the getColumns method.

$(".selector").tableModelView("getIconList").getColumns();

getRecords(pElements$) → {Array.<model.Record>}

Given a jQuery object with one or more record elements return the corresponding model records. For this to work the elements must have a data-id attribute with the value of the record id.

Parameters:
Name Type Description
pElements$ jQuery A jQuery object of record elements such as returned by getSelection.
Returns:
Array of records from the model corresponding to the record elements.
Type
Array.<model.Record>

getSelectedRecords() → {Array.<model.Record>}

Return the underlying data model records corresponding to the current selection.

This is only applicable if the tableModelView#useIconList option is true. If it is false then null is returned.

Returns:
Array of records from the model corresponding to the selected record elements.
Type
Array.<model.Record>

getSelection() → {jQuery}

Return the currently selected elements.

This is only applicable if the iconList#useIconList option is true.

Returns:
The selected record elements. Returns null if not using an iconList.
Type
jQuery

gotoPage(pPageNumber) → {boolean}

Go to the specified page number. This should only be used when pagination.scroll is false and the model knows the total number of records.

Parameters:
Name Type Description
pPageNumber zero based page number
Inherited From:
Returns:
true for success, false if a page is currently being rendered.
Type
boolean

lastPage() → {boolean}

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

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

loadMore() → {boolean}

Load more records into the view. When pagination.scroll is true this adds a new page of records to the end. When pagination.scroll is false this is the same as nextPage. This is intended to be used when pagination.loadMore is true.

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

lockActive()

Call to lock the active row while async processing is in progress.

The view edits one row/record at a time. This is known as the active row. In edit mode as the user changes the focused cell with the mouse, tab or enter keys if the new cell is on a different row the previous row is deactivated and the new row is activated. Any dynamic actions or other code that manipulates Column items are acting on the active row. If any actions are asynchronous such as using ajax to set a column item value then the row must not be deactivated while the async action is in progress otherwise the result would be applied to the wrong row!

So this method must be called before starting an async operation. It can be called multiple times if there are multiple async operations. For each call to lockActive there must be exactly one call to unlockActive.

If the view is part of an APEX region plugin, that region should implement the beforeAsync and afterAsync functions on the object returned from region.getSessionState by calling lockActive and unlockActive respectively. Then if an appropriate target option is passed to apex.server.plugin then the locking will be done automatically. Dynamic Actions that act on column items pass the correct target option. The bottom line is that for Dynamic Actions on columns of an Interactive Grid these lock/unlock methods are called automatically.

Inherited From:

nextPage() → {boolean}

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

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

previousPage() → {boolean}

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

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

refresh(pFocusopt)

Refresh the view. Typically no need to call this method because it is called automatically when the model data is refreshed.

Parameters:
Name Type Attributes Description
pFocus boolean <optional>
 if true put focus in the view, if false don't. If undefined/omitted maintain focus if the view already has focus.

resize()

This method must be called if the size of the container changes so that pagination state, footer position, and nested iconList if any can be updated to reflect the new size.

setActiveRecordValue(pColumn)

Use after a column item value is set without triggering a change event to update the model and grid view. Has no effect if there is no active record.

todo improve doc
Parameters:
Name Type Description
pColumn string The name of the column.
Inherited From:

setSelectedRecords(pRecords, pFocus, pNoNotifyopt)

Select the elements that correspond to the given data model records.

This is only applicable if the tableModelView#useIconList option is true.

Parameters:
Name Type Attributes Description
pRecords Array.<model.Record> Array of data model records to select.
pFocus boolean If true the first record of the selection is given focus.
pNoNotify boolean <optional>
 If true the selection change event will be suppressed.

setSelection(pElements$, pFocusopt, pNoNotifyopt)

Set the selected record elements.

This is only applicable if the iconList#useIconList option is true.

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

unlockActive()

Call to unlock the active row after async processing is complete.

Call after the async operation completes. See tableModelViewBase#lockActive for more information.

Inherited From: