From 28d9c69513ab50ab64a5304fffb6805c4f7cf2c0 Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Sun, 22 Mar 2015 19:07:35 -0400 Subject: [PATCH] Updated README.md to use EmberCLI semantics - Renamed to *Ember List* - Changed examples to assume EmberCLI - Changed installation to use EmberCLI - Changed Handlebars examples to use {{ember-list}} helper Changed List View to ListView Changed title of the readme Changed Ember Virtual List -> VirtualListView Updated example to use {{view 'list-view'}} instead of {{ember-list}} --- README.md | 151 +++++++++++++++++++++++++----------------------------- 1 file changed, 69 insertions(+), 82 deletions(-) diff --git a/README.md b/README.md index e4808a6..b4ee311 100755 --- a/README.md +++ b/README.md @@ -1,10 +1,10 @@ -# Ember.ListView [![Build Status](https://secure.travis-ci.org/emberjs/list-view.png?branch=master)](http://travis-ci.org/emberjs/list-view) +# ListView [![Build Status](https://secure.travis-ci.org/emberjs/list-view.png?branch=master)](http://travis-ci.org/emberjs/list-view) An efficient incremental rendering list view for large lists. -`Ember.ListView` works on major modern browsers and also on major mobile devices (iOS, Android). However, there are known issues with using `Ember.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 `Ember.ListView` needs to capture. Also, if the browser is under heavy load, it can just stop emitting some events. +*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 `Ember.VirtualListView` that does the momentum scroll entirely in JS. However, note that `Ember.VirtualListView` doesn't have a native scroll bar. This is something that we need to work on for future releases of `Ember.ListView` +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 @@ -22,10 +22,10 @@ Latest: ## Dependencies -Both `Ember.ListView` and `Ember.VirtualListView` need [jquery](http://jquery.com/), +Both *ListView* and *VirtualListView* need [jquery](http://jquery.com/), [handlebars](http://handlebarsjs.com), [ember.js](http://emberjs.com). -`Ember.VirtualListView` need an additional dependency: [zynga scroller](https://github.com/zynga/scroller). +*VirtualListView* need an additional dependency: [zynga scroller](https://github.com/zynga/scroller). ## Demo @@ -39,54 +39,25 @@ It would help us greatly to help you and to improve ember list view. ## Installation -Since `ember-cli` is in transition right now, these instructions are for -those of you using *version 0.0.44 or below*. +Install *ListView* with EmberCLI using this command. -1. You need to build `list-view`, so in your projects directory: - - ```bash - git clone git@github.com:emberjs/list-view.git - cd list-view - npm install - npm run build-all - ``` - -2. In your project that you want to use `list-view` in: - - ```bash - mkdir vendor/list-view - ``` - - then copy the built `list-view` - Javascript file from your clone's subdirectory `dist/list-view.js` to - your project's `vendor/list-view` folder above. - -3. Add the line: - - ```javascript - "list-view": "0.0.5" - ``` - - to your `devDependencies` hash in your project's `package.json` file. +```bash +ember install:addon ember-list +``` ## Usage First, let's create a template: -``` html - +```handlebars +{{#view 'list-view' items=model height=500 rowHeight=50 width=500}} + {{name}} +{{/view}} ``` Next, let's feed our template with some data: ``` javascript -// create Ember application -App = Ember.Application.create(); - -// define default index route and pushing some data to content -App.IndexRoute = Ember.Route.extend({ +// 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++) { @@ -101,24 +72,43 @@ 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 ```Ember.ListView```. +Here's an example of how to create your version of *ListView*. -``` html - +Create a **my-list.js** in your project's **/views** directory. - ``` +// in views/my-list.js -``` javascript -// create Ember application -App = Ember.Application.create(); +import ListView from 'list-view/list-view'; +import ListItemView from '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. + +```handlebars +{{view 'my-list' items=model}} +``` + +Create a **my-list-item.hbs** in your project's **/templates** directory. + +```handlebars +{{name}} +``` + +Return data from your route's model hook. +```javascript // define default index route and pushing some data to content -App.IndexRoute = Ember.Route.extend({ +export default Ember.Route.extend({ model: function() { var items = []; for (var i = 0; i < 10000; i++) { @@ -127,53 +117,49 @@ App.IndexRoute = Ember.Route.extend({ return items; } }); - -// extending Ember.ListView -// customize the row views by subclassing Ember.ListItemView -// and specifying the itemViewClass property in the Ember.ListView definition -App.ListView = Ember.ListView.extend({ - height: 500, - rowHeight: 50, - itemViewClass: Ember.ListItemView.extend({templateName: "row_item"}) -}); ``` -Unfortunately, if you want to customize item template, you would have to use ```Ember.ListItemView``` -and create an additional template, as you see above. You cannot specify ```templateName``` paramter -directly on ```Ember.ListView``` because it's derived from ```Ember.ContainerView``` and it cannot have a template. +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 ```Ember.ListView``` during runtime +### Changing height and width of *ListView* during runtime -The height and width of the entire ```Ember.ListView``` can be adjusted at run-time. -When this occurs the ```Ember.ListView``` will transform existing view items to the new locations, +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. ``` javascript -App.ListView = Ember.ListView.extend({ +import ListView from 'list-view/list-view'; + +export default ListView.extend({ height: 500, width: 960, - adjustLayout: function(new_width, new_height) { - this.set('width', new_width); - this.set('height', new_height); + adjustLayout: function(newWidth, newHeight) { + this.set('width', newWidth); + this.set('height', newHeight); } }); ``` ### Required parameters -You must specify the ```height``` and ```rowHeight``` parameters because ```Ember.ListView``` will try +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 -```elementWidth```, as well as ```width```. +`element-width`, as well as `width`. ``` javascript -App.ListView = Ember.ListView.extend({ +import ListView from 'list-view/list-view'; +import ListItemView from 'list-view/list-item-view'; + +export default ListView.extend({ height: 500, rowHeight: 50, elementWidth: 80, width: 500, - itemViewClass: Ember.ListItemView.extend({templateName: "row_item"}) + itemViewClass: ListItemView.extend( { templateName: "row-item" } ) }); ``` @@ -188,16 +174,17 @@ App.ListView = Ember.ListView.extend({ 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) -5. `npm run build-all` +5. `ember build` ## How it works -`Ember.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. +*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](https://github.com/emberjs/list-view/blob/master/tests/unit/list-view-test.js) for more information. @@ -212,7 +199,7 @@ npm test 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](http://jsfiddle.net/SPZn4/2/). +* `classNameBindings` and `attributeBindings` won't work properly on `ListItemView` after view's recycle. Using it should be avoided. [Demo](http://jsfiddle.net/SPZn4/2/). ## Thanks