From 7f1e2e48467f80cc083d24b44f088620e4e7bcb6 Mon Sep 17 00:00:00 2001 From: Igor Minar Date: Mon, 6 Jun 2011 08:50:35 -0700 Subject: new batch of docs --- docs/content/guide/dev_guide.overview.ngdoc | 288 ++++++++++++++++++++++++++++ 1 file changed, 288 insertions(+) create mode 100644 docs/content/guide/dev_guide.overview.ngdoc (limited to 'docs/content/guide/dev_guide.overview.ngdoc') diff --git a/docs/content/guide/dev_guide.overview.ngdoc b/docs/content/guide/dev_guide.overview.ngdoc new file mode 100644 index 00000000..7eb56470 --- /dev/null +++ b/docs/content/guide/dev_guide.overview.ngdoc @@ -0,0 +1,288 @@ +@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: + + + + + Invoice: +
+
+ + + + + + + +
QuantityCost
+
+ Total: {{qty * cost | currency}} + + + + + +Try out the Live Preview above, and then let's walk through the example and describe what's going +on. + + +In the `` tag, we add an attribute to let the browser know about the angular namespace: + + + + + +This ensures angular runs nicely in all major browsers. + + +In the `` + + +From the `name` attribute of the `` tags, angular automatically sets up two-way data +binding, and we also demonstrate some easy input validation: + + + Quantity: + Cost: + + +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 directives, {@link api/angular.widget.@ng:validate ng:validate} and {@link +api/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 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 `{{ double curly braces }}`: + + + Total: {{qty * cost | currency}} + + +This notation, `{{ _expression_ }}`, is a bit of built-in angular {@link dev_guide.compiler.markup +markup}, a shortcut for displaying data to the user. The expression within curly braces gets +transformed by the angular compiler into an angular directive ({@link api/angular.directive.ng:bind +ng:bind}). 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: + + +
+Hello
+
+ + +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: + + +
+var label = new Label();
+label.setText('Hello');
+label.setClass('label');
+parent.addChild(label);
+
+ + +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. + + + + + + + + + + +{@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} -- cgit v1.2.3