aboutsummaryrefslogtreecommitdiffstats
path: root/docs/content/guide/introduction.ngdoc
diff options
context:
space:
mode:
authorTobias Bosch2013-11-05 22:16:11 -0800
committerTobias Bosch2013-11-06 17:11:44 -0800
commitfc060dfc08f048511fe78e9df04ce4616171da34 (patch)
tree71b912fb07c70b3e5c315577057b13c85b2032e6 /docs/content/guide/introduction.ngdoc
parent947a44d1ee6b253a5f31bb28616e0fa0303bd4aa (diff)
downloadangular.js-fc060dfc08f048511fe78e9df04ce4616171da34.tar.bz2
docs(guide/overview): Refactor overview and mvc docs
Before, there we multiple overview docs: - guide/overview - guide/introduction - guide/dev_guide.mvc - guide/dev_guide.mvc.understanding_model - guide/dev_guide.mvc.understanding_view - guide/concepts Now we have: - guide/introduction: High level description of Angular with the key benefits but without code or any concrete concepts - guide/concepts: explains all important concepts with a simple example and contains deep links to the other parts of the guide. All the old information was moved into existing documents or deleted when they were duplicates.
Diffstat (limited to 'docs/content/guide/introduction.ngdoc')
-rw-r--r--docs/content/guide/introduction.ngdoc132
1 files changed, 102 insertions, 30 deletions
diff --git a/docs/content/guide/introduction.ngdoc b/docs/content/guide/introduction.ngdoc
index dfd9e21a..415801a7 100644
--- a/docs/content/guide/introduction.ngdoc
+++ b/docs/content/guide/introduction.ngdoc
@@ -1,42 +1,114 @@
@ngdoc overview
-@name Developer Guide: Introduction
+@name Introduction
@description
-Angular is pure client-side technology, written entirely in JavaScript. It works with the
-long-established technologies of the web (HTML, CSS, and JavaScript) to make the development of
-web apps easier and faster than ever before.
-One important way that Angular simplifies web development is by increasing the level of abstraction
-between the developer and most low-level web app development tasks. Angular automatically takes
-care of many of these tasks, including:
+# What Is Angular?
- * DOM Manipulation
- * Setting Up Listeners and Notifiers
- * Input Validation
+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.
-Because Angular handles much of the work involved in these tasks, developers can concentrate more
-on application logic and less on repetitive, error-prone, lower-level coding.
+Angular is what HTML would have been had it been designed for applications. HTML is a great
+declarative language for static documents. It does not contain much in the way of creating
+applications, and as a result building web applications is an exercise in *what do I have to do
+to trick the browser into doing what I want.*
-At the same time that Angular simplifies the development of web apps, it brings relatively
-sophisticated techniques to the client-side, including:
+The impedance mismatch between dynamic applications and static documents is often solved with:
- * Separation of data, application logic, and presentation components
- * Data Binding between data and presentation components
- * Services (common web app operations, implemented as substitutable objects)
- * Dependency Injection (used primarily for wiring together services)
- * An extensible HTML compiler (written entirely in JavaScript)
- * Ease of Testing
+ * **a 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. E.g., `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. E.g., `knockout`, `ember`, etc.
-These techniques have been for the most part absent from the client-side for far too long.
-## Single-page / Round-trip Applications
+Angular takes another approach. It attempts to minimize the impedance mismatch between document
+centric HTML and what an application needs by creating new HTML constructs. Angular teaches the
+browser new syntax through a construct we call directives. Examples include:
-You can use Angular to develop both single-page and round-trip apps, but Angular is designed
-primarily for developing single-page apps. Angular supports browser history, forward and back
-buttons, and bookmarking in single-page apps.
+ * 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.
-You normally wouldn't want to load Angular with every page change, as would be the case with using
-Angular in a round-trip app. However, it would make sense to do so if you were adding a subset of
-Angular's features (for example, templates to leverage angular's data-binding feature) to an
-existing round-trip app. You might follow this course of action if you were migrating an older app
-to a single-page Angular app.
+
+
+## A complete client-side solution
+
+Angular is not a single piece in the overall puzzle of building the client-side of a web
+application. It handles all of the DOM and AJAX glue code you once wrote by hand and puts it in a
+well-defined structure. 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 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 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 with the CRUD application in mind. Luckily CRUD
+applications represent the majority of web applications. To understand what Angular is
+good at, though, it helps to understand when an app is not a good fit for Angular.
+
+Games and GUI editors are examples of applications with intensive and tricky DOM manipulation.
+These kinds of apps are different from CRUD apps, and as a result are probably not a good fit for Angular.
+In these cases it may be better to use a library with a lower level of abstraction, such as `jQuery`.
+
+# 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 pains:
+
+ * **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' tasks. 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 a presentation on Angular from May 2012. The {@link http://mhevery.github.io/angular-demo-slides/index.html#/list corresponding slides} are also available.
+
+<iframe width="560" height="315" src="http://www.youtube.com/embed/bfrn5VNpwsg" frameborder="0" allowfullscreen></iframe>