Demo: ember-infinity.github.io/ember-infinity/
Simple, flexible infinite scrolling for Ember CLI Apps. Works out of the box with the Kaminari Gem.
Also:
ember install ember-infinity
ember-infinity exposes 3 consumable items for your application.
-
infinity service
-
infinity-loader component
-
Route Mixin (deprecated)
As of 1.0, you can either use the infinity service model hook or the infinityModel Route mixin hook. You may be used to the Route mixin; however, we will be moving forward with the service based approach as the ergonomics for your application are greatly improved.
Ember Infinity has moved to a service based approach wherein your application is viewed as an interaction between your components (ephemeral state) and service (long term state).
As a result of this new approach, we can intelligently store your model state to provide you the ability to cache and invalidate your cache when you need to. If you provide an optional infinityCache timestamp (in ms), the infinity service model hook will return the existing collection (and not make a network request) if the timestamp has not yet expired. Be careful as this will also circumvent your ability to receive fresh data on every route visit.
Moreover, you are not restricted to only fetching items in the route. Fetch away in any top-level component!
Lastly, before we get to an example, you do not need to pass an action into infinity-loader component anymore. We handle that internally now. You can still pass a closure action infinityLoad if you need to perform additional logic.
Let's see how simple it is to fetch a list of products. Instead of this.store.query('product') or this.store.findAll('product'), you simply invoke this.infinity.model('product') and under the hood, ember-infinity will query the store and manage fetching new records for you!
import Route from '@ember/routing/route';
import { inject as service } from '@ember/service';
export default Route.extend({
infinity: service(),
model() {
return this.infinity.model('product');
}
});Importing the ember-infinity Route Mixin and extending your route will give you access to this.infinityModel in your model hook. For various reasons (including you writing less code!), we have deprecated the use of the Route mixin and will phase it out by v1.1.
import Route from '@ember/routing/route';
import InfinityRoute from "ember-infinity/mixins/route";
export default Route.extend(InfinityRoute, {
model() {
/* Load pages of the Product Model, starting from page 1, in groups of 12. */
return this.infinityModel('product', { perPage: 12, startingPage: 1 });
}
});Then, you'll need to add the infinity-loader component to your template, like so, in which model is an instance of InfinityModel returned from your model hook.
In both cases, whenever the infinity-loader component is in view, we will fetch the next page for you.
By default, ember-infinity expects the server response to contain something about how many total pages it can expect to fetch. ember-infinity defaults to looking for something like meta: { total_pages: 20 } in your response. See Advanced Usage.
Let's look at a more complicated example using multiple infinity models in a route. Super easy!
import Route from '@ember/routing/route';
import RSVP from 'rsvp';
import { inject as service } from '@ember/service';
export default Route.extend({
infinity: service(),
model() {
return RSVP.hash({
products: this.infinity.model('product'),
users: this.infinity.model('user')
});
}
});The infinity service also exposes 5 methods to fetch & mutate your collection:
- model
- replace
- flush
- pushObjects
- unshiftObjects
The model hook (similar to the Route Mixin infinityModel hook pre 1.0) will fetch the first page you request and pass the result to your template.
import Route from '@ember/routing/route';
import { inject as service } from '@ember/service';
export default Route.extend({
infinity: service(),
model() {
return this.infinity.model('product');
}
});Moreover, if you want to intelligently cache your infinity model, pass { infinityCache: timestamp } and we will return the cached collection if the future timestamp is less than the current time (in ms) if your users revisit the same route.
import Route from '@ember/routing/route';
import { inject as service } from '@ember/service';
export default Route.extend({
infinity: service(),
model() {
return this.infinity.model('product', { infinityCache: 36000 }); // timestamp expiry of 10 minutes (in ms)
}
});Let's see an example of using replace.
import Controller from '@ember/routing/route';
import { inject as service } from '@ember/service';
import { get } from '@ember/object';
export default Controller.extend({
infinity: service(),
actions: {
/**
@method filterProducts
@param {String} query
*/
async filterProducts(query) {
let products = await this.store.query('product', { query });
// model is the collection returned from the route model hook
get(this, 'infinity').replace(get(this, 'model'), products);
}
}
});import Route from '@ember/routing/route';
import { inject as service } from '@ember/service';
export default Route.extend({
infinity: service(),
model() {
return this.infinity.model('product');
}
});If you want to use closure actions with ember-infinity and the infinity-loader component, you need to be a little bit more explicit. Generally you should let the infinity service handle fetching records for you, but if you have a special case, this is how you would do it:
See the Ember docs on passing actions to components here.
import Controller from '@ember/routing/route';
import { inject as service } from '@ember/service';
import { get } from '@ember/object';
export default Controller.extend({
infinity: service(),
actions: {
/**
Note this must be handled by you. An action will be called with the result of your Route model hook from the `infinity-loader` component, similar to this:
// closure action in infinity-loader component
get(this, 'infinityLoad')(infinityModelContent);
@method loadMoreProduct
@param {InfinityModel} products
*/
loadMoreProduct(products) {
// Perform other logic ....
get(this, 'infinity').infinityLoad(products);
}
}
});import Route from '@ember/routing/route';
import { inject as service } from '@ember/service';
export default Route.extend({
infinity: service(),
model() {
return this.infinity.model('product');
}
});In the world of optimistic route transitions & skeleton UI, it's necessary to return a POJO or similar primitive to Ember's Route#model hook to ensure the transition is not blocked by promise.
model() {
return {
posts: this.infinity.model('post')
};
}By default, ember-infinity will send pagination parameters as part of a GET request as follows
/items?per_page=5&page=1
and will expect to receive metadata in the response payload via a total_pages param in a meta object
{
items: [
{id: 1, name: 'Test'},
{id: 2, name: 'Test 2'}
],
meta: {
total_pages: 3
}
}If you wish to customize some aspects of the JSON contract for pagination, you may do so via your model hook. For example, you may want to customize the following:
Default:
- perPageParam:
per_page, - pageParam:
page, - totalPagesParam:
meta.total_pages, - countParam:
meta.count,
Example Customization shown below:
- perPageParam:
per, - pageParam:
pg, - totalPagesParam:
meta.total, - countParam:
meta.records,
import Route from '@ember/routing/route';
import { inject as service } from '@ember/service';
export default Route.extend({
infinity: service(),
model() {
/* Load pages of the Product Model, starting from page 1, in groups of 12. Also set query params by handing off to infinityModel */
return this.infinity.model('product', { perPage: 12, startingPage: 1,
perPageParam: 'per', pageParam: 'pg', totalPagesParam: 'meta.total', countParam: 'meta.records' });
}
});This will result in request query params being sent out as follows
/items?per=5&pg=1
and ember-infinity will be set up to parse the total number of pages from a JSON response like this:
{
items: [
...
],
meta: {
total: 3
}
}You can also prevent the per_page or page parameters from being sent by setting perPageParam or pageParam to null, respectively.
Moreover, if your backend passes the total number of records instead of total pages, then as it's replacement, set the countParam.
If you are serving a continuously updating stream, it's helpful to keep track
of your place in the list while paginating, to avoid duplicates. This is known
as cursor-based pagination and is common in popular APIs like Twitter,
Facebook, and Instagram. Instead of relying on page_number to paginate,
you'll want to extract the min_id or min_updated_at from each page of
results, so that you can fetch the next page without risking duplicates if new
items are added to the top of the list by other users in between requests.
To do this, implement the afterInfinityModel hook as follows:
import Route from '@ember/routing/route';
import InfinityModel from 'ember-infinity/lib/infinity-model';
const ExtendedInfinityModel = InfinityModel.extend({
buildParams() {
let params = this._super(...arguments);
params['min_id']: get(this, '_minId'); // where `this` is the infinityModel instance
params['min_updated_at']: get(this, '_minUpdatedAt');
return params;
},
afterInfinityModel(posts) {
let loadedAny = posts.get('length') > 0;
posts.set('canLoadMore', loadedAny);
this.set('_minId', posts.get('lastObject.id'));
this.set('_minUpdatedAt', posts.get('lastObject.updated_at').toISOString());
}
});
export default Route.extend({
infinity: service(),
model() {
return this.infinity.model('post', {}, ExtendedInfinityModel);
}
});You can also provide additional static parameters to infinityModel that
will be passed to your backend server in addition to the
pagination params. For instance, in the following example a category
parameter is added:
return this.infinity.model('product', { perPage: 12, startingPage: 1,
category: 'furniture' });Extending infinityModel
As of 1.0+, you can override or extend the behavior of Ember Infinity by providing a class that extends InfinityModel as a third argument to the Route#infinityModel hook.
Note: This behavior should negate any need for the pre 1.0 "Bound Params" style of work. See [Bound Parameters](#Bound Parameters) Section below for more information.
import InfinityModel from 'ember-infinity/lib/infinity-model';
const ExtendedInfinityModel = InfinityModel.extend({
buildParams() {
let params = this._super(...arguments);
params['category_id'] = get(this, 'global.categoryId');
return params;
}
});
export default Route.extend({
global: service(),
infinity: service(),
categoryId: computed('global.categoryId', function() {
return get(this, 'global.categoryId');
}),
model() {
let global = get(this, 'global');
this.infinity.model('product', {}, ExtendedInfinityModel.extend({ global }));
}
});[DEPRECATED] Bound Parameters
As of 1.0+, passing a third parameter to represent Bound Parameters is deprecated. All valid use cases of this feature should now be ported to the [Extended Infinity Model pattern][Extending infinityModel].
Bound Params were introduced as a way of dynamically fetching data over time - the query params passed to the server would be dictated by a property (computed or otherwise) on the route level, that was evaluated at the request time.
This design has always felt a little off - using computed properties on the Route level is an uncommon (and thus non-ergonomic) pattern in Ember. As users have requested more features in Ember Infinity, we've realized it's more important to provide a flexible primitive that can be manipulated and extended in a Ember-esque way. This opens Ember Infinity up to a great deal more use cases, while also providing a path forward to those using the pre 1.0 version of Bound Params.
- modelPath
modelPath is optional parameter for situations when you are overriding setupController
or when your model is on different location than controller.model.
model() {
return this.infinity.model('product', {
perPage: 12,
startingPage: 1,
modelPath: 'controller.products'
});
},
setupController(controller, model) {
controller.set('products', model);
}In some cases, a single call to your data store isn't enough. The afterInfinityModel
method is available for those cases when you need to chain together functions or
promises after fetching a model.
As a simple example, let's say you had a blog and just needed to set a property on each Post model after fetching all of them:
import Route from '@ember/routing/route';
import InfinityModel from 'ember-infinity/lib/infinity-model';
const ExtendedInfinityModel = InfinityModel.extend({
afterInfinityModel(posts) {
posts.setEach('author', 'Jane Smith');
}
});
export default Route.extend({
model() {
return this.infinity.model('post', {}, ExtendedInfinityModel);
}
});As a more complex example, let's say you had a blog with Posts and Authors as separate related models and you needed to extract an association from Posts. In that case, return the collection you want from afterInfinityModel:
import Route from '@ember/routing/route';
import InfinityModel from 'ember-infinity/lib/infinity-model';
const ExtendedInfinityModel = InfinityModel.extend({
afterInfinityModel(posts) {
return posts.mapBy('author').uniq();
}
});
export default Route.extend({
model() {
return this.infinity.model('post', {}, ExtendedInfinityModel);
}
});import Route from '@ember/routing/route';
import InfinityModel from 'ember-infinity/lib/infinity-model';
export default Route.extend(InfinityRoute, {
model() {
return this.infinity.model("post");
},
afterInfinityModel(posts) {
posts.setEach('author', 'Jane Smith');
}
});afterInfinityModel should return either a promise, ArrayProxy, or a
falsy value. The returned value, when not falsy, will take the place of the
resolved promise object and, if it is a promise, will hold execution until resolved.
In the case of a falsy value, the original promise result is used.
So relating this to the examples above... In the first example, afterInfinityModel
does not have an explicit return defined so the original posts promise result is used.
In the second example, the returned collection of authors is used.
The route mixin also provides following event hooks:
infinityModelUpdated
Triggered on the route whenever new objects are pushed into the infinityModel.
Args:
infinityModelLoaded
-
lastPageLoaded
-
totalPages
-
infinityModel
Triggered on the route when the infinityModel is fully loaded.
Args:
- totalPages
import Route from '@ember/routing/route';
export default Route.extend({
...
model() {
/* Load pages of the Product Model, starting from page 1, in groups of 12. */
return this.infinity.model('product', { perPage: 12, startingPage: 1 });
},
infinityModelUpdated({ lastPageLoaded, totalPages, newObjects }) {
Ember.Logger.debug('updated with more items');
},
infinityModelLoaded({ totalPages }) {
Ember.Logger.info('no more items to load');
}
}Chances are you'll want to scroll some source other than the default ember-data store to infinity. You can do that by injecting your store into the route and specifying the store to the infinityModel options:
import { inject as service } from '@ember/service';
export default Ember.Route.extend({
infinity: service(),
customStore: service('my-custom-store'),
model(params) {
return this.infinity.model('product', {
perPage: 12,
startingPage: 1,
store: this.customStore, // custom ember-data store or ember-redux / ember-cli-simple-store / your own hand rolled store (see dummy app)
storeFindMethod: 'findAll' // should return a promise (optional if custom store method uses `query`)
})
}
});The infinity-loader component as some extra options to make working with it easy! It is based on the IntersectionObserver API. In essence, instead of basing your scrolling on Events (synchronous), it instead behaves asynchronously, thus not blocking the main thread.
https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API
- infinityLoad
Closure actions are enabled in the 1.0.0 series.
- hideOnInfinity
Now, when the Infinity Model is fully loaded, the infinity-loader will hide itself.
Versions less than 1.0.0 called this property destroyOnInfinity
- developmentMode
This simply stops the infinity-loader from fetching triggering loads, so that
you can work on its appearance.
- loadingText & loadedText
By default, the infinity-loader will just output a span showing its status.
- Providing a block
If you provide a block to the component, it will render the block instead of
rendering loadingText or loadedText. This will allow you to provide your
own custom markup or styling for the loading state.
- reached-infinity Class Name
.infinity-loader {
background-color: wheat;
&.reached-infinity {
background-color: lavender;
}
}
When the Infinity Model loads entirely, the reached-infinity class is added to the
component.
- infinity-template Generator
ember generate infinity-template
Will install the default infinity-loader template into your host app, at
app/templates/components/infinity-loader.
- scrollable
You can optionally pass in a CSS style selector string. If not present, scrollable will default to using the window. This is useful for scrollable areas that are constrained in the window.
- loadPrevious
- triggerOffset
You can optionally pass an offset value. This value will be used when calculating if the bottom of the scrollable has been reached.
- eventDebounce
Default is 50ms. You can optionally pass a debounce time to delay loading the list when reach bottom of list
You can use the route loading magic of Ember Infinity without using the InfinityLoader component.
load-more-button.js:
export default Ember.Component.extend({
loadText: 'Load more',
loadedText: 'Loaded',
click: function(){
this.sendAction('action', this.get('infinityModel'));
}
});load-more-button.hbs:
template.hbs:
template.hbs:
The basic idea here is to:
- Place an infinity-loader component above and below your content.
- Ensure loadPrevious is set to true on the infinity-loader above the content.
If your route loads on page 3, it will fetch page 2 on load. As the user scrolls up, it will fetch page 1 and stop loading from there. If you are already on page 1, no actions will be fired to fetch the previous page.
Testing can be a breeze once you have an example. So here is an example! Note this is using Ember's new testing APIs.