diff options
| author | Igor Minar | 2011-05-19 18:04:12 -0700 |
|---|---|---|
| committer | Igor Minar | 2011-06-06 22:52:01 -0700 |
| commit | bc2ca384b1c44488c6e27c24f10111cc06113df9 (patch) | |
| tree | c0d7cc5b4c0df124941768969d4d814c76afbdfe /docs/content/intro | |
| parent | 238094310694f0755e6089bf92c36d0ff55fe626 (diff) | |
| download | angular.js-bc2ca384b1c44488c6e27c24f10111cc06113df9.tar.bz2 | |
move docs/content/intro to docs/content/misc
Diffstat (limited to 'docs/content/intro')
| -rw-r--r-- | docs/content/intro/contribute.ngdoc | 233 | ||||
| -rw-r--r-- | docs/content/intro/downloading.ngdoc | 70 | ||||
| -rw-r--r-- | docs/content/intro/faq.ngdoc | 81 | ||||
| -rw-r--r-- | docs/content/intro/started.ngdoc | 146 | ||||
| -rw-r--r-- | docs/content/intro/testimonials.ngdoc | 33 |
5 files changed, 0 insertions, 563 deletions
diff --git a/docs/content/intro/contribute.ngdoc b/docs/content/intro/contribute.ngdoc deleted file mode 100644 index 43d17283..00000000 --- a/docs/content/intro/contribute.ngdoc +++ /dev/null @@ -1,233 +0,0 @@ -@ngdoc overview -@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_2">Contributing to Source Code</a> -* <a href="#H1_3">Applying Code Standards</a> -* <a href="#H1_4">Checking Out and Building `Angular`</a> -* <a href="#H1_5">Submitting Your Changes</a> - - - -<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.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 - -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: - - git push origin :my-fix-branch - - * To check out the master branch, run: - - git checkout master - - * To delete a local branch, run: - - git branch -D my-fix-branch - - * To update your master with the latest upstream version, run: - - git pull --ff upstream master - -That's it! Thank you for your contribution! diff --git a/docs/content/intro/downloading.ngdoc b/docs/content/intro/downloading.ngdoc deleted file mode 100644 index a02b3367..00000000 --- a/docs/content/intro/downloading.ngdoc +++ /dev/null @@ -1,70 +0,0 @@ -@workInProgress -@ngdoc overview -@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. - -There are two kinds of urls you care about: - -* http://code.angularjs.org/angular-<version>.js -* http://code.angularjs.org/angular-<version>.min.js - -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: - -<pre> - <!doctype html> - <html> - <head> - <title>My Angular App</title> - <script src="http://code.angularjs.org/angular-0.9.12.js" ng:autobind></script> - </head> - <body> - </body> - </html> -</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). - -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. - -* `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 -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-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 -<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! diff --git a/docs/content/intro/faq.ngdoc b/docs/content/intro/faq.ngdoc deleted file mode 100644 index 2030dfbb..00000000 --- a/docs/content/intro/faq.ngdoc +++ /dev/null @@ -1,81 +0,0 @@ -@workInProgress -@ngdoc overview -@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}. - -### 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 -the compilation step produces a live view. This means you, the developer, don't need to write -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 -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. - -### 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}". - -### How is angular licensed? - -The MIT License. diff --git a/docs/content/intro/started.ngdoc b/docs/content/intro/started.ngdoc deleted file mode 100644 index a505b471..00000000 --- a/docs/content/intro/started.ngdoc +++ /dev/null @@ -1,146 +0,0 @@ -@workInProgress -@ngdoc overview -@name Getting Started -@description - -# Hello World! - -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`). -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 -`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 entire HTML page when it is loaded: - -<pre> - <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 -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 -the greeting text. Here the expression is the string literal 'World'. - -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: - -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"/> - <hr/> - Hello {{yourname}}! - </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 - `yourname`. -* 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 - 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 -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: - -## 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! - -## 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 - -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: - -<img class="left" src="img/angular_parts.png" border="0" /> - -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. - -# 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}. diff --git a/docs/content/intro/testimonials.ngdoc b/docs/content/intro/testimonials.ngdoc deleted file mode 100644 index 2e333f4b..00000000 --- a/docs/content/intro/testimonials.ngdoc +++ /dev/null @@ -1,33 +0,0 @@ -@ngdoc overview -@name Testimonials -@description - - -## John Hardy -> Also I want to pass on my compliments to Misko and Igor for this fantastic project. I'm currently -> rewriting a server-side web application to use this system. I am constantly astounded at how much -> simpler it is to do it this way and I still consider myself a learner. - -> This is without question the most productive approach to building webapps that I have seen. - -> The last time I had a coding epiphany was discovering the power and simplicity of JQuery. This is -> way better than that. - -> I'm interested in promoting this library as widely as possible. I understand that you are still -> developing it and I still have a long way to go before I really understand everything but I think -> you really have something here. - - -## Jerry Jeremiah -> angular is the best thing I have used in a long time. I am having so much fun, even thought it is -> probably obvious that dynamic web sites are new to me (my experience is more in the back end -> embedded world...) - - -## Dobrica Pavlinusic -> Thanks to great help I received at this list, I was basically able to accomplish my goal to write -> simple conference submission application within a week of first git clone of angular source from -> github. - -> I think it might be useful to summarize my experience here, especially for people who are still -> wondering if angular is worth a try. Executive summary is: **yes it is!**
\ No newline at end of file |
