kylefang/angular.js
1
0
Fork 0
mirror of https://github.com/zhigang1992/angular.js.git synced 2026-05-12 11:21:35 +08:00
Code Issues Packages Projects Releases Wiki Activity

new batch of docs

Browse Source
This commit is contained in:
Igor Minar
2011-06-06 08:50:35 -07:00
parent 5533e48dea
commit 7f1e2e4846
76 changed files with 5363 additions and 931 deletions
Download Patch File Download Diff File Expand all files Collapse all files

153
docs/content/misc/contribute.ngdoc
View File

@@ -2,14 +2,10 @@
@name Contributing
@description
<a name="H1_1"></a>
# Open Source
`Angular` is an open source project licensed under the {@link
http://github.com/angular/angular.js/blob/master/LICENSE MIT license}. Your contributions are
always welcome. When working with `angular` source base, please follow the guidelines provided on
this page.
* <a href="#H1_1">License</a>
* <a href="#H1_2">Contributing to Source Code</a>
* <a href="#H1_3">Applying Code Standards</a>
* <a href="#H1_4">Checking Out and Building `Angular`</a>
@@ -17,217 +13,348 @@ this page.
<a name="H1_1"></a>
# License
`Angular` is an open source project licensed under the {@link
http://github.com/angular/angular.js/blob/master/LICENSE MIT license}. Your contributions are
always welcome. When working with `angular` source base, please follow the guidelines provided on
this page.
<a name="H1_2"></a>
# Contributing to Source Code
We'd love for you to contribute to our source code and to make `angular` even better than it is
today! Here are the guidelines we'd like you to use:
* Major changes that you intend to contribute to the project must be discussed first on our {@link
https://groups.google.com/forum/?hl=en#!forum/angular mailing list} so that we can better
coordinate our efforts, prevent duplication of work, and help you to craft the change so that it
is successfully accepted upstream.
* Small changes and bug fixes can be crafted and submitted to Github as a <a href="#H1_5">pull
request</a>.
<a name="H1_3"></a>
# Applying Code Standards
To ensure consistency throughout the source code, keep these rules in mind as you are working:
* All features or bug fixes must be tested by one or more <a href="#unit-tests">specs</a>.
* All public API methods must be documented with ngdoc, an extended version of jsdoc (we added
support for markdown and templating via `@ngdoc` tag). To see how we document our APIs, please
check out the existing ngdocs.
* With the exceptions listed below, we follow the rules contained in {@link
http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml Google's JavaScript Style
Guide}:
* Do not use namespaces: Instead, we wrap the entire `angular` code base in an anonymous closure
and export our API explicitly rather than implicitly.
* Wrap all code at 100 characters.
* Instead of complex inheritance hierarchies, we prefer simple objects. We use prototypical
inheritance only when absolutely necessary.
* We love functions and closures and, whenever possible, prefer them over objects.
* To write concise code that can be better minified, internally we use aliases that map to the
external API. See our existing code to see what we mean.
* We don't go crazy with type annotations for private internal APIs unless it's an internal API
that is used throughout `angular`. The best guidance is to do what makes the most sense.
<a name="H1_4"></a>
# Checking Out and Building Angular
The `angular` source code is hosted at {@link http://github.com Github}, which we also use to
accept code contributions. Several steps are needed to check out and build `angular`:
## Installation Dependencies
Before you can build `angular`, you must install or configure the following dependencies on your
machine:
* {@link http://rake.rubyforge.org Rake}: We use Rake as our build system, which is pre-installed
on most Macintosh and Linux machines. If that is not true in your case, you can grab it from the
Rake website.
* {@link http://nodejs.org Node.js}: We use Node to generate the documentation and to run a
development web server. Depending on your system, you can install Node either from source or as a
pre-packaged bundle.
* Java: The Java runtime is used to run {@link http://code.google.com/p/js-test-driver
JsTestDriver} (JSTD), which we use to run our unit test suite. JSTD binaries are part of the
`angular` source base, which means there is no need to install or configure it separately.
* Git: The {@link http://help.github.com/mac-git-installation Github Guide to Installing Git} is
quite a good source for information on Git.
## Creating a Github Account and Forking Angular
To create a Github account, follow the instructions {@link https://github.com/signup/free here}.
Afterwards, go ahead and {@link http://help.github.com/forking fork} the {@link
https://github.com/angular/angular.js main angular repository}.
## Building `Angular`
To build `angular`, you check out the source code and use Rake to generate the non-minified and
minified `angular` files:
1. To clone your Github repository, run:
git clone git@github.com:<github username>/angular.js.git
2. To go to the `angular` directory, run:
cd angular.js
3. To add the main `angular` repository as an upstream remote to your repository, run:
git remote add upstream https://github.com/angular/angular.js.git
4. To build `angular`, run:
rake package
The build output can be located under the `build` directory. It consists of the following files and
directories:
* `angular-x.y.z-<git sha>.tgz` — This is the complete tarball, which contains all of the release
build artifacts.
* `angular-<version>.tgz` — This is the complete tarball, which contains all of the release build
artifacts.
* `angular.js` — The non-minified `angular` script.
* `angular.min.js` — The minified `angular` script.
* `angular-scenario.js` — The `angular` End2End test runner.
* `angular-ie-compat.js` — The Internet Explorer compatibility patch file.
* `docs/` — A directory that contains all of the files needed to run `docs.angularjs.org`.
* `docs/index.html` — The main page for the documentation.
* `docs/docs-scenario.html` — The End2End test runner for the documentation application.
## Running a Local Development Web Server
To debug or test code, it is often useful to have a local HTTP server. For this purpose, we have
made available a local web server based on Node.js.
1. To start the web server, run:
./nodeserver.sh
2. To access the local server, go to this website:
http://localhost:8000/
By default, it serves the contents of the `angular` project directory.
<a name="unit-tests"></a>
## Running the Unit Test Suite
Our unit and integration tests are written with Jasmine and executed with JsTestDriver. To run the
tests:
1. To start the JSTD server, run:
./server.sh
2. To capture one or more browsers, go to this website:
http://localhost:9876/
3. To trigger a test execution, run:
./test.sh
./test.sh
4. To automatically run the test suite each time one or more of the files in the project directory
is changed, you can install `watchr` and then run:
watchr watchr.rb
5. To view the output of each test run, you can tail this log file:
./logs/jstd.log
## Running the End2End Test Suite
To run the End2End test suite:
1. Start the local web server.
2. In a browser, go to:
http://localhost:8000/build/docs/docs-scenario.html
The tests are executed automatically.
<a name="H1_5"></a>
# Submitting Your Changes
To create and submit a change:
1. Create a new branch off the master for your changes:
git branch my-fix-branch
2. Check out the branch:
git checkout my-fix-branch
3. Create your patch, make sure to have plenty of tests (that pass).
4. Commit your changes:
git commit -a
5. Run JavaScript Lint and be sure to address all new warnings and errors:
rake lint
6. Push your branch to Github:
git push origin my-fix-branch
7. In Github, send a pull request to `angular:master`.
8. When the patch is reviewed and merged, delete your branch and pull yours — and other — changes
from the main (upstream) repository:
* To delete the branch in Github, run:
1. To delete the branch in Github, run:
git push origin :my-fix-branch
* To check out the master branch, run:
2. To check out the master branch, run:
git checkout master
* To delete a local branch, run:
3. To delete a local branch, run:
git branch -D my-fix-branch
* To update your master with the latest upstream version, run:
4. To update your master with the latest upstream version, run:
git pull --ff upstream master
That's it! Thank you for your contribution!

87
docs/content/misc/downloading.ngdoc
View File

@@ -3,24 +3,30 @@
@name Downloading
@description
# Including angular scripts from code.angularjs.org
To get started quickly you without worrying about downloading anything and maintaining a local copy,
you can point your html `script` tag directly to <http://code.angularjs.org/> urls.
# Including angular scripts from the angular server
The quickest way to get started is to point your html `<script>` tag to a
<http://code.angularjs.org/> URL. This way, you don't have to download anything or maintain a
local copy.
There are two kinds of urls you care about:
* http://code.angularjs.org/angular-<version>.js
* http://code.angularjs.org/angular-<version>.min.js
There are two types of angular script URLs you can point to, one for development and one for
production:
The first one is non-minified version, suitable for web development. The latter one is minified
version, which we strongly suggest you use in production.
To point your code to let's say angular version 0.9.12, use the following template:
* __angular-<version>.js__ — This is the human-readable, non-minified version, suitable for web
development.
* __angular-<version>.min.js__ — This is the minified version, which we strongly suggest you use in
production.
To point your code to an angular script on the angular server, use the following template. This
example points to (non-minified) version 0.9.12:
<pre>
<!doctype html>
<html>
<html xmlns:ng="http://angularjs.org">
<head>
<title>My Angular App</title>
<script src="http://code.angularjs.org/angular-0.9.12.js" ng:autobind></script>
@@ -31,40 +37,51 @@ To point your code to let's say angular version 0.9.12, use the following templa
</pre>
# Downloading and hosting the files on your own
This options is for those who want to work with angular offline, or want to host the angular files
on their own servers.
If you navigate to <http://code.angularjs.org/>, you'll see a directory listing with all angular
versions since we started releasing versioned build artifacts (quite late in the project lifetime).
# Downloading and hosting angular files locally
This option is for those who want to work with angular offline, or those who want to host the
angular files on their own servers.
Each directory contains all artifacts that we released for a particular version. Once you navigate
to one of these directories you'll see the following list of files:
* `angular-<version>.js` - This file is non-obfuscated, non-minified, and human-readable by opening
it it any editor or browser. In order to get better error messages during development, you should
always use this non-minified angular script.
If you navigate to <http://code.angularjs.org/>, you'll see a directory listing with all of the
angular versions since we started releasing versioned build artifacts (quite late in the project
lifetime). Each directory contains all artifacts that we released for a particular version.
Download the version you want and have fun.
* `angular-<version>.min.js` - This is a minified and obfuscated version of
`angular-<version>.js` created with Closure compiler. Use this version for production in order to
minimize the size of the application that is downloaded by your user's browser.
* `angular-<version>.tgz` - This is a tarball archive which contains all the other files released
Each directory under <http://code.angularjs.org/> includes the following set of files:
* __`angular-<version>.js`__ — This file is non-obfuscated, non-minified, and human-readable by
opening it it any editor or browser. In order to get better error messages during development, you
should always use this non-minified angular script.
* __`angular-<version>.min.js`__ — This is a minified and obfuscated version of
`angular-<version>.js` created with the Closure compiler. Use this version for production in order
to minimize the size of the application that is downloaded by your user's browser.
* __`angular-<version>.tgz`__ — This is a tarball archive that contains all of the files released
for this angular version. Use this file to get everything in a single download.
* `angular-ie-compat-<version>.js` - This is a special file that contains code and data specifically
tailored for getting Internet Explorer to work with angular. If you host your own copy of angular
files, make sure that this file is available for download and resides under the same parent path as
`angular-<version>.js` or `angular-<version>.min.js`.
* `angular-mocks-<version>.js` - This file contains implementation of mocks that we provide to you
to make testing angular apps even easier. Your unit/integration test harness should load this file
after `angular-<version>.js` is loaded.
* __`angular-ie-compat-<version>.js`__ — This is a special file that contains code and data
specifically tailored for getting Internet Explorer to work with angular. If you host your own copy
of angular files, make sure that this file is available for download, and that it resides under the
same parent path as `angular-<version>.js` or `angular-<version>.min.js`.
* `angular-scenario-<version>.js` - This file is a very nifty JavaScript file, which allows you to
write and execute end to end tests for angular applications.
* `docs-<version>` - this directory contains all the files that compose the
* __`angular-mocks-<version>.js`__ — This file contains an implementation of mocks that makes
testing angular apps even easier. Your unit/integration test harness should load this file after
`angular-<version>.js` is loaded.
* __`angular-scenario-<version>.js`__ — This file is a very nifty JavaScript file that allows you
to write and execute end-to-end tests for angular applications.
* __`docs-<version>`__ — this directory contains all the files that compose the
<http://docs.angularjs.org/> documentation app. These files are handy to see the older version of
our docs, or even more importantly, view the docs offline!
our docs, or even more importantly, view the docs offline.

38
docs/content/misc/faq.ngdoc
View File

@@ -3,36 +3,49 @@
@name FAQ
@description
#FAQ
### Why is this project called "angular"? Why is the namespace called "ng"?
Because HTML has angular brackets and "ng" sounds like "angular".
### Is <angular/> an HTML5 tag?
No, <angular/> is not an HTML5 tag. angular is an orthogonal project to HTML5; you can use the two
together.
### Is angular a {library, framework, DOM manipulation library, widget library, native plugin}?
No, angular is none of these. You don't call its functions, it does not call your functions,
it does not provide a way to manipulate DOM, but does provide primitives to create UI projections
of your data. There are lots of existing widget libraries which you can integrate with angular.
It is 100% JavaScript, 100% client side and compatible with both desktop and mobile browsers.
### Do I need to worry about security holes in angular?
Like with any technology, angular is not impervious to attack. angular does, however, provide
built-in protection from basic security holes including cross-site scripting and HTML injection
attacks. angular does round-trip escaping on all strings for you.
### Can I download the source, build, and host the angular environment locally?
Yes. See instructions in {@link intro.downloading downloading}.
Yes. See instructions in {@link downloading}.
### Is angular a templating system?
At the highest level, angular does look like a just another templating system. But there is one
important reason why angular templating system is different and makes it very good fit for
application development: bidirectional data binding. The template is compiled on the browser and
@@ -40,42 +53,59 @@ the compilation step produces a live view. This means you, the developer, don't
code to constantly sync the view with the model and the model with the view as in other
templating systems.
### What browsers does angular work with?
Webkit-based browsers (Safari, Chrome, iPhone, Android, WebOS, BlackBerry 6), Firefox, IE6 and
above. Note that CSS only works on IE7 and above.
### What's angular's performance like?
angular takes ~300ms to load, render, and compile. In Chrome it uses about 2-5MB of memory. Your
app's performance will vary depending on how many bindings you use.
### How big is the angular bootstrap JS file that I need to include?
The size of the library itself is < 50KB compressed and obfuscated.
### Can I use the open-source Closure Library with angular?
Yes, you can use widgets from the {@link http://code.google.com/closure/library Closure Library}
in angular.
### Does angular use the jQuery library?
Yes, angular uses {@link http://jquery.com/ jQuery}, the open source DOM manipulation library.
If jQuery is not present in your script path, angular falls back on its own implementation of
{@link angular.element jQuery lite}. If jQuery is present in the path, angular uses it to
{@link api/angular.element jQuery lite}. If jQuery is present in the path, angular uses it to
manipulate the DOM.
### What is testability like in angular?
Very testable. It has an integrated dependency injection framework. See
{@link angular.service service} for details.
{@link api/angular.service service} for details.
### How can I learn more about angular?
Watch the July 28, 2010 talk
"{@link http://www.youtube.com/watch?v=elvcgVSynRg| Angular: A Radically Different Way of Building AJAX Apps}".
"{@link http://www.youtube.com/watch?v=elvcgVSynRg| Angular: A Radically Different Way of Building
AJAX Apps}".
### How is angular licensed?
The MIT License.

145
docs/content/misc/started.ngdoc
View File

@@ -3,68 +3,89 @@
@name Getting Started
@description
# Hello World!
A great way for you to get started with `angular` is to create the tradtional
A great way for you to get started with `angular` is to create the tradtional
"Hello World!" app:
1. In your favorite text editor, create an HTML file
(for example, `helloworld.html`).
1. In your favorite text editor, create an HTML file
(for example, `helloworld.html`).
2. From the __Source__ box below, copy and paste the code into your HTML file.
(Double-click on the source to easily select all.)
3. Open the file in your web browser.
<doc:example>
<doc:source>
Hello {{'World'}}!
</doc:source>
</doc:example>
The resulting web page should look something like the following:
<img class="center" src="img/helloworld.png" border="1" />
Now let's take a closer look at that code, and see what is going on behind
the scenes.
The first line of interest defines the `ng` namespace, which makes
Now let's take a closer look at that code, and see what is going on behind
the scenes.
The first line of interest defines the `ng` namespace, which makes
`angular` work across all browsers (especially important for IE):
<pre>
<html xmlns:ng="http://angularjs.org">
</pre>
The next line downloads the `angular` script, and instructs `angular` to process
The next line downloads the `angular` script, and instructs `angular` to process
the entire HTML page when it is loaded:
<pre>
<script type="text/javascript" src="http://code.angularjs.org/angular-?.?.?.min.js" ng:autobind></script>
<script type="text/javascript" src="http://code.angularjs.org/angular-?.?.?.min.js"
ng:autobind></script>
</pre>
(For details on what happens when `angular` processes an HTML page,
see {@link guide.bootstrap Bootstrap}.)
Finally, this line in the `<body>` of the page is the template that describes
(For details on what happens when `angular` processes an HTML page,
see {@link guide/dev_guide.bootstrap Bootstrap}.)
Finally, this line in the `<body>` of the page is the template that describes
how to display our greeting in the UI:
<pre>
Hello {{'World'}}!
</pre>
Note the use of the double curly brace markup (`{{ }}`) to bind the expression to
Note the use of the double curly brace markup (`{{ }}`) to bind the expression to
the greeting text. Here the expression is the string literal 'World'.
Next let's look at a more interesting example, that uses `angular` to
Next let's look at a more interesting example, that uses `angular` to
bind a dynamic expression to our greeting text.
# Hello <angular/> World!
This example demonstrates `angular`'s two-way data binding:
This example demonstrates `angular`'s two-way data binding:
1. Edit the HTML file you created in the "Hello World!" example above.
2. Replace the contents of `<body>` with the code from the __Source__ box below.
3. Refresh your browswer window.
<doc:example>
<doc:source>
Your name: <input type="text" name="yourname" value="World"/>
@@ -73,74 +94,100 @@ This example demonstrates `angular`'s two-way data binding:
</doc:source>
</doc:example>
After the refresh, the page should look something like this:
<img class="left" src="img/helloworld_2way.png" border="1" />
These are some of the important points to note from this example:
* The text input {@link angular.widget widget} called `yourname` is bound to a model variable called
* The text input {@link api/angular.widget widget} called `yourname` is bound to a model variable
called
`yourname`.
* The double curly braces notation binds the variable `yourname` to the
* The double curly braces notation binds the variable `yourname` to the
greeting text.
<!--
* The variable `yourname` is implicitly created in the root scope.
-->
* You did not need to explicitly register an event listener or define an event
* You did not need to explicitly register an event listener or define an event
handler for events!
Now try typing your name into the input box, and notice the immediate change to
the displayed greeting. This demonstrates the concept of `angular`'s
{@link guide.data-binding bi-directional data binding}. Any changes to the input field are immediately
reflected in the model (one direction), and any changes to the model are
Now try typing your name into the input box, and notice the immediate change to
the displayed greeting. This demonstrates the concept of `angular`'s
{@link guide/dev_guide.templates.databinding bi-directional data binding}. Any changes to the input
field are immediately
reflected in the model (one direction), and any changes to the model are
reflected in the greeting text (the other direction).
# Anatomy of an `angular` App
This section describes the 3 parts of an `angular` app, and explains how they
map to the Model-View-Controller design pattern:
# Anatomy Of An Angular App
This section describes the 3 parts of an angular app, and explains how they map to the
Model-View-Controller design pattern:
## Templates
Templates, which you write in HTML and CSS, serve as the View. You add elements,
attributes, and markup to HTML, which serve as instructions to the `angular`
compiler. The `angular` compiler is fully extensible, meaning that with angular
you can build your own declarative language on top of HTML!
Templates, which you write in HTML and CSS, serve as the View. You add elements, attributes, and
markup to HTML, which serve as instructions to the angular compiler. The angular compiler is fully
extensible, meaning that with angular you can build your own declarative language on top of HTML!
## Application Logic and Behavior
Application Logic and Behavior, which you define in JavaScript, serve as the
Controller. With `angular` (unlike with standard AJAX applications) you don't
need to write additional listeners or DOM manipulators, because they are built-in.
This feature makes your application logic very easy to write, test, maintain, and
understand.
## Scope
Application Logic and Behavior, which you define in JavaScript, serve as the Controller. With
angular (unlike with standard AJAX applications) you don't need to write additional listeners or
DOM manipulators, because they are built-in. This feature makes your application logic very easy to
write, test, maintain, and understand.
The Model consists of one or more JavaScript objects, arrays, or primitive types.
These are referenced from the scope. There are no restrictions on what the Model
can be or what structure it should have. The only requirement is that it is
referenced by the scope.
The following illustration shows the parts of an `angular` application and how they
work together:
## Data
The Model is referenced from properties on {@link guide/dev_guide.scopes angular scope objects}.
The data in your model could be Javascript objects, arrays, or primitives, it doesn't matter. What
matters is that these are all referenced by the scope object.
Angular employs scopes to keep your data model and your UI in sync. Whenever something occurs to
change the state of the model, angular immediately reflects that change in the UI, and vice versa.
The following illustration shows the parts of an angular application and how they work together:
<img class="left" src="img/angular_parts.png" border="0" />
In addition, `angular` comes with a set of Services, which have the following
properties:
In addition, angular comes with a set of Services, which have the following properties:
* The services provided are very useful for building web applications.
* You can extend and add application-specific behavior to services.
* Services include Dependency-Injection, XHR, caching, URL routing,
and browser abstraction.
* Services include Dependency-Injection, XHR, caching, URL routing, and browser abstraction.
# Where To Go Next
* For additional hands-on examples of using `angular`, including more source
code that you can copy and paste into your own pages, take a look through
the `angular` {@link cookbook Cookbook}.
* For explanations of the `angular` concepts presented in the examples on this
page, see the {@link guide Developer Guide}.
* For explanations and examples of the angular concepts presented on this page, see the {@link
guide/index Developer Guide}.
* For additional hands-on examples of using `angular`, including more source code that you can
copy and paste into your own pages, take a look through the `angular` {@link cookbook/ Cookbook}.