Need help with ember-impagination?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

adopted-ember-addons
122 Stars 12 Forks MIT License 353 Commits 31 Opened issues

Description

An Ember Addon that puts the fun back in asynchronous, paginated datasets

Services available

!
?

Need anything else?

Contributors list

Ember-Impagination

npm version Ember Observer Score Build Status Netlify 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.

ember-impagination

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|}}
  
Total Records: {{records.length}}
{{#each records as |record|}}
Record {{record.content.id}}
{{/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
    – Runs the test suite on the current Ember version
  • ember test --server
    – Runs the test suite in "watch mode"
  • ember try:each
    – Runs the test suite against multiple Ember versions

Running the dummy application

For more information on using ember-cli, visit https://ember-cli.com/.

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.

License


This project is licensed under the MIT License.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.