diff options
Diffstat (limited to 'docs/content/guide/overview.ngdoc')
| -rw-r--r-- | docs/content/guide/overview.ngdoc | 337 |
1 files changed, 0 insertions, 337 deletions
diff --git a/docs/content/guide/overview.ngdoc b/docs/content/guide/overview.ngdoc deleted file mode 100644 index 8723e839..00000000 --- a/docs/content/guide/overview.ngdoc +++ /dev/null @@ -1,337 +0,0 @@ -@ngdoc overview -@name Developer Guide: Overview -@description - - -* <a href="#H1_1">What Is Angular?</a> -* <a href="#H1_3">The Angular Philosophy</a> -* <a href="#H1_2">Anatomy Of An Angular App</a> -* <a href="#H1_4">Why You Want Angular</a> -* <a href="#H1_5">Angular's Ancestors</a> -* <a href="#H1_6">Watch a Presentation About Angular</a> - - -<a name="H1_1"></a> -# 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 kind of depends on where you're coming from... - -* If you're a web designer, you might perceive angular to be a sweet {@link guide.template -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 -guide.compiler compiler} that runs in your browser. This compiler teaches your browser new tricks. - -So then, angular's not just a templating system, but you can create fantastic templates with it; -angular's not just a web framework, but it has a very nice one; and angular's not just an -extensible HTML compiler, but it has one of those too. Let's put it this way: angular includes -these parts along with some others; it evolved naturally from earlier occurrences of these forms; -and thus angular is something far greater than the sum of its parts. It sounds like... it's alive! - -## An Intro By Way of 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 doing DOM updates, writing listeners, and -writing input validators, all to do something as simple as implementing a form!? You either don't -want to go there in the first place or you've been there and the thrill is gone. - -You could even be muttering to yourself as you hack another callback, "This is like building my own -bike from scratch every time I want to ride to the store." But let's say a clever friend, who keeps -tabs on these sorts of things, told you to check out angular. - -So now here you are checking out angular, and here is a simple example. Note that it features only -the templating aspect of angular, but this should suffice for now to quickly demonstrates how much -easier life can be with angular: - -<doc:example> -<doc:source> - <h2>Bigg Bike Shop</h2> - <hr> - <b>Invoice:</b> - <br/> - <br/> - <table> - <tr><td> </td><td> </td> - <tr><td>Quantity</td><td>Cost</td></tr> - <tr> - <td><input name="qty" value="1" ng:validate="integer:0" ng:required/></td> - <td><input name="cost" value="19.95" ng:validate="number" ng:required/></td> - </tr> - </table> - <hr> - <b>Total:</b> {{qty * cost | currency}} - <hr> -</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> - -Go ahead, try out the Live Preview above. "Well I _declare_! It's a fully functioning form, with -an instantly updating display, and input validation." Speaking of being declarative, let's walk -through the example and look at the angular-related lines to see what's going on around here. - -In line __2__ of the example, we let the browser know about the angular namespace: - - 2 <html xmlns:ng="http://angularjs.org"> - -This ensures angular runs nicely in all major browsers. - -In line __3__ we do two angular setup tasks inside a `<script>` tag: - -1. We pull in `angular.js`. -2. The angular {@link angular.directive.ng:autobind ng:autobind} directive tells angular to {@link -guide.compiler compile} and manage the whole HTML document. - - 3 <script src="file:///Users/krculp/angular.js/build/angular.min.js" ng:autobind></script> - -Lines __14__ and __15__ set up one side of angular's very cool two-way data binding, as well as -demonstrate some easy input validation: - - 14 Quantity: <input name="qty" value="1" ng:validate="integer:0" ng:required/> - 15 Cost: <input name="cost" value="199.95" ng:validate="number" ng:required/> - -These input widgets look normal enough, but consider these points: - -* Remember the `ng:autobind` directive from line 3? 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" part of the Model-View-Controller design pattern. -* Note the angular directives, {@link angular.widget.@ng:validate ng:validate} and {@link -angular.widget.@ng:required ng:required}. You may have noticed that when you enter invalid data or -leave the the input fields blank, the borders turn a plainly irritated red color, and the display -value disappears. These `ng:` directives make it easier to implement field validators than coding -them in JavaScript, no? Yes. - -And finally, the mysterious line #__19__: - - 19 Total: {{qty * cost | currency}} - -What's with the curly braces? Those curly braces are your friend. This notation, `{{ _expression_ -}}`, is a bit of built-in angular {@link angular.markup markup}, a shortcut that you use to display -data. The expression within curly braces gets transformed by the angular compiler into an angular -directive ({@link angular.directive.ng:bind ng:bind}). The expression itself can be a combination -of both an expression and a {@link angular.filter filter}: `{{ expression | filter }}`. - -In our example above, we're saying, "Bind the data we got from the input widgets to the display, -multiply them together, and format the resulting number into something that looks like money." - - -<a name="H1_3"></a> -# 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 clearly the way to -go 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 it by simply adding text to the HTML template, saving the code, and refreshing your -browser (this here is declarative): - -<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 looks like, let's see, do some math, factor out the `<pre>`s, carry the one, ummm... a little -bit 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 -what angular isn't: - -* 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 with 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. - - -<a name="H1_2"></a> -# Anatomy Of An Angular App - -This section describes the parts of an angular app in more detail. - -## Templates - -{@link guide.template Templates} are the part of angular that makes it easy and fun to create the -UI for your web apps. With angular's templates you can create a dynamic UI using only HTML and -CSS, but now you can add your own elements, attributes, and markup. The angular compiler reads the -"angularized" HTML when your page loads, and follows the instructions in there to generate a -dynamic page for you. This is the View part of MVC. "But wait there's more": since the compiler is -extensible, you can build your own declarative language on top of HTML! - -## Application Logic and Behavior - -Application Logic and Behavior, which you define in JavaScript, is the C in MVC. With angular you -write the logic (the controllers) for your app, but because angular takes care of reflecting the -state of the model in the view, you don't have to write listeners or DOM manipulators. This feature -makes your application logic very easy to write, test, maintain, and understand. - -## Data - -In an angular app, all of your data is referenced from inside of a {@link angular.scope scope}. -The scope is the data Model, the M in the MVC pattern. A scope is a JavaScript object that has -watcher functions that keep tabs on the data that is referenced from that scope. The data could be -one or more Javascript objects, arrays, or primitives, it doesn't matter. What matters is that -these are all referenced by the scope. - -This "scope thing" is how angular takes care of keeping your data model and your UI in sync. -Whenever something occurs to change the state of the scope, angular immediately reflects that -change in the UI, and vice versa. - -In addition to the three components described above (the MVC bits), angular comes with a set of -{@link angular.service Services} that are very helpful for building web apps. The services include -the following features: - -* You can extend and add application-specific behavior to services. -* Services include Dependency-Injection, XHR, caching, URL routing, and browser abstraction. - -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" /> - - -<a name="H1_4"></a> -# 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, knock yourself out. -* **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 (gah!) 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. - - -<a name="H1_5"></a> -# Angular's Ancestors - -Where does angular come from? What events led to the inevitability of the appearance of something -like angular? - -## First There Was HTML - -HTML was initially designed long, long ago, in the great year of 1989, with the intention to create -a markup language for sharing scientific documents over the network. Yes, yes, certainly there was -SGML even before that, but it was so difficult that even esteemed scientists balked at using it. -Thankfully, Tim Berners-Lee saved all of us from that pain with his much friendlier HTML. -`<HTML><BODY>Thank You, TB-L!</BODY></HTML>`. - -## Then There Was JavaScript - -Fast forward to 1995: JavaScript was invented. This was done with the best of intentions! But in -practice it initially served mainly to annoy Internet users with cheap effects that "enhanced" -static HTML documents. - -Fast forward to the mid 2000s, when a new breed of back-then-considered-rich web applications -started to appear on the web. These were built with HTML, JavaScript, and CSS, and featured less -annoying and more impressive effects. Can you recall the first time you saw apps like Gmail, or -Google Maps, and you couldn't believe everything that was going on in the browser? - -## And JavaScript Prevailed - -As of this writing, in 2011, people are building still richer and more interactive web applications -that often rival their desktop counterparts. And yet they are essentially still working with -technology and programming primitives that were used decades ago for the creation of static -documents with cheap graphic effects. At the same time, the web is HUGE now, and we -can't just abandon the technologies it was built with. Applets, Flash and Silverlight tried it, and -in some ways succeeded. Yet many would argue that in reality they failed, because they tried to -work _around_ the web instead of working _with_ it. - -## And Then There Was Angular - -Angular recognizes the strengths of the existing "static" web technologies, as well as their -deficiencies. At the same time, angular is learning from the failures of other technologies that -tried, or are trying, to work around the web. - -For these reasons angular plays to the strengths of established web technologies, instead of -bypassing them. Angular sets out the goal of increasing the abstraction and programming primitives -that developers use to build web applications, so as to better reflect the needs of modern web -applications and their developers. - - -<a name="H1_6"></a> -# 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} |