margru / angular-vs-repeat

Virtual Scroll for AngularJS ngRepeat directive

angular-vs-repeat v1.0.0-rc5

Virtual Scroll for AngularJS ngRepeat directive

Demo: http://kamilkp.github.io/angular-vs-repeat/

You can find the source code for this demo on branch "gh-pages".

Changelog: https://github.com/kamilkp/angular-vs-repeat/blob/master/CHANGELOG.md

###DESCRIPTION: vsRepeat directive stands for Virtual Scroll Repeat. It turns a standard ngRepeated set of elements in a scrollable container into a component, where the user thinks he has all the elements rendered and all he needs to do is scroll (without any kind of pagination - which most users loath) and at the same time the browser isn't overloaded by that many elements/angular bindings etc. The directive renders only so many elements that can fit into current container's clientHeight/clientWidth.

###LIMITATIONS:

• current version only supports an Array as a right-hand-side object for ngRepeat
• all rendered elements must have the same height/width or the sizes of the elements must be known up front

###USAGE: First include vs-repeat as a module dependency in your app. In order to use the vsRepeat directive you need to place a vs-repeat attribute on a direct parent of an element with ng-repeat example:

<div vs-repeat>
	<div ng-repeat="item in someArray">
		<!-- content -->
	</div>
</div>

You can also measure the single element's height/width (including all paddings and margins), and then speficy it as a value of the attribute 'vs-repeat'. This can be used if one wants to override the automatically computed element size. example:

<div vs-repeat="50">	<!-- the specified element height is 50px -->
	<div ng-repeat="item in someArray">
		<!-- content -->
	</div>
</div>

• the vsRepeat directive must be applied to a direct parent of an element with ngRepeat
• the value of vsRepeat attribute is the single element's height/width measured in pixels. If none provided, the directive will compute it automatically

###OPTIONAL PARAMETERS (attributes):

• vs-scroll-parent="selector" - selector to the scrollable container. The directive will look for a closest parent matching the given selector (defaults to the current element)
• vs-offset-before="value" - top/left offset in pixels (defaults to 0)
• vs-offset-after="value" - bottom/right offset in pixels (defaults to 0)
• vs-horizontal - horizontal mode (the ngRepeat'ed elements should be horizontally stacked)
• vs-excess="value" - an integer number representing the number of elements to be rendered outside of the current container's viewport (defaults to 2)
• vs-size-property="propertyName" - a property name of the items in collection that is a number denoting the element size (in pixels)
• vs-autoresize - use this attribute without vs-size-property and without specifying element's size. The automatically computed element style will readjust upon window resize if the size is dependable on the viewport size
• vs-scroll-settings - an object with 2 possible properties: scrollIndex: "value" - index of the item that should be scrolled to; the exact position of this item in the viewport may be further defined by scrollIndexPosition: "value" - a position where the element at scrollIndex index will be scrolled to; either a number of pixels or one of the following strings: 'top', 'middle', 'bottom', 'inview' is the same as 'inview#top', 'inview#middle', 'inview#bottom', 'inview#auto'; the 'inview#<position>' settings means that if the item is already in the view, nothing is scrolled, but if it is not, then the item will be scrolled accordingly (to be in the <position>); position 'auto' means that it will be either 'top' or 'bottom' depending on what is closer to the current item position

###EVENTS:

• vsRepeatTrigger - an event the directive listens for to manually trigger reinitialization; it may receive additional argument - an object with following properties:

1. scrollIndex and scrollIndexPosition - their meaning is the same as in the optional attribute vs-scroll-settings
2. elementSize - set the size in pixels of each element in the reinitialized list

• vsRepeatReinitialized - an event the directive emits upon reinitialization done; the listener may accepts three arguments: event, startIndex and endIndex