An Ember Addon that puts the fun back in asynchronous, paginated datasets
JavaScript HTML CSS
Permalink
Failed to load latest commit information.
addon Expose some more valuable keys Dec 15, 2016
app Move heart of the code back into Addon folder Dec 14, 2016
blueprints/ember-impagination Refactor Tests Dec 14, 2016
config Update ember-cli to version 2.11.0 πŸš€ (#140) Jan 24, 2017
tests `ember-impagiantion` should be a tagless component Dec 14, 2016
vendor Initial Commit from Ember CLI v1.13.8 Oct 19, 2015
.bowerrc Initial Commit from Ember CLI v1.13.8 Oct 19, 2015
.editorconfig Upgrade to `ember-cli`v2.9.1 Nov 18, 2016
.ember-cli Initial Commit from Ember CLI v1.13.8 Oct 19, 2015
.gitignore Update ember-cli to version 2.10.1 πŸš€ (#139) Jan 20, 2017
.jshintrc Upgrade to `ember-cli`v2.9.1 Nov 18, 2016
.npmignore Updage to `ember-cli`v2.5.1 Nov 18, 2016
.travis.yml Update ember-cli to version 2.11.0 πŸš€ (#140) Jan 24, 2017
.watchmanconfig Upgrade to `ember-cli`v2.3 Nov 18, 2016
CHANGELOG.md Add Changelog & tags Apr 21, 2016
CODE_OF_CONDUCT.md add a Code of Conduct via the Contributor Covenant Jan 7, 2016
LICENSE.md Update ember-cli to version 2.10.1 πŸš€ (#139) Jan 20, 2017
README.md Update README.md (#133) Feb 9, 2017
bower.json Update ember-cli to version 2.11.0 πŸš€ (#140) Jan 24, 2017
ember-cli-build.js Update ember-cli to version 2.11.0 πŸš€ (#140) Jan 24, 2017
index.js Get the dummy app workign again with new impagination Oct 19, 2016
package.json chore(package): update loader.js to version 4.2.2 (#151) Feb 25, 2017
testem.js Updage to `ember-cli`v2.5.1 Nov 18, 2016

README.md

Ember-Impagination

npm version Ember Observer Score Build Status

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, 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}}

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=filterCallback}}
// app/route/record.js
export default Ember.Route.extend({

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

Dataset API

There are a number actions to update the dataset.

Updating the Dataset

Actions Parameters Description
refilter [filterCallback] Reapplies the filter for all resolved pages. If filterCallback is provided, applies and sets the new filter.
reset [offset] Unfetches all pages and clears the state. If offset is provided, fetches records starting at offset.
setReadOffset [offset] Sets the readOffset and fetches records resuming at offset
reload [index] Removed in 1.0.0 release. Please use reset instead.

Updating the State

Actions Parameters Defaults Description
post data, index index = 0 Creates record with data at index.
put data, index index = state.readOffset Merges data into record at index.
delete index index= state.readOffset Deletes record at index.

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() {
  this.get('dataset').reset();
},

actions: {
  observeDataset: function(dataset) {
    this.set('dataset', dataset);
  },
  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|}}
  {{!-- reset dataset and start fetching at record index 0 --}}
  {{#search-pane search=(action "search") on-search-results=(action dataset.reset 0)}}
      {{#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.