Ember-Impagination

Ember-Impagination is an Ember binding for Impagination, a front-end data-layer for the paginated API on your server. Ember-Impagination leverages the power of Glimmer and provides your component the data it needs to render quickly each and every time.

Impagination README:

Whatever your use-case: infinite scrolling lists, a carousel browser, or even a classic page-by-page result list, Impagination frees you to focus on what you want to do with your data, not the micro-logistics of when to fetch it. All you provide Impagination is the logic to fetch a single page, plus how many pages you want it to pre-fetch ahead of you, and it will figure out the rest.

Impagination is built using an event-driven immutable style, so it is ideal for use with UI frameworks like Ember . . .

Hence, we present Ember-Impagination.

Ember-Impagination provides you with a component, {{impagination-dataset as |data|}}, you can use to feed data into your templates while having that data look exactly like an Ember.Array.

Note: Ember-Impagination does not provide any of the visual elements in a system like infinite scroll. You'll still need to use a special component like virtual-each or ember-collection. Instead, Ember-Impagination simplifies feeding your components fetched data.

Installation

ember install ember-impagination

Demo

Ember-Impagination Demo

The demo presents a finite scroll implementation of Ember-Impagination. It scrolls through the ROYGBIV color spectrum by loading and unloading pages of records, where each record is a unique color-hue. At the top of the demo, you will find a visualization for pages. Resolved (Loaded) Pages are green, Pending (Loading) pages are white, and Unrequested (Unloaded) pages are black. The white-bar represents the top-most index of the scroll view.

The demo is implemented using virtual-each due to the simplicity of the component. However, Ember-Impagination can also be utilized with other components like ember-collection, or even a simple {{each}}. By design, Ember-Impagination leverages Glimmer and yields paginated data from your server's API to components which expect an array.

Usage

Impagination-Dataset Component

To create an impagination-dataset there are two required parameters, fetch and page-size. Optional parameters include load-horizon, unload-horizon, read-offset, unfetch. See Impagination for detailed attribute descriptions.

{{!-- app/templates/index.hbs --}}
{{#impagination-dataset
  fetch=fetch
  page-size=pageSize
  load-horizon=loadHorizon
  as |records|}}
  <div class="records">Total Records: {{records.length}}</div>
  {{#each records as |record|}}
    <div class="record">Record {{record.content.id}}</div>
  {{/each}}
{{/impagination-dataset}}

In most cases, using a simple {{each}} would defeat the purpose of using a data layer like Ember-Impagination, and for truly infinite datasets might result in truly infinite loops 😱

Now, in your route, you can define the actual (un)fetch functions that tell {{impagination-dataset}} how it should request each individual page, and the (un)loadHorizon which specify how many pages to request ahead/behind.

// app/route/record.js
export default Ember.Route.extend({
  pageSize: 5,               // fetch records in pages of 5 (*required*)
  loadHorizon: 10,           // fetch  records "inclusive" (+/- loadHorizon)   of the current readOffset (default: pageSize)
  //unloadHorizon: Infinity, // unload records "exclusive" (+/- unloadHorizon) of the current readOffset (default: Infinity)
  //readOffset: 0,           // the initial readOffset of the dataset (default: 0)

  // fetch() function is invoked whenever a page is requested within the loadHorizon
  fetch: function(pageOffset, pageSize, stats) { // function which returns a "thenable" (*required*)
    let params = {
      page: pageOffset,
    };
    // fetch a page of records at the pageOffset
    return this.store.query('record', params).then((data) => {
      let meta = data.get('meta');
      stats.totalPages = meta.totalPages;
      return data.toArray();
    });
  },
  // unfetch() function is invoked whenever a page is unloaded
  unfetch: function(records, pageOffset) {
    this.store.findByIds('record', records.map(r => r.id).then(function(records) {
      records.forEach(record => record.deleteRecord());
    });
  }
})

This setup will immediatly call fetch twice (for records 0-4 [page 0] and records 5-9 [page 1])

Total Records: 10
Record 0
Record 1
Record 2
...
Record 9

Passing the Fetch Function

In Ember 1.13 and above, we can use closure-actions to pass the fetch function into ember-impagination

{{#impagination-dataset fetch=(action "fetch")}}

// app/route/record.js
export default Ember.Route.extend({

  // fetch() function is invoked whenever a page is requested within the loadHorizon
  actions: {
    fetch(pageOffset, pageSize, stats) { // function which returns a "thenable" (*required*)
      let params = {
        query: query,
      };
      // fetch a page of records at the pageOffset
      return this.store.query('record', params).then((data) => {
        let meta = data.get('meta');
        stats.totalPages = meta.totalPages;
        return data.toArray();
      });
    }
  }
});

We do not recommend defining fetch inside your controller because it requires injecting the store into the controller

In Ember 1.12 and below we cannot define fetch in our actions hash. We must instead bind it to our controller.

{{#impagination-dataset fetch=fetch)}}

// app/route/record.js
export default Ember.Route.extend({
    fetch: function(pageOffset, pageSize, stats) {
      return this.store.query(...);
    },
    setupController: function(controller, model){
      this._super.apply(this, arguments);
      controller.set('fetch', this.fetch.bind(this));
    }
});

Filtering Records

We fetch records using an immutable style, but we often require filtering by mutable records in our dataset. To enable filtering, pass a filter callback to ember-impagination as you would to Array.prototype.filter(). The filters are applied as soon as a page is resolved. To filter a page at other times in your application see refilter.

{{#impagination-dataset fetch=(action "fetch") filter=(action "filterCallback")}}

// app/route/record.js
export default Ember.Route.extend({

  // filter() function is invoked whenever a page is resolved or refiltered
  actions: {
    filterCallback(record/*, index, records*/) { // function which rejects deleted records
      return !record.get('isDeleted');
    }
  }
});

Dataset Actions

There are a number of public impagination functions which we provide as actions.

Actions	Params	Default	Description
refilter	none	none	Reapplies the filter to all resolved pages.
reload	`offset`	currentOffset	Unfetches all pages and fetches records at starting at `offset`
reset	`offset`	0	Destroys all pages and fetches records at starting at `offset`
setReadOffset	`offset`	none	Sets the readOffset and fetches records resuming at `offset`

These functions can be called from the route/controller or from child components in the handlebars templates. In the examples below, we reset the dataset upon search queries through the {{search-pane}} component using both options.

resetting from the parent route

In order to call dataset actions from the route, we will have to observe the latest dataset and dataset-actions with the on-observe parameter.

{{#search-pane search=(action "search")}}
  {{#impagination-dataset on-observe=(action "observeDataset") fetch=(action "fetch") as |dataset|}}
    {{#ember-collection items=dataset as |record|}}
      {{chat-search-result result=record}}
    {{/ember-collection}}
  {{/impagination-dataset}}
{{/search-pane}}

_resetDataset() {
  let reset = this.get('actions.reset');
  reset.call(this.get('dataset'));
},

actions: {
  observeDataset: function(dataset, actions) { // dataset and actions are passed-up
    this.set('dataset', dataset);
    this.set('actions', actions);
  },
  search(query) {
    this.set('searchParams', query);
    this._resetDataset();
  },
  fetch(pageOffset, pageSize, stats) {
    params = this.get('params');
    return this.store.query('records', params);
  }
}

resetting from child components

Here we do not need to utilize impagination-dataset's on-observe parameter. The reset action is simply called by a child component.

{{#impagination-dataset fetch=(action "fetch") as |dataset|}}
  {{#search-pane search=(action "search") on-search-results=(action "reset" target=dataset)}}
      {{#ember-collection items=dataset as |record|}}
        {{chat-search-result result=record}}
      {{/ember-collection}}
  {{/search-pane}}
{{/impagination-dataset}}

Create your own Dataset

If {{impagination-dataset}} is not an ideal component for your unique Impagination needs, you can get into the nitty gritty, and use Impagination directly. If you find yourself creating your own Dataset, let us know how you are using Dataset and Impagination. It may be a reason for improvements or another ember addon.

import Dataset from 'impagination/dataset';

let dataset = new Dataset({
  pageSize: 5,
  fetch: function(pageOffset, pageSize, stats) {
    return new Ember.RSVP.Promise((resolve)=> {
      let data = // Array
      resolve(data);
    },

    return this.store.query('record', params).then((data) => {
      let meta = result.get('meta');
      stats.totalPages = meta.totalPages;
      return result.toArray();
    });
  },
  observe: (state) => {}
});

Running Tests

ember test
ember test --server

Code of Conduct

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms, which can be found in the CODE_OF_CONDUCT.md file in this repository.

willrax / ember-impagination