ampersand-grid-view
v0.9.0
Published
A collection backed grid view.
Downloads
3
Readme
ampersand-grid-view
A collection backed grid view.
This is not quite a 1.0 release, but it's pretty close. It works for the simple cases.
What it does
The grid view takes a container and an ampersand-collection and renders it into a grid with a set number of columns. Items will be rendered into the currently shortest column. Hence this module can be used to create a Pinterest-like grid of items.
Usage
var AmpGridView = require('ampersand-grid-view');
var data = new AmpersandCollection(); // Create a collection containing your models
var MyView = require('./my-model-view');
var gridView = new AmpGridView({
view: MyView,
collection: data,
el: document.querySelector('.some-container'),
columnCount: 3,
gutter: 10,
viewOptions: {
// additional properties passed to new views.
}
});
This will create a grid of three columns with 10px spacing between each view.
Each model in the collection data
will be represented by the view MyView
.
If more models are added to the collection they will automatically render into the view.
Async Views
Views can be asynchronous, meaning, you can tell the grid that you do not want
to be inserted right after rendering. But rather at some point later. You do
this by adding a property async
to your view and set it to true
. Then
have the view emit a ready
event when it is ready to be drawn into the grid.
This is useful when you are rendering images of unknown sizes for example. Since the grid has to know the height of the view being rendered it can't just insert it into the grid and have the image load later, this will cause overlapping.
module.exports = AmpersandView.extend({
async: true,
done: false,
template: function () {
return someTemplateThatHasAnImage;
},
render: function initPostView() {
this.renderWithTemplate(this);
var self = this;
// Star loading image
var image = new Image();
image.src = this.model.image;
// Upon success set our imageUrl property to the URL and have
// bindings update the src attribute.
// Then set `async` to false to prevent consecutive renders if the grid
// reflows for example
image.onload = function imageLoaded() {
self.imageUrl = image.src;
self.trigger('ready');
self.async = false;
};
image.onerror = function imageError() {
// You could remove the image here and render the view anyway. Or replace
// it with some standard image.
self.trigger('ready');
self.async = false;
};
},
});
Note that currently there is not way to ensure ordering of views in async mode unless you keep track outside of the grid view yourself. This will be fixed in the future though.
Responsive Web Design
If you need to change the number of colums based on the window size for example
you can do this by hooking up an event listener on the resize
event of the
window
object. Then set the property columnCount
on the grid view and call
the reflow()
method.
The grid view won't handle anything like this automatically.
A view will always be the container's width divided by column count. So you can
adjust the views widths by setting the width of the container yourself and
adjusting the gutter
property.
Endless Scrolling
If you want endless scrolling you can just listen to the scroll event yourself and then when the user reaches the bottom you load more models and add them to the collection. They will automatically render in the grid.
You could use my toBottom module for this.
Different Views
If you have different kinds of models in you collection and need to render
different kinds of views you can set the view
option to an object where the
keys match model.type || model.getType()
and the value is a matching view
constructor.
Performance Concernts
All the views will be absolutely positioned within it's container. This is to make the layout job for the browser easier. DOM operations are also somewhat grouped together to decrease the repaints etc necessary.
License
MIT