Defines a Y.DataTable class extension to add capability to support a Paginator View-Model and allow paging of actively displayed data within the DT instance.

Works with either client-side pagination (i.e. local data, usually in form of JS Array) or in conjunction with remote server-side pagination, via either DataSource or ModelSync.REST.

Allows for dealing with sorted data, wherein the local data is sorted in place, and in the case of remote data the "sortBy" attribute is passed to the remote server.

Usage

var dtable = new Y.DataTable({
    columns:    [ 'firstName','lastName','state','age', 'grade' ],
    data:       enrollment.records,
    scrollable: 'y',
    height:     '450px',
    sortBy:     [{lastName:'asc'}, {grade:-1}],
    paginator:  new PaginatorView({
       model:      new PaginatorModel({itemsPerPage:50, page:3}),
       container:  '#pagContA'
    }),
    resizePaginator: true
});

Client OR Server Pagination

Pagination can either be done solely on the "client", or from a remote "server". The attribute paginationSource is set to either of these strings. The trivial case is where the data is coming locally (i.e. in a JS array) and the user requests "client" pagination. Likewise when pagination occurs solely on a remote device, "server" is very straightforward. This module also provides a middle-path where the initial payload is obtained from a remote source, and then after loading, pagination is to be done on the "client" (see below).

A determination of whether the source of data is either "local" data (i.e. a Javascript Array or Y.ModelList), or is provided from a server (either DataSource or ModelSync.REST) is performed within the method _afterDataReset.

For server-side pagination, the OUTGOING request must include (as a minimum); page and itemsPerPage querystring parameters (all others, including sortBy are optional). Likewise, the INCOMING (returned response) must include as "meta-data" at least totalItems, plus any other PaginatorModel attributes. The key item within the returned response is totalItems'. If the returned response does not containtotalItems` metadata the PaginatorView will not be shown!.

We have provided an attribute serverPaginationMap as an object hash to translate both outgoing querystring parameter names and incoming (response returned) parameter names in order to match what is expected by the PaginatorModel. Please see this attribute or the examples for how to utilize this map for your use case.

Loading the "data" For a Page

Once the "source of data" is known, the method processPageRequest fires on a pageChange.

For the case of "client" pagination, an internal buffer _mlistArray is set to hold all of the data. Each page request in this circumstance involves using simply Array slicing methods from the buffer. (See method paginatorLocalRequest for details)

The case of "remote data" (from a server) is actually more straightforward. For the case of ModelSync.REST remote data the current "pagination state" is processed through the serverPaginationMap hash (to convert to queryString format) and the ModelList.load() method is called. For the case of a DataSource, a similar approach is used where the requestStringTemplate is read, processed through the serverPaginationMap hash and a datasource.load() request is fired. (See methods paginatorMLRequest and paginatorDSRequestfor details)

This extension DOES NOT "cache" pages for remote data, it simply inserts the full returned data into the DT. So as a consequence, a pagination state change for remote data involves a simple request sent to the server source (either DataSource or ModelSync.REST) and the response results are loaded in the DT as in any other "response".

Loading the "initial data" remotely - then using "client" Pagination

A recent revision to this module now allows for the initial payload of data that constitutes the entire "dataset" to be loaded from a remote source (by the standard DataSource or ModelSync.REST methods).

By setting the paginationSource attribute to "client", this module proceeds with paginating the DataTable as if the data was initially set within the "data" property.

Sorting

This module supports sorting for both client and server side Pagination. Note that sorting for "server-side" is required to be accomplished by the remote server; the "sortBy" settings are passed in a remote page request.

For client-side Pagination the task is a more complex. We utilize an internal buffer to store the client-side data, so therefore the requested "sorting" is accomplished internally within method paginatorSortLocalData. Basic "client-side" sorting is supported in this method (limited to one sort key at a time). Implementers may override this method for more complex sorting needs.