Skip to content

Commit

Permalink
update readme.
Browse files Browse the repository at this point in the history
  • Loading branch information
wesjones committed Dec 5, 2013
1 parent d88fad9 commit 7d47975
Showing 1 changed file with 69 additions and 26 deletions.
95 changes: 69 additions & 26 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,35 +1,78 @@
## Concept 1 ##
recycle rows down.
## ListView ##
----------
**Highly performant list and datagrid for AngularJS** designed for mobile devices which just makes it all the better on a desktop.

- take scroll offset into consideration.
- check to see how far a row will need to be moved.
- if the row needs to be moved less than half of the visible area then move dom from top to bottom.
- else adjust every row in a renderAll pattern.
- scrolling will use scrollTop and adjust the speed for a smooth scrolling experience.
Most lists work with recycled or just in time created rows for long lists in angular. **ListView doesn't work that way because in order to get a smooth scrolling experience on a mobile device you need to allow the browser to handle the scrolling as much as possible**. So to accomplish this ListView works on a chunking algorithm to create pieces as they come into view, but never destroy them until the whole grid is destroyed. This allows the scrolling experience to be smooth because GPU is leveraged from the browser as the dom is considered to be static until in view.

## Concept 2 ##
render pages at a time.
Of course since this is angular there is then the issue with a **digest being too expensive. This is not a problem** because all rows are disabled from the digest when out of view and enabled when in view. So they don't loose their scopes or have to create new ones constantly, but only once. Then **they are just enabled or disabled as they come into view**.

- render a page. When scrolled past that page, show an infinite scroll and then show the new results.
- Keep up to 2 pages in dom. So that as you scroll to load the 3rd. Drop the first on render of the 3rd page.
- To optimize digests. Deactivate rows that are not currently visible.
- This would allow the pages to be long. As in up to 100 or so per page.
- [Demos](https://rawgithub.com/webux/ux-listView/master/samples/index.html)
- [Unit Tests](https://rawgithub.com/webux/ux-listView/master/test/index.html)

## Concept 3 (cannot see stuff as it goes by) ##
## What makes this list/datagrid different? ##
Chunking is the concept of **grouping the dom elements in hierarchies** so that the browser does not calculate the position of every element when one changes, but only those in that container, it's parents in it's container, and so on up the chain. The smaller the groups the less the browser has to redraw, size, and position elements because it can just move the parent of necessary. **This works regardless of rows all having the same heights or dynamic heights as long as there is a template for each different height.**

- large div on top and bottom to push for height of scrollbar.
- rows that are not visible are display none so no heights are calculated.
- heights have an initial calculation to determine position. recalculated when digested.
Using this concept listView is able to **create many more rows** that are listed natively **like static html and allows the browser to use GPU snapshots to keep scrolling smooth**. Dynamic changes cause repaints that are expensive, so this avoids that.

## Concept 4 * ##
**Chunking doesn't have to create them all** though. To make sure the listView could start up and jump to any section quickly it needed to be able to only put in chunks that are in view. So once a chunk is requested it will be created if it was not already. This makes it so that a list of 50,000 items can still start up quickly and jump to any location and scroll as smooth as glass on your mobile device.

- all rows are absolute
- position them with heights calculated from the template before initial innerHTML.
- then no resize events because they are all in place.
## Time to get your hands dirty! ##
ListView uses the concept of templates for your rows. You can have as many templates as you like. You can even overwrite the templateModel for one of your own as long as you implement the same API. You just need to assign it as an addon. (We will discuss those later).

## Concept 5 ** ##
First we will create the directive and assign it an array so it has something to display.

- container chunks to break down the amount of dom that is shown.
- this will make it so that it doesn't resize all 5000, but just ones in the visible containers, and then adjusts the containers.
- combined with concept 3 then we would be able to hide chunks that are out of view and then display before they come into view making a top and bottom spacer that will take up all of the space above and below to prevent having additional resizes.
- this could make this support MANY more rows.
<div ux-list-view="items"></div>

These items are read from the scope that the listView exists in. It will then take that data and convert it into a normalized array so it can display every item. This does nothing for single dimentional arrays, but for arrays that are multi-dimentional it creates a single array of those based on the grouped property.

Grouped property is for reading a hiearchy. If you have an object with the property children that is an array, then "children" would be your grouped property for the datagrid to read it. See this example for use of grouped data. [Grouped Data Example](https://rawgithub.com/webux/ux-listView/master/samples/lotsOfRows/index.html)

In most cases your datagrid will look similar to this one below.

<div ux-list-view="items">
<script type="template/html" data-template-name="default" data-template-item="item">
<div class="row">{{item}}</div>
</script>
</div>

What is really happening here is that the directive is setup with a script template inside of it. The script template allows the contents of it to be read as a string rather than be interpreted as dom by the browser. So it makes a very convenient way of writing out your row templates.

The script template has 3 properties.

- **type="template/html"** it uses this to match on. So if you don't get it right might not work. This is required.
- **template-name** if this is not defined it will be changed to 'default'. So this one is not required if you only have one template, but if you have more than one the second will overwrite the first without this property.
- **template-item** this is what you want the data to be referenced by on the row scope. Such as in angular if you do a repeat with "item in items" you then reference item in your template. This does the same thing with this property.

## Addons ##
Addons are like a plugin to the listView. It actually becomes a behavior modifier of the listView object. Addons are created as factories and applied directly to the listView instance. The internals of the listView are constructed with addons as well.

Because these addons assign themselves as behaviors to the instance behaviors can be overwritten. So if you need to modify core behavior then go right ahead and add an addon that overwrites those methods.

**How to create an addon**
Addons are factories that modify the behavior. To create an addon you just need to create the factory and then add it to the dom.

angular.module('ux').factory('listViewVersion', function () {
return function (listView) {
listView.version = "0.1.0";
};
});

Now we need to add it to the dom.

<div ux-list-view="items" data-addons="listViewVersion">...</div>

Now when this listView is created it will call the "listViewVersion" factory and pass to it the listView instance so that it can be modified.

Any public methods can be overwritten allowing you to change internal behavior. Not all methods are public, but hopefully the ones you need.

It is also handy to have addons that will update based on events. Here is an example of an addon that updates based off of some events that the listView will throw. For this example we will assume we are waiting for some data to load asynchronously through a service. So we want a spinner until the data is loaded.

angular.module('ux').factory('listLoader', function () {
return function (listView) {
listView.unwatchers.push(listView.scope.$on(ux.listView.events.AFTER_UPDATE_WATCHERS, function () {
if (listView.data.length) {
alert('loading is complete');
}
}))
};
})

0 comments on commit 7d47975

Please sign in to comment.