Skip to content
This repository has been archived by the owner on Apr 6, 2019. It is now read-only.

Commit

Permalink
Small spelling and punctuation fixes
Browse files Browse the repository at this point in the history
  • Loading branch information
Travis authored and Travis committed Dec 12, 2014
1 parent 011ff9f commit 9a9cd05
Showing 1 changed file with 15 additions and 17 deletions.
32 changes: 15 additions & 17 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,20 +4,20 @@ angular-once
One time bindings for AngularJS.
## Why?

AngularJS is a great framework with many superb features, but when is used to display large amount
AngularJS is a great framework with many superb features, but when it is used to display large amounts
of data, it can become quite slow due to it's binding mechanism.

When you bind data via `{{ }}` or `ng-bind` directives,
angular sets up `watch` under the cover which is being executed every time angular event loop triggers (for example after `$http` request, or keypress).
It's fine when number of bindings (pieces of dynamic information you want to display) is relatively small up to few hundreds,
but when that number increases page can become unresponsive expecially on low-end devices
angular sets up `watch` under the cover which is being executed every time an angular event loop triggers (for example after `$http` request, or keypress).
It's fine when the number of bindings (pieces of dynamic information you want to display) is relatively small up to a few hundred,
but when that number increases, page can become unresponsive; expecially on low-end devices
(it was Surface RT in my case, and reason to create that project, it was painfully slow even for 200 bindings).

There isn't much you can do about it, except displaying less data (via paging for example), but it's not always the case.
Should we wait till browsers implement [`Object.observe`](http://updates.html5rocks.com/2012/11/Respond-to-change-with-Object-observe) and AngularJS
will used it so we get [40x speed-up](https://mail.mozilla.org/pipermail/es-discuss/2012-September/024978.html)?
We could, but when your data is readonly (and in many cases is) you can use this project which sets up one time bindings
and doesn't create any watchers so is incredibly **fast**!
will use it so we get [40x speed-up](https://mail.mozilla.org/pipermail/es-discuss/2012-September/024978.html)?
We could, but when your data is readonly (and in many cases it is) you can use this project which sets up one time bindings
and doesn't create any watchers which is incredibly **fast**!

**bottom line: If you use AngularJS, have performance issues and need to display lots of readonly data, this project is for you!**

Expand All @@ -35,7 +35,7 @@ or copy once.js file.
## Usage
##### Prerequisites
* reference once.js file
* add `once` module as dependency to your app (`angular.module('yourApp', ['once'])`)
* add `once` module as adependency to your app (`angular.module('yourApp', ['once'])`)



Expand All @@ -51,9 +51,8 @@ Lets look at this standard AngularJS code snippet:
</ul>
```

Now given 100 users it's 600 watchers and list is not only information on page in most cases.
If users data needs to be only displayed not edited inline, we don't need to set up watchers in `ng-repeat` directive,
especially as user goes back and forward within the app many times list is being refreshed on each display as controller in angular are transient.
Now given 100 users (600 watchers), the list is not the only information on the page in most cases.
If user's data needs to be only displayed, and not edited inline, we don't need to set up watchers in a `ng-repeat` directive, especially as the user goes back and forth within the app many times as the list is being refreshed on each display as controller in angular are transient.

Let's look at the same example using **angular-once**:
```html
Expand All @@ -65,13 +64,13 @@ Let's look at the same example using **angular-once**:
</li>
</ul>
```
Number of watchers? **0** (actually 1 as angular uses separate watch for ng-repeat directive itself).
Number of watchers? **0** (actually 1 as angular uses a separate watch for the `ng-repeat` directive itself).

**IMPORTANT: Built in angular `ng-href` and `ng-src` directives support interpolation (`{{ }}` notation), `angular-once` doesn't due to performance reasons (avoid setting up watchers).**

## API

List below contains comparison of angular-once directives ( **one time bindings** ) with build in angular directives ( **two-way bindings** ).
List below contains comparison of angular-once directives ( **one time bindings** ) with built in angular directives ( **two-way bindings** ).

| angular-once | native angular equivalent | example usage |
| ------------- |:-------------:|:-----:|
Expand All @@ -91,18 +90,17 @@ List below contains comparison of angular-once directives ( **one time bindings*


#### Important:
One important thing to note is that when using `angular-once` and bound data is `undefined` it creates watch which waits till data is available (promise is resolved)
and then remove that watch itself. Reason for that is to be able to use it with data which is not yet available, but still readonly.
One important thing to note is that when using `angular-once` and bound data is `undefined`, it creates a watch which waits until the data is available (promise is resolved). Once the promise is resolved, the watch is removed. Reason for that is to be able to use it with data which is not yet available, but still readonly.

In case bound data contains static and dynamic part, for example `once-src="'http://placekitten.com/'+ kitty.size"` and `kitty-size` isn't
immediately available, you can use `once-wait-for` directive to wait till `kitten.size` is fetched, so it will look like:
immediately available, you can use the `once-wait-for` directive to wait untill `kitten.size` is fetched, so it will look like:
`once-src="'http://placekitten.com/'+ kitty.size" once-wait-for='kitty.size'`

## Credits
Thanks both to @Pasvaz for bindonce and @abourget for $watch fighters, as both modules were inspiration and starting point for creating this module.

## Similar projects
* [bindonce](https://github.com/Pasvaz/bindonce) - similar, but requires addtional bindonce directive which wraps other dindonce directives.
* [bindonce](https://github.com/Pasvaz/bindonce) - similar, but requires additional bindonce directives which wrap other bindonce directives.
* [watch fighters](https://github.com/abourget/abourget-angular) - similar, but doesn't handle case when there is no data yet to bind, simply binds nothing, so doesn't work with promises.

## License
Expand Down

0 comments on commit 9a9cd05

Please sign in to comment.