Nickelback Plays Music

    ember-list-view

    0.0.6 • Public • Published

    ListView Build Status

    An efficient incremental rendering list view for large lists.

    ListView works on major modern browsers and also on major mobile devices (iOS, Android). However, there are known issues with using ListView on mobile web (if you have a long list and you're touch-scrolling it very fast, you'll see that items in your list start to disappear and after some lag appear again). That happens because some mobile browsers do not emit scroll events during the momentum scroll phase that ListView needs to capture. Also, if the browser is under heavy load, it can just stop emitting some events.

    If you do experience this problem. We offer an API compatible VirtualListView that does the momentum scroll entirely in JS. However, note that VirtualListView doesn't have a native scroll bar. This is something that we need to work on for future releases of ListView

    Downloads

    Latest:

    Table of Contents

    1. Usage
    2. Subclassing
    3. Build it
    4. How it works
    5. Run unit tests
    6. Caveats

    Dependencies

    Both ListView and VirtualListView need jquery, handlebars, ember.js.

    VirtualListView need an additional dependency: zynga scroller.

    Demo

    Please, take a look at our live demo and jsbin links: first and second.

    Submitting bugs

    Please, attach code samples or links to jsbin or jsfiddle. It would help us greatly to help you and to improve ember list view.

    Installation

    Install ListView with EmberCLI using this command.

    ember install:addon ember-list-view

    Usage

    First, let's create a template:

    {{#view 'list-view' items=model height=500 rowHeight=50 width=500}}
      {{name}}
    {{/view}}

    Next, let's feed our template with some data:

    // define index route and return some data from model
    export default Ember.Route.extend({
      model: function() {
        var items = [];
        for (var i = 0; i < 10000; i++) {
          items.push({name: "Item " + i});
        }
        return items;
      }
    });

    Shazam! You should be able to see a scrollable area with 10,000 items in it.

    Subclassing

    Here's an example of how to create your version of ListView.

    Create a my-list.js in your project's /views directory.

    // in views/my-list.js
    
    import ListView from 'ember-list-view';
    import ListItemView from 'ember-list-view/list-item-view';
    
    // extending ListView
    // customize the row views by subclassing ListItemView
    // and specifying the itemViewClass property in the Ember.ListView definition
    export default ListView.extend({
      height: 500,
      rowHeight: 50,
      itemViewClass: ListItemView.extend({templateName: "my-list-item"})
    });
    

    Use the {{view}} helper in your template.

    {{view 'my-list' items=model}}

    Create a my-list-item.hbs in your project's /templates directory.

    {{name}}

    Return data from your route's model hook.

    // define default index route and pushing some data to content
    export default Ember.Route.extend({
      model: function() {
        var items = [];
        for (var i = 0; i < 10000; i++) {
          items.push({name: "Item " + i});
        }
        return items;
      }
    });

    Unfortunately, if you want to customize item template, you would have to use ListItemView and create an additional template, as you see above. You cannot specify templateName parameter directly on ListView because it's derived from Ember.ContainerView and it cannot have a template.

    Changing height and width of ListView during runtime

    The height and width of the entire ListView can be adjusted at run-time. When this occurs the ListView will transform existing view items to the new locations, and create and position any new view items that might be needed. This is meant to make resizing as cheap as possible.

    import ListView from 'ember-list-view';
     
    export default ListView.extend({
      height: 500,
      width: 960,
      adjustLayout: function(newWidth, newHeight) {
        this.set('width', newWidth);
        this.set('height', newHeight);
      }
    });

    Required parameters

    You must specify the height and row-Height parameters because ListView will try to fill visible area with rows. If you would like to have multiple columns, then you need to specify element-width, as well as width.

    import ListView from 'ember-list-view';
    import ListItemView from 'ember-list-view/list-item-view';
     
    export default ListView.extend({
      height: 500,
      rowHeight: 50,
      elementWidth: 80,
      width: 500,
      itemViewClass: ListItemView.extend( { templateName: "row-item" } )
    });

    Required CSS

    .ember-list-view {
      overflow: auto;
      position: relative;
    }
    .ember-list-item-view {
      position: absolute;
    }

    Build It

    1. git clone https://github.com/emberjs/list-view.git
    2. cd list-view
    3. npm install (implicitly runs bower install as a postinstall)
    4. ember build

    How it works

    ListView will create enough rows to fill the visible area (as defined by the height property). It reacts to scroll events and reuses/repositions the rows as scrolled.

    Please look at the unit tests for more information.

    Running unit tests

    npm install
    npm test

    Caveats

    Things we are aware about and are on the list to fix.

    • classNameBindings and attributeBindings won't work properly on ListItemView after view's recycle. Using it should be avoided. Demo.

    Thanks

    A lot of the work was sponsored by Yapp Labs.

    Keywords

    Install

    npm i ember-list-view

    DownloadsWeekly Downloads

    20

    Version

    0.0.6

    License

    MIT

    Last publish

    Collaborators

    • stefanpenner
    • taras
    • tce