├── .gitignore
├── .travis.yml
├── LICENSE
├── README.md
├── bower.json
├── karma.conf.js
├── knockout-js-infinite-scroll.js
├── package.json
└── tests.js


/.gitignore:
--------------------------------------------------------------------------------
1 | node_modules/*
2 | bower_components/*
3 | coverage/*
4 | .idea*
5 | /*.project
6 | 


--------------------------------------------------------------------------------
/.travis.yml:
--------------------------------------------------------------------------------
 1 | language: node_js
 2 | 
 3 | node_js:
 4 |   - "0.10"
 5 | 
 6 | install:
 7 |   - npm install -g brunch bower
 8 |   - bower install
 9 |   - npm install
10 | 
11 | script:
12 |   - ./node_modules/karma/bin/karma start --single-run --browsers PhantomJS


--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
 1 | The MIT License (MIT)
 2 | 
 3 | Copyright (c) 2013 Baz
 4 | 
 5 | Permission is hereby granted, free of charge, to any person obtaining a copy of
 6 | this software and associated documentation files (the "Software"), to deal in
 7 | the Software without restriction, including without limitation the rights to
 8 | use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
 9 | the Software, and to permit persons to whom the Software is furnished to do so,
10 | subject to the following conditions:
11 | 
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 | 
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
17 | FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
18 | COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
19 | IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
20 | CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
21 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | Knockout JS (KO) Infinite Scroll
 2 | ===========================
 3 | 
 4 | [![Build Status](https://travis-ci.org/thinkloop/knockout-js-infinite-scroll.svg?branch=master)](https://travis-ci.org/thinkloop/knockout-js-infinite-scroll)
 5 | [![Coverage Status](https://img.shields.io/coveralls/thinkloop/knockout-js-infinite-scroll.svg)](https://coveralls.io/r/thinkloop/knockout-js-infinite-scroll?branch=master)
 6 | 
 7 | This is a KnockoutJS extender that provides infinite scroll functionality to an observable array by automatically filtering it down to only the items visible on screen. It was developed to display and scroll various long lists of complex items on [OppositeofOpposite.com](http://www.oppositeofopposite.com/), such as the main items list, the friends list and the categories list.
 8 | 
 9 | ###Example Fiddle: http://jsfiddle.net/thinkloop/7MqJ2/###
10 | 
11 | The example fiddle shows the simplest implmentation of this component, see the next sections for important in-practice tips.
12 | 
13 | ###Scale to Thousands of Items###
14 | There is an important technique that allows this to scale to many thousands of complex items. Say we were working with a Pinterest style layout, where items with heavy content are floated next to each other forever. When items scroll out of view, we can unload their expensive contents (images, comments, styling, etc.), while keeping the top-level containers to maintain document structure:
15 | 
16 | ```html
17 | <!-- ko foreach: filteredItems.infinitescroll.displayItems -->
18 |    <article class="main-item">
19 |       <!-- ko if: $index() >= $root.filteredItems.infinitescroll.firstVisibleIndex() -->
20 |          <!-- * * complex expensive content * * -->
21 |       <!-- /ko -->
22 |    </article>
23 | <!-- /ko -->
24 | ````
25 | 
26 | We compare $index to firstVisibleIndex and only render the contents of items that are actually visible on screen. This way users can scroll through many thousands of items without any performance issues, since the majority of the containers will be empty and light-weight.
27 | 
28 | 
29 | ###Bower
30 | 
31 | - `bower install git://github.com/thinkloop/knockout-js-infinite-scroll.git`
32 | 
33 | ###Run tests
34 | 
35 | Install dependencies:
36 | - install [node.js](nodejs.org)
37 | - `npm install -g bower`
38 | - `bower install`
39 | - `npm install`
40 | 
41 | Run tests: `npm test`
42 | 
43 | coverage report in html is in *coverage/*
44 | 
45 | ---
46 | 
47 | #####Don't hesitate to ask questions in issues, or star the repo if you like it!###
48 | 


--------------------------------------------------------------------------------
/bower.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "name": "knockout-js-infinite-scroll",
 3 |   "description": "Knockout JS (KO) extender that provides infinite scroll functionality to an observable array by automatically filtering it down to only the items visible on screen.",
 4 |   "homepage": "https://github.com/thinkloop/knockout-js-infinite-scroll",
 5 |   "authors": [
 6 |     "Baz <bk@thinkloop.com>"
 7 |   ],
 8 |   "license": "MIT",
 9 |   "keywords": [
10 |     "knockout",
11 |     "ko",
12 |     "infinite",
13 |     "scroll"
14 |   ],
15 |   "version": "0.1.0",
16 |   "main": "knockout-js-infinite-scroll.js",
17 |   "dependencies": {
18 |   	"knockout": "~3.2.0"
19 |   },
20 |   "devDependencies": {
21 |     "mocha": "~1.18",
22 |     "chai": "~1.9",
23 |     "sinon": "1.8.2",
24 |     "sinon-chai": "2.5.0",
25 |     "commonjs-require-definition": "~0.1.2"
26 |   },
27 |   "ignore": [
28 |     "**/.*",
29 |     "node_modules",
30 |     "bower_components",
31 |     "test",
32 |     "tests",
33 |     ".gitignore",
34 |     "README.md"
35 |   ]
36 | }
37 | 


--------------------------------------------------------------------------------
/karma.conf.js:
--------------------------------------------------------------------------------
 1 | // Karma configuration
 2 | // Generated on Wed Feb 26 2014 09:39:36 GMT+0100 (CET)
 3 | 
 4 | module.exports = function(config) {
 5 |   config.set({
 6 | 
 7 |     // base path that will be used to resolve all patterns (eg. files, exclude)
 8 |     basePath: '',
 9 | 
10 |     // frameworks to use
11 |     frameworks: ['mocha'],
12 | 
13 |     // list of files / patterns to load in the browser
14 |     files: [
15 |       'bower_components/commonjs-require-definition/require.js',
16 |       'bower_components/knockout/dist/knockout.js',
17 |       'bower_components/mocha/mocha.js',
18 |       'bower_components/chai/chai.js',
19 |       'bower_components/sinon-chai/lib/sinon-chai.js',
20 |       'bower_components/sinon/lib/sinon.js',
21 |       'knockout-js-infinite-scroll.js',
22 |       'tests.js'
23 |     ],
24 | 
25 |     // list of files to exclude
26 |     exclude: [
27 | 
28 |     ],
29 | 
30 |     // test results reporter to use
31 |     // possible values: 'dots', 'progress', 'junit', 'growl', 'coverage'
32 |     reporters: ['progress', 'coverage', 'coveralls'],
33 | 
34 |     // preprocess matching files before serving them to the browser
35 |     // available preprocessors: https://npmjs.org/browse/keyword/karma-preprocessor
36 |     preprocessors: {
37 |       'knockout-js-infinite-scroll.js': 'coverage'
38 |     },
39 | 
40 |     // test results reporter to use
41 |     // possible values: 'dots', 'progress'
42 |     // available reporters: https://npmjs.org/browse/keyword/karma-reporter
43 |     coverageReporter: {
44 |         reporters: [
45 |             {type: 'html', dir: 'coverage/'},
46 |             {type: 'lcov', dir: 'coverage/'}
47 |         ]
48 |     },
49 | 
50 |     coverallsReporter: {
51 |         repoToken: "BMoZLkpnTVMTl8BzixWMIdxYavV5xPl3G"
52 |     },
53 | 
54 |     // web server port
55 |     port: 9876,
56 | 
57 |     // enable / disable colors in the output (reporters and logs)
58 |     colors: true,
59 | 
60 | 
61 |     // level of logging
62 |     // possible values: config.LOG_DISABLE || config.LOG_ERROR || config.LOG_WARN || config.LOG_INFO || config.LOG_DEBUG
63 |     logLevel: config.LOG_INFO,
64 | 
65 |     // enable / disable watching file and executing tests whenever any file changes
66 |     autoWatch: true,
67 | 
68 |     // start these browsers
69 |     // available browser launchers: https://npmjs.org/browse/keyword/karma-launcher
70 |     browsers: ['PhantomJS'],
71 | 
72 |     // If browser does not capture in given timeout [ms], kill it
73 |     captureTimeout: 60000,
74 | 
75 |     // Continuous Integration mode
76 |     // if true, Karma captures browsers, runs the tests and exits
77 |     singleRun: true
78 |   });
79 | };
80 | 


--------------------------------------------------------------------------------
/knockout-js-infinite-scroll.js:
--------------------------------------------------------------------------------
  1 | (function (factory) {
  2 | 	// Module systems magic dance.
  3 | 
  4 |     /* istanbul ignore next - (code coverage ignore) */
  5 | 	if (typeof require === "function" && typeof exports === "object" && typeof module === "object") {
  6 | 		// CommonJS or Node: hard-coded dependency on "knockout"
  7 | 		factory(require("knockout"), exports);
  8 | 	} else if (typeof define === "function" && define["amd"]) {
  9 | 		// AMD anonymous module with hard-coded dependency on "knockout"
 10 | 		define(["knockout", "exports"], factory);
 11 | 	} else {
 12 | 		// <script> tag: use the global `ko` object
 13 | 		factory(ko, {});
 14 | 	}
 15 | }(function (ko, exports) {
 16 | 	ko.extenders.infinitescroll = function(target, args) {
 17 | 		var props = {};
 18 | 
 19 | 		target.infinitescroll = props;
 20 | 
 21 | 		props.numPagesPadding = ko.observable(parseFloat(args.numPagesPadding) || 1);
 22 | 
 23 | 		// dimensions
 24 | 		props.viewportWidth = ko.observable(-1);
 25 | 		props.viewportHeight = ko.observable(-1);
 26 | 
 27 | 		props.itemWidth = ko.observable(-1);
 28 | 		props.itemHeight = ko.observable(-1);
 29 | 
 30 | 		props.scrollY = ko.observable(0);
 31 | 
 32 | 		// if using the main browser scroller to scroll a container that is not 100% tall,
 33 | 		// the gap between the scroller height and div height is the scrollYOffset in px.
 34 | 		props.scrollYOffset = ko.observable(0);
 35 | 
 36 | 		// calculations
 37 | 		props.numColsPerPage = ko.computed(function() {
 38 | 			var viewportWidth = parseInt(props.viewportWidth()),
 39 | 				itemWidth = parseInt(props.itemWidth()) || -1;
 40 | 			return Math.max(Math.floor(viewportWidth / itemWidth), 0);
 41 | 		});
 42 | 		props.numRowsPerPage = ko.computed(function() {
 43 | 			var viewportHeight = parseInt(props.viewportHeight()),
 44 | 				itemHeight = parseInt(props.itemHeight()) || -1;
 45 | 			return Math.max(Math.ceil(viewportHeight / itemHeight), 0);
 46 | 		});
 47 | 		props.numItemsPerPage = ko.computed(function() {
 48 | 			var numColsPerPage = parseInt(props.numColsPerPage()),
 49 | 				numRowsPerPage = parseInt(props.numRowsPerPage());
 50 | 			return numColsPerPage * numRowsPerPage;
 51 | 		});
 52 | 		props.numItemsPadding = ko.computed(function() {
 53 | 			var numItemsPerPage = props.numItemsPerPage(),
 54 | 				numPagesPadding = props.numPagesPadding(),
 55 | 				numColsPerPage = props.numColsPerPage();
 56 | 			return Math.max(Math.floor(numItemsPerPage * numPagesPadding / numColsPerPage) * numColsPerPage, 0);
 57 | 		});
 58 | 		props.firstVisibleIndex = ko.computed(function() {
 59 | 			var scrollY = parseInt(props.scrollY()),
 60 | 				scrollYOffset = parseInt(props.scrollYOffset()),
 61 | 				itemHeight = parseInt(props.itemHeight()) || -1,
 62 | 				numColsPerPage = props.numColsPerPage();
 63 | 			return Math.max(Math.floor((scrollY - scrollYOffset) / itemHeight) * numColsPerPage, 0);
 64 | 		});
 65 | 		props.lastVisibleIndex = ko.computed(function() {
 66 | 			return props.firstVisibleIndex() + props.numItemsPerPage() - 1;
 67 | 		});
 68 | 		props.firstHiddenIndex = ko.computed(function() {
 69 | 			return Math.max(props.firstVisibleIndex() - 1 - props.numItemsPadding(), 0);
 70 | 		});
 71 | 		props.lastHiddenIndex = ko.computed(function() {
 72 | 			return Math.min(props.lastVisibleIndex() + 1 + props.numItemsPadding(), target().length);
 73 | 		});
 74 | 		props.heightBefore = ko.computed(function() {
 75 | 			return Math.max(props.firstHiddenIndex() / props.numColsPerPage() * props.itemHeight(), 0);
 76 | 		});
 77 | 		props.heightAfter = ko.computed(function() {
 78 | 			return Math.max(((target().length - 1 - props.lastHiddenIndex()) / props.numColsPerPage()) * props.itemHeight(), 0);
 79 | 		});
 80 | 
 81 | 		// display items
 82 | 		props.displayItems = ko.observableArray([]);
 83 | 		ko.computed(function() {
 84 | 			var oldDisplayItems = props.displayItems.peek(),
 85 | 				newDisplayItems = target.slice(0, props.lastHiddenIndex());
 86 | 
 87 | 			if (oldDisplayItems.length !== newDisplayItems.length) {
 88 | 				props.displayItems(newDisplayItems);
 89 | 				return;
 90 | 			}
 91 | 
 92 | 			// if collections are not identical, skip, replace with new items
 93 | 			for (var i = newDisplayItems.length - 1; i >= 0; i--) {
 94 | 				if (newDisplayItems[i] !== oldDisplayItems[i]) {
 95 | 					props.displayItems(newDisplayItems);
 96 | 					return;
 97 | 				}
 98 | 			}
 99 | 		});
100 | 	};
101 | }));


--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "name": "knockout-js-infinite-scroll",
 3 |   "description": "Knockout JS (KO) extender that provides infinite scroll functionality to an observable array by automatically filtering it down to only the items visible on screen.",
 4 |   "author": "Baz <bk@thinkloop.com>",
 5 |   "version": "0.1.1",
 6 |   "repository": {
 7 |     "type": "git",
 8 |     "url": "git://github.com/thinkloop/knockout-js-infinite-scroll.git"
 9 |   },
10 |   "license": "MIT",
11 |   "main": "knockout-js-infinite-scroll.js",
12 |   "devDependencies": {
13 |     "karma": "~0.12.21",
14 |     "karma-coffee-preprocessor": "~0.2.1",
15 |     "karma-coverage": "git://github.com/karma-runner/karma-coverage#a35d8d068ef",
16 |     "karma-coveralls": "^0.1.4",
17 |     "karma-mocha": "~0.1.7",
18 |     "karma-phantomjs-launcher": "^0.1.4"
19 |   },
20 |   "scripts": {
21 |     "test": "node ./node_modules/karma/bin/karma start karma.conf.js"
22 |   },
23 |   "keywords": [
24 |     "knockout",
25 |     "ko",
26 |     "infinite",
27 |     "scroll"
28 |   ]
29 | }
30 | 


--------------------------------------------------------------------------------
/tests.js:
--------------------------------------------------------------------------------
  1 | expect = chai.expect;
  2 | assert = chai.assert;
  3 | 
  4 | 
  5 | var ViewModel = function() {
  6 |     var self = this;
  7 |     self.items = ko.observableArray([]);
  8 |     self.items.extend({
  9 |         infinitescroll: {}
 10 |     });
 11 | };
 12 | 
 13 | setViewport = function (target, args)
 14 | {
 15 |     target.items.infinitescroll.viewportHeight(args.height);
 16 |     target.items.infinitescroll.viewportWidth(args.width);
 17 | }
 18 | 
 19 | setItemSize = function(target, args)
 20 | {
 21 |     target.items.infinitescroll.itemHeight(args.height);
 22 |     target.items.infinitescroll.itemWidth(args.width);
 23 | }
 24 | 
 25 | 
 26 | describe('Infinitescroll - not scrolled, no page-padding -', function() {
 27 |   var target, itemDim;
 28 |   beforeEach(function() {
 29 |     target = new ViewModel();
 30 |     target.items.infinitescroll.numPagesPadding(0);
 31 |     itemDim = 10;
 32 |     target.items(['item1', 'item2', 'item3', 'item4', 'item5']);
 33 |     setItemSize(target, {height: itemDim, width: itemDim});
 34 |   });
 35 |   it('should display no items initially', function() {
 36 |     expect(target.items.infinitescroll.displayItems()).to.have.length(0);
 37 |   });
 38 |   it('should display 1 item when grid is 1x1', function() {
 39 |     setViewport(target, {height: 1*itemDim, width: 1*itemDim});
 40 |     expect(target.items.infinitescroll.numRowsPerPage()).to.equal(1);
 41 |     expect(target.items.infinitescroll.numColsPerPage()).to.equal(1);
 42 |     expect(target.items.infinitescroll.displayItems()).to.have.length(1);
 43 |   });
 44 |   it('should display 2 items when grid is 2x1', function() {
 45 |     setViewport(target, {height: 2*itemDim, width: 1*itemDim});
 46 |     expect(target.items.infinitescroll.numRowsPerPage()).to.equal(2);
 47 |     expect(target.items.infinitescroll.numColsPerPage()).to.equal(1);
 48 |     expect(target.items.infinitescroll.displayItems()).to.have.length(2);
 49 |   });
 50 |   it('should display 2 items when grid is 1x2', function() {
 51 |     setViewport(target, {height: 1*itemDim, width: 2*itemDim});
 52 |     expect(target.items.infinitescroll.numRowsPerPage()).to.equal(1);
 53 |     expect(target.items.infinitescroll.numColsPerPage()).to.equal(2);
 54 |     expect(target.items.infinitescroll.displayItems()).to.have.length(2);
 55 |   });
 56 |   it('should display 4 items when grid is 2x2', function() {
 57 |     setViewport(target, {height: 2*itemDim, width: 2*itemDim});
 58 |     expect(target.items.infinitescroll.numRowsPerPage()).to.equal(2);
 59 |     expect(target.items.infinitescroll.numColsPerPage()).to.equal(2);
 60 |     expect(target.items.infinitescroll.displayItems()).to.have.length(4);
 61 |   });
 62 |   it('should display 3 items when grid is 2x2 and only exist 3 items', function() {
 63 |     setViewport(target, {height: 2*itemDim, width: 2*itemDim});
 64 |     target.items(['item1', 'item2', 'item3']);
 65 |     expect(target.items.infinitescroll.numRowsPerPage()).to.equal(2);
 66 |     expect(target.items.infinitescroll.numColsPerPage()).to.equal(2);
 67 |     expect(target.items.infinitescroll.displayItems()).to.have.length(3);
 68 |   });
 69 |   it('should update displayed items when updating an item', function() {
 70 |     setViewport(target, {height: 2*itemDim, width: 2*itemDim});
 71 |     expect(target.items.infinitescroll.numRowsPerPage()).to.equal(2);
 72 |     expect(target.items.infinitescroll.numColsPerPage()).to.equal(2);
 73 |     expect(target.items.infinitescroll.displayItems()).to.have.length(4);
 74 |     target.items()[1] = 'newItem2';
 75 |     target.items.valueHasMutated();
 76 |     expect(target.items.infinitescroll.displayItems()[1]).to.equal('newItem2');
 77 |   });
 78 | });
 79 | 
 80 | 
 81 | describe('InfiniteScroll - scrolled, no page-padding - ', function() {
 82 |   beforeEach(function() {
 83 |     target = new ViewModel();
 84 |     target.items.infinitescroll.numPagesPadding(0);
 85 |     itemDim = 10;
 86 |     target.items(['item1', 'item2',
 87 |                   'item3', 'item4',
 88 |                   'item5', 'item6',
 89 |                   'item7', 'item8',
 90 |                   'item9', 'item10']);
 91 |     setItemSize(target, {height: itemDim, width: itemDim});
 92 |     setViewport(target, {height: 2*itemDim, width: 2*itemDim});
 93 |     expect(target.items.infinitescroll.numRowsPerPage()).to.equal(2);
 94 |     expect(target.items.infinitescroll.numColsPerPage()).to.equal(2);
 95 |     expect(target.items.infinitescroll.numItemsPadding()).to.equal(0);
 96 |   });
 97 |   it('should keep items above, when scroll beyond them', function() {
 98 |     var firstVisibleRow = 3;
 99 |     target.items.infinitescroll.scrollY(firstVisibleRow*itemDim);
100 |     expect(target.items.infinitescroll.displayItems()[0]).to.equal('item1');
101 |   });
102 |   it('should exclude items below, when not scrolled far enough to include them', function() {
103 |     var firstVisibleRow = 1;
104 |     target.items.infinitescroll.scrollY(firstVisibleRow*itemDim);
105 |     expect(target.items.infinitescroll.displayItems()[0]).to.equal('item1');
106 |     expect(target.items.infinitescroll.displayItems()[5]).to.equal('item6');
107 |     expect(target.items.infinitescroll.displayItems()).to.have.length(6);
108 |   });
109 | });
110 | 
111 | 
112 | describe('InfiniteScroll - scrolled, with page-padding - ', function() {
113 |   beforeEach(function() {
114 |     target = new ViewModel();
115 |     target.items.infinitescroll.numPagesPadding(2);
116 |     itemDim = 10;
117 |     target.items(['item1', 'item2',
118 |                   'item3', 'item4',
119 |                   'item5', 'item6',
120 |                   'item7', 'item8',
121 |                   'item9', 'item10',
122 |                   'item11', 'item12',
123 |                   'item13', 'item14',
124 |                   'item15', 'item16',
125 |                   'item17', 'item18']);
126 |     setItemSize(target, {height: itemDim, width: itemDim});
127 |     setViewport(target, {height: 2*itemDim, width: 2*itemDim});
128 |     expect(target.items.infinitescroll.numRowsPerPage()).to.equal(2);
129 |     expect(target.items.infinitescroll.numColsPerPage()).to.equal(2);
130 |     expect(target.items.infinitescroll.numItemsPadding()).to.equal(8);
131 |   });
132 |   it('first hidden index should be page-padded', function() {
133 |     var firstVisibleRow = 6;
134 |     target.items.infinitescroll.scrollY(firstVisibleRow*itemDim);
135 |     // item13, item14 on row6, one page is 2x2, two pages up is on item5, first hidden is item4 = index 3
136 |     expect(target.items.infinitescroll.firstHiddenIndex()).to.equal(3);
137 |   });
138 |   it('last hidden index should be page-padded', function() {
139 |     var firstVisibleRow = 1;
140 |     target.items.infinitescroll.scrollY(firstVisibleRow*itemDim);
141 |     // item3, item4 on row1, grid is 2x2, so item5, item6 is in the view
142 |     // two pages down from item6 is item14, first hidden is therefore item15 = index 14
143 |     expect(target.items.infinitescroll.lastHiddenIndex()).to.equal(14);
144 |   });
145 | });
146 | 


--------------------------------------------------------------------------------