diff options
Diffstat (limited to 'docs/content')
| -rw-r--r-- | docs/content/guide/dev_guide.overview.ngdoc | 236 | ||||
| -rw-r--r-- | docs/content/guide/overview.ngdoc | 208 |
2 files changed, 208 insertions, 236 deletions
diff --git a/docs/content/guide/dev_guide.overview.ngdoc b/docs/content/guide/dev_guide.overview.ngdoc deleted file mode 100644 index e44a9cef..00000000 --- a/docs/content/guide/dev_guide.overview.ngdoc +++ /dev/null @@ -1,236 +0,0 @@ -@ngdoc overview -@name Developer Guide: Overview -@description - - -# What Is Angular? - -The short answer: angular is a new, powerful, client-side technology that makes it much easier for -you to create dynamic web sites and complex web apps, all without leaving the comfort of your HTML -/ JavaScript home. - -The long answer: it depends on where you're coming from... - -* If you're a web designer, you might perceive angular to be a sweet {@link dev_guide.templates -templating} system, that doesn't get in your way and provides you with lots of nice built-ins that -make it easier to do what you want to do. - -* If you're a web developer, you might be thrilled that angular functions as an excellent web -framework, one that assists you all the way through the development cycle. - -* If you want to go deeper, you can immerse yourself in angular's extensible HTML {@link -dev_guide.compiler compiler} that runs in your browser. The angular compiler teaches your browser -new tricks. - -Angular is not just a templating system, but you can create fantastic templates with it. Angular is -not just a web framework, but it features a very nice framework. Angular is not just an extensible -HTML compiler, but the compiler is at the core of Angular. Angular includes all of these -components, along with others. Angular is far greater than the sum of its parts. It is a new, -better way to develop web applications! - - -## An Introductory Angular Example - -Let's say that you are a web designer, and you've spent many thous — erm, hundreds of hours -designing web sites. But at this point, the thought of manipulating the DOM, writing listeners and -input validators, all just to implement a simple form? No. You either don't want to go there in -the first place or you've been there and the thrill is gone. - -So look over the following simple example written using angular. Note that it features only the -templating aspect of angular, but this should suffice for now to quickly demonstrate how much -easier a web developer's life can if they're using angular: - -<doc:example> -<doc:source> - <script> - function InvoiceCntl($scope) { - $scope.qty = 1; - $scope.cost = 19.95; - } - </script> - <div ng-controller="InvoiceCntl"> - <b>Invoice:</b> - <br /> - <br /> - <table> - <tr><td> </td><td> </td> - <tr><td>Quantity</td><td>Cost</td></tr> - <tr> - <td><input type="integer" min="0" ng-model="qty" required ></td> - <td><input type="number" ng-model="cost" required ></td> - </tr> - </table> - <hr /> - <b>Total:</b> {{qty * cost | currency}} - </div> -</doc:source> -<!-- -<doc:scenario> - it('should show of angular binding', function() { - expect(binding('qty * cost')).toEqual('$19.95'); - input('qty').enter('2'); - input('cost').enter('5.00'); - expect(binding('qty * cost')).toEqual('$10.00'); - }); -</doc:scenario> ---> -</doc:example> - -Try out the Live Preview above, and then let's walk through the example and describe what's going -on. - -In the `<html>` tag we specify that this is an angular application with the `ngApp` directive. -The `ngApp' will cause the angular to {@link dev_guide.bootstrap auto initialize} your application. - - <html ng-app> - -We load the angular using the `<script>` tag: - - <script src="http://code.angularjs.org/angular-?.?.?.min.js"></script> - -From the `ngModel` attribute of the `<input>` tags, angular automatically sets up two-way data -binding, and we also demonstrate some easy input validation: - - Quantity: <input type="integer" min="0" ng-model="qty" required > - Cost: <input type="number" ng-model="cost" required > - -These input widgets look normal enough, but consider these points: - -* When this page loaded, angular bound the names of the input widgets (`qty` and `cost`) to -variables of the same name. Think of those variables as the "Model" component of the -Model-View-Controller design pattern. -* Note the angular/HTML widget, {@link api/angular.module.ng.$compileProvider.directive.input input}. -You may have noticed that when you enter invalid data -or leave the the input fields blank, the borders turn red color, and the display value disappears. -These widgets make it easier to implement field validation than coding them in JavaScript, -no? Yes. - -And finally, the mysterious `{{ double curly braces }}`: - - Total: {{qty * cost | currency}} - -This notation, `{{ _expression_ }}`, is a bit of built-in angular binding markup, a shortcut for -displaying data to the user. The expression within curly braces is monitored and its evaluated value -is updated into the view by angular's template compiler. Alternatively, one could use angular's -{@link api/angular.module.ng.$compileProvider.directive.ngBind ngBind}) directive. The expression -itself can be a combination of both an expression and a {@link dev_guide.templates.filters filter}: -`{{ expression | filter }}`. Angular provides filters for formatting display data. - -In the example above, the expression in double-curly braces directs angular to, "Bind the data we -got from the input widgets to the display, multiply them together, and format the resulting number -into output that looks like money." - - -# The Angular Philosophy - -Angular is built around the belief that declarative code is better than imperative when it comes to -building UIs and wiring software components together, while imperative code is excellent for -expressing business logic. - -Not to put too fine a point on it, but if you wanted to add a new label to your application, you -could do so by simply adding text to the HTML template, saving the code, and refreshing your -browser: - -<pre> -<span class="label">Hello</span> -</pre> - -Or, as in programmatic systems (like {@link http://code.google.com/webtoolkit/ GWT}), you would -have to write the code and then run the code like this: - -<pre> -var label = new Label(); -label.setText('Hello'); -label.setClass('label'); -parent.addChild(label); -</pre> - -That's one line of markup versus four times as much code. - - -## More Angular Philosophy - -* It is a very good idea to decouple DOM manipulation from app logic. This dramatically improves -the testability of the code. -* It is a really, _really_ good idea to regard app testing as equal in importance to app writing. -Testing difficulty is dramatically affected by the way the code is structured. -* It is an excellent idea to decouple the client side of an app from the server side. This allows -development work to progress in parallel, and allows for reuse of both sides. -* It is very helpful indeed if the framework guides developers through the entire journey of -building an app: from designing the UI, through writing the business logic, to testing. -* It is always good to make common tasks trivial and difficult tasks possible. - -Now that we're homing in on what angular is, perhaps now would be a good time to list a few things -that angular is not: - -* It's not a Library. You don't just call its functions, although it does provide you with some -utility APIs. -* It's not a DOM Manipulation Library. Angular uses jQuery to manipulate the DOM behind the scenes, -rather than give you functions to manipulate the DOM yourself. -* It's not a Widget Library. There are lots of existing widget libraries that you can integrate -with angular. -* It's not "Just Another Templating System". A part of angular is a templating system. The -templating subsystem of angular is different from the traditional approach for these reasons: - * It Uses HTML/CSS syntax: This makes it easy to read and can be edited with existing HTML/CSS -authoring tools. - * It Extends HTML vocabulary: Angular allows you to create new HTML tags, which expand into -dynamic UI components. - * It Executes in the browser: Removes the round trip to the server for many operations and -creates instant feedback for users as well as developers. - * It Has Bidirectional data binding: The model is the single source of truth. Programmatic -changes to the model are automatically reflected in the view. Any changes by the user to the view -are automatically reflected in the model. - - -# Why You Want Angular - -Angular frees you from the following pain: - -* **Registering callbacks:** Registering callbacks clutters your code, making it hard to see the -forest for the trees. Removing common boilerplate code such as callbacks is a good thing. It vastly -reduces the amount of JavaScript coding _you_ have to do, and it makes it easier to see what your -application does. -* **Manipulating HTML DOM programatically:** Manipulating HTML DOM is a cornerstone of AJAX -applications, but it's cumbersome and error-prone. By declaratively describing how the UI should -change as your application state changes, you are freed from low level DOM manipulation tasks. Most -applications written with angular never have to programatically manipulate the DOM, although you -can if you want to. -* **Marshaling data to and from the UI:** CRUD operations make up the majority of AJAX -applications. The flow of marshaling data from the server to an internal object to an HTML form, -allowing users to modify the form, validating the form, displaying validation errors, returning to -an internal model, and then back to the server, creates a lot of boilerplate code. Angular -eliminates almost all of this boilerplate, leaving code that describes the overall flow of the -application rather than all of the implementation details. -* **Writing tons of initialization code just to get started:** Typically you need to write a lot of -plumbing just to get a basic "Hello World" AJAX app working. With angular you can bootstrap your -app easily using services, which are auto-injected into your application in a {@link -http://code.google.com/p/google-guice/ Guice}-like dependency-injection style. This allows you to -get started developing features quickly. As a bonus, you get full control over the initialization -process in automated tests. - - -# Watch a Presentation About Angular - -Here is an early presentation on angular, but note that substantial development has occurred since -the talk was given in July of 2010. - -<object width="480" height="385"> - <param name="movie" value="http://www.youtube.com/v/elvcgVSynRg&hl=en_US&fs=1"></param> - <param name="allowFullScreen" value="true"></param> - <param name="allowscriptaccess" value="always"></param> - <embed src="http://www.youtube.com/v/elvcgVSynRg&hl=en_US&fs=1" - type="application/x-shockwave-flash" allowscriptaccess="always" - allowfullscreen="true" width="480" height="385"></embed> -</object> - -{@link - -https://docs.google.com/present/edit?id=0Abz6S2TvsDWSZDQ0OWdjaF8yNTRnODczazdmZg&hl=en&authkey=CO-b7oID - -Presentation} -| -{@link - -https://docs.google.com/document/edit?id=1ZHVhqC0apbzPRQcgnb1Ye-bAUbNJ-IlFMyPBPCZ2cYU&hl=en&authkey=CInnwLYO - -Source} diff --git a/docs/content/guide/overview.ngdoc b/docs/content/guide/overview.ngdoc new file mode 100644 index 00000000..8bb9e657 --- /dev/null +++ b/docs/content/guide/overview.ngdoc @@ -0,0 +1,208 @@ +@ngdoc overview +@name Developer Guide: Overview +@description + + +# What Is Angular? + +AngularJS is a structural framework for dynamic web apps. It lets you use HTML as your template +language and lets you extend HTML's syntax to express your application's components clearly and +succinctly. Out of the box, it eliminates much of the code you currently write through data +binding and dependency injection. And it all happens in JavaScript within the browser making it an +ideal partner with any server technology. + +Angular is what HTML would have been had it been design for applications. HTML is a great +declarative language for static documents. It does not contain much in the way of creating +application, and as a result building web-applications is an exercise in *what do I have to do, so +that I trick the browser in to doing what I want.* + +Impedance mismatch between dynamic-applications and static-documents are often solved as: + + * **library** - a collection of functions which are useful when writing web apps. Your code is + in charge and it calls into the library when it sees fit. i.e.: `jQuery` + * **frameworks** - a particular implementation of a web-application, where your code fills in + the details. The framework is in charge and it calls into your code when it needs something + app specific. i.e.: `knockout`, `sproutcore`, etc... + + +Angular takes another approach. It attempts to minimize the impedance mismatch between document +centric HTML and what application needs by creating new HTML constructs. Angular teaches the +browser new syntax through a construct we call directives. Examples include: + + * Data binding as in `{{}}`. + * DOM control structures for repeating/hiding DOM fragments. + * Support for forms and form validation. + * Attaching code-behind to DOM elements. + * Grouping of HTML into reusable components. + + + +## End-to-end solution + +Angular tries to be an end to end solution, when building a web-application. This means it is +not a single piece in an overall puzzle of building a web-application, but an end-to-end solution. +This makes Angular opinionated about how a CRUD application should be built. But while it is +opinionated, it also tries to make sure that its opinion is just a starting point, which you can +easily change. Angular comes with the following out-of-the-box: + + * Everything you need to build a CRUD app in a cohesive set: Data-binding, basic templating + directives, form validation, routing, deep-linking, reusable components, dependency injection. + * Testability story: unit-testing, end-to-end testing, mocks, test harnesses. + * Seed application with directory layout and test scripts as a starting point. + + +## Angular Sweet Spot + +Angular simplifies the application development by presenting a higher level of abstraction to the +developer. Like any abstraction, it comes at a cost of flexibility. In other words not every app +is a good fit for Angular. Angular was built for the CRUD application in mind, luckily CRUD +applications represent at least 90% of the web applications. But to understand what Angular is +good at one also has to understand when an app is not a good fit for Angular. + +Games, and GUI editors are examples of very intensive and tricky DOM manipulation. These kinds of +apps are different from CRUD apps, and as a result are not a good fit for Angular. In these cases +using something closer to bare metal such as `jQuery` may be a better fit. + + +# An Introductory Angular Example + +Below is a typical CRUD application which contains a form. The form values are validated, and +are used to compute the total, which is formatted to a particular local. These are some common +concepts which the application developer may face: + + * attaching data-model to the UI. + * writing, reading and validating user input. + * computing new values based on the model. + * formatting output in a user specific locale. + +<doc-example> + <doc-source> + <script> + function InvoiceCntl($scope) { + $scope.qty = 1; + $scope.cost = 19.95; + } + </script> + <div ng-controller="InvoiceCntl"> + <b>Invoice:</b> + <br> + <br> + <table> + <tr><td>Quantity</td><td>Cost</td></tr> + <tr> + <td><input type="integer" min="0" ng-model="qty" required ></td> + <td><input type="number" ng-model="cost" required ></td> + </tr> + </table> + <hr> + <b>Total:</b> {{qty * cost | currency}} + </div> + </doc-source> + <doc-scenario> + it('should show of angular binding', function() { + expect(binding('qty * cost')).toEqual('$19.95'); + input('qty').enter('2'); + input('cost').enter('5.00'); + expect(binding('qty * cost')).toEqual('$10.00'); + }); + </doc-scenario> +</doc-example> + +Try out the Live Preview above, and then let's walk through the example and describe what's going +on. + +In the `<html>` tag, we specify that it is an angular +application with the `ng-app` directive. The `ng-app' will cause the angular to {@link +dev_guide.bootstrap auto initialize} your application. + + <html ng-app> + +We load the angular using the `<script>` tag: + + <script src="http://code.angularjs.org/angular-?.?.?.min.js"></script> + +From the `ng-model` attribute of the `<input>` tags, angular automatically sets up two-way data +binding, and we also demonstrate some easy input validation: + + Quantity: <input type="integer" min="0" ng-model="qty" required > + Cost: <input type="number" ng-model="cost" required > + +These input widgets look normal enough, but consider these points: + + * When this page loaded, angular bound the names of the input widgets (`qty` and `cost`) to + variables of the same name. Think of those variables as the "Model" component of the + Model-View-Controller design pattern. + * Note that the HTML widget {@link api/angular.module.ng.$compileProvider.directive.input input} + has special powers. The input invalidates itself by turning red when you enter invalid data or + leave the the input fields blank. These new widget behavior make it easier to implement field + validation common in CRUD applications. + +And finally, the mysterious `{{ double curly braces }}`: + + Total: {{qty * cost | currency}} + +This notation, `{{ _expression_ }}`, is angular markup for data-binding. The expression itself can +be a combination of both an expression and a {@link dev_guide.templates.filters filter}: `{{ +expression | filter }}`. Angular provides filters for formatting display data. + +In the example above, the expression in double-curly braces directs angular to "Bind the data we +got from the input widgets to the display, multiply them together, and format the resulting number +into output that looks like money." + +Notice that we achieved this application behavior not by calling angular methods, nor by +implementing application specific behavior as framework. We achieved the behavior because the +browser behaved more in line what is needed for dynamic web-application rather then what is needed +for static-document. Angular has lowered the impedance mismatch to the point where no +library/framework calls are needed. + + +# The Zen of Angular + +Angular is built around the belief that declarative code is better than imperative when it comes +to building UIs and wiring software components together, while imperative code is excellent for +expressing business logic. + + + * It is a very good idea to decouple DOM manipulation from app logic. This dramatically improves + the testability of the code. + * It is a really, _really_ good idea to regard app testing as equal in importance to app + writing. Testing difficulty is dramatically affected by the way the code is structured. + * It is an excellent idea to decouple the client side of an app from the server side. This + allows development work to progress in parallel, and allows for reuse of both sides. + * It is very helpful indeed if the framework guides developers through the entire journey of + building an app: from designing the UI, through writing the business logic, to testing. + * It is always good to make common tasks trivial and difficult tasks possible. + + + +Angular frees you from the following pain: + + * **Registering callbacks:** Registering callbacks clutters your code, making it hard to see the + forest for the trees. Removing common boilerplate code such as callbacks is a good thing. It + vastly reduces the amount of JavaScript coding _you_ have to do, and it makes it easier to see + what your application does. + * **Manipulating HTML DOM programmatically:** Manipulating HTML DOM is a cornerstone of AJAX + applications, but it's cumbersome and error-prone. By declaratively describing how the UI + should change as your application state changes, you are freed from low level DOM manipulation + tasks. Most applications written with angular never have to programmatically manipulate the + DOM, although you can if you want to. + * **Marshaling data to and from the UI:** CRUD operations make up the majority of AJAX + applications. The flow of marshaling data from the server to an internal object to an HTML + form, allowing users to modify the form, validating the form, displaying validation errors, + returning to an internal model, and then back to the server, creates a lot of boilerplate + code. Angular eliminates almost all of this boilerplate, leaving code that describes the + overall flow of the application rather than all of the implementation details. + * **Writing tons of initialization code just to get started:** Typically you need to write a lot + of plumbing just to get a basic "Hello World" AJAX app working. With angular you can bootstrap + your app easily using services, which are auto-injected into your application in a {@link + http://code.google.com/p/google-guice/ Guice}-like dependency-injection style. This allows you + to get started developing features quickly. As a bonus, you get full control over the + initialization process in automated tests. + + +# Watch a Presentation About Angular + +Here is an early presentation on angular, but note that substantial development has occurred since +the talk was given in July of 2010. + +<iframe width="560" height="315" src="http://www.youtube.com/embed/bfrn5VNpwsg" frameborder="0" allowfullscreen></iframe> |