docs(dart): update BASICS intro (#1410)
Also copy edited the TS version a bit.
This commit is contained in:
Kathy Walrath
parent
5b1a84be4c
commit
a595eb81ef
|
|
@ -29,6 +29,10 @@
|
|||
- var _Promise = 'Promise';
|
||||
- var _Observable = 'Observable';
|
||||
|
||||
//- Location of sample code
|
||||
- var _liveLink = 'live link';
|
||||
|
||||
|
||||
//- Used to prefix identifiers that are private. In Dart this will be '_'.
|
||||
- var _priv = '';
|
||||
|
||||
|
|
|
|||
|
|
@ -11,6 +11,7 @@ include ../../../_includes/_util-fns
|
|||
- var _Lang = 'Dart';
|
||||
- var _Promise = 'Future';
|
||||
- var _Observable = 'Stream';
|
||||
- var _liveLink = 'sample repo';
|
||||
|
||||
mixin liveExampleLink(linkText, exampleUrlPartName)
|
||||
a(href='https://angular-examples.github.io/#{exampleUrlPartName}' target="_blank")= linkText
|
||||
|
|
|
|||
|
|
@ -1,93 +1,13 @@
|
|||
include ../_util-fns
|
||||
extends ../../../ts/latest/guide/index.jade
|
||||
|
||||
:marked
|
||||
This Developers Guide is a practical guide to Angular for experienced programmers who
|
||||
are building client applications in HTML and Dart.
|
||||
figure
|
||||
img(src="/resources/images/devguide/intro/people.png" alt="Us" align="left" style="width:200px; margin-left:-40px;margin-right:10px" )
|
||||
:marked
|
||||
We are on a journey together to understand how Angular works and, more importantly,
|
||||
how to make it work for us. We look at our application requirements and we see problems to solve.
|
||||
<br clear="all">
|
||||
block includes
|
||||
include ../_util-fns
|
||||
|
||||
* How do we get data onto the screen and handle user interactions?
|
||||
* How do we organize our code into manageable, cohesive chunks of functionality that work together?
|
||||
* What are the essential Angular building blocks and how do they help?
|
||||
* How do we minimize routine, mechanical coding in favor of declarative, higher level constructs without losing control?
|
||||
|
||||
This chapter begins the journey.
|
||||
|
||||
<a id="how-to-read"></a>
|
||||
:marked
|
||||
# How to read this guide
|
||||
Each chapter of this guide targets an Angular feature,
|
||||
showing how to use it to solve a programming problem.
|
||||
|
||||
All the chapters include code snippets ... snippets we can reuse in our own applications.
|
||||
Typically, these snippets are excerpts from a sample application that accompanies the chapter.
|
||||
|
||||
**All the source files** for each sample app are displayed together at the **end of each chapter.**
|
||||
|
||||
<!-- Although a few early chapters are written as tutorials, most later chapters
|
||||
don't explain how to build the accompanying sample.
|
||||
These non-tutorial chapters highlight key points in code but generally don't include the entire source. -->
|
||||
|
||||
<!-- We don't have to read this guide straight through. -->
|
||||
<!-- The "[Cheat Sheet](cheatsheet.html)" is a handy map to Angular overall. -->
|
||||
<!-- A few early chapters are arranged sequentially and best read together to establish a foundation in Angular.
|
||||
But most chapters stand on their own. We can browse to any of them as our interest or some necessity moves us. -->
|
||||
|
||||
Here is a learning path we might follow:
|
||||
|
||||
1. First, be familiar with Dart programming and with web concepts such as
|
||||
the DOM, HTML, and CSS. Dart tutorials such as
|
||||
[Get Started](https://www.dartlang.org/docs/tutorials/get-started/) and
|
||||
[Connect Dart & HTML](https://www.dartlang.org/docs/tutorials/connect-dart-html/)
|
||||
are a great way to start.
|
||||
|
||||
1. Follow the [QuickStart](../quickstart.html), which is the "Hello, World" of Angular 2.
|
||||
It shows how to set up the libraries and tools needed to write *any* Angular app.
|
||||
It ends with a "proof of life", a running Angular app.
|
||||
|
||||
1. Next, read the Developers Guide chapters in order:
|
||||
<!-- TODO: adjust this text once we have non-introductory/tutorial chapters -->
|
||||
1. The rest of this chapter, especially the Architecture overview
|
||||
1. [Displaying Data](displaying-data.html)
|
||||
1. [User Input](user-input.html)
|
||||
1. [Forms](forms.html)
|
||||
<!-- add dependency injection when it exists -->
|
||||
<!-- add text about template syntax, once that exists -->
|
||||
|
||||
1. Consider hopping over to the [TypeScript docs](/docs/ts/latest/)
|
||||
since they're currently ahead of the Dart docs. (We're working on that!)
|
||||
Especially check out the [Tutorial](/docs/ts/latest/tutorial/) and
|
||||
[Cheat Sheet](/docs/ts/latest/guide/cheatsheet.html), and the guide chapters
|
||||
[Dependency Injection](/docs/ts/latest/guide/dependency-injection.html)
|
||||
and [Template Syntax](/docs/ts/latest/guide/template-syntax.html).
|
||||
|
||||
<!-- Follow your own star from there, wherever it leads. -->
|
||||
|
||||
Don't miss the [Cheat Sheet](cheatsheet.html), a handy map to Angular.
|
||||
|
||||
<a id="toh"></a>
|
||||
.l-main-section
|
||||
:marked
|
||||
# Appendix: The Hero Staffing Agency
|
||||
|
||||
There's a backstory to the <!-- the "Tour of Heroes" and --> samples in this guide.
|
||||
|
||||
The world is full of crises large and small.
|
||||
Fortunately, courageous heroes are prepared to take on every challenge.
|
||||
The shadowy Hero Staffing Agency matches crises to heroes.
|
||||
|
||||
We are contract developers, hired by the Agency to build an application to manage their operations.
|
||||
The Agency maintains a stable of heroes with special powers.
|
||||
Ordinary humans submit crises as job requests. The heroes bid to take the job, and the Agency
|
||||
assigns each job accordingly.
|
||||
|
||||
Our application handles every detail of recruiting, tracking, and job assignment.
|
||||
For example, the [Forms](forms.html) chapter features a screen for
|
||||
entering personal information about heroes:
|
||||
|
||||
figure.image-display
|
||||
img(src="/resources/images/devguide/forms/hero-form-1.png" width="400px" alt="Clean Form")
|
||||
block example-links
|
||||
:marked
|
||||
Look for a link to that sample near the top of each page.
|
||||
For example, the sample repo https://github.com/angular-examples/architecture
|
||||
contains the code
|
||||
for the [Architecture](architecture.html) chapter's sample.
|
||||
A running version of that sample is at
|
||||
https://angular-examples.github.io/architecture/.
|
||||
|
|
|
|||
|
|
@ -1,4 +1,5 @@
|
|||
include ../_util-fns
|
||||
block includes
|
||||
include ../_util-fns
|
||||
|
||||
// #docregion intro
|
||||
- var langName = current.path[1] == 'ts' ? 'TypeScript' : 'JavaScript'
|
||||
|
|
@ -26,14 +27,16 @@ figure
|
|||
table(width="100%")
|
||||
col(width="15%")
|
||||
col
|
||||
tr(style=top)
|
||||
td <b>QuickStart</b>
|
||||
td
|
||||
:marked
|
||||
The foundation for every chapter and sample in this documentation.
|
||||
tr(style=top)
|
||||
td <b>Tutorial</b>
|
||||
td
|
||||
:marked
|
||||
A step-by-step, immersive approach to learning Angular.
|
||||
It begins with the [QuickStart](../quickstart.html),
|
||||
the foundation for every chapter and sample in this documentation,
|
||||
followed by the [*Tour of Heroes* tutorial](../tutorial) that
|
||||
A step-by-step, immersive approach to learning Angular that
|
||||
introduces the major features of Angular in an application context.
|
||||
tr(style=top)
|
||||
td <b>Basics</b>
|
||||
|
|
@ -44,36 +47,30 @@ table(width="100%")
|
|||
td <b>Developer Guide</b>
|
||||
td
|
||||
:marked
|
||||
In depth analysis of Angular features and development practices.
|
||||
In-depth analysis of Angular features and development practices.
|
||||
tr(style=top)
|
||||
td <b>Cookbook</b>
|
||||
td
|
||||
:marked
|
||||
Recipes for specific application challenges, mostly code snippets with a minimum of exposition.
|
||||
tr(style=top)
|
||||
td <b>Reference</b>
|
||||
td <b>API Reference</b>
|
||||
td
|
||||
:marked
|
||||
Angular-specific reference material, most notably the [API Guide](../api)
|
||||
with its authoritative details about each member in the Angular libraries.
|
||||
tr(style=top)
|
||||
td <b>Resources</b>
|
||||
td
|
||||
:marked
|
||||
Other places to go for help and information.
|
||||
Authoritative details about each member of the Angular libraries.
|
||||
:marked
|
||||
# Learning Path
|
||||
# Learning path
|
||||
We don't have to read the guide straight through. Most chapters stand on their own.
|
||||
|
||||
We recommend a learning path for those new to Angular.
|
||||
Most of that path runs through the *Basics* section:
|
||||
|
||||
1. Read the [Architecture Overview](architecture.html) to get the big picture.
|
||||
1. Read the [Architecture](architecture.html) overview to get the big picture.
|
||||
|
||||
1. Try the [QuickStart](../quickstart.html). The QuickStart is the "Hello, World" of Angular 2.
|
||||
It shows us how to setup the libraries and tools we'll need to write *any* Angular app.
|
||||
It shows us how to set up the libraries and tools we'll need to write *any* Angular app.
|
||||
|
||||
1. Take the *Tour of Heroes* [Tutorial](../tutorial) which picks up from where the QuickStart leaves off
|
||||
1. Take the *Tour of Heroes* [Tutorial](../tutorial), which picks up from where the QuickStart leaves off
|
||||
and builds a simple data-driven app.
|
||||
Simple, yes, but with the essential characteristics we'd expect of a professional application:
|
||||
a sensible project structure, data binding, master/detail, services, dependency injection, navigation, and remote data access.
|
||||
|
|
@ -87,7 +84,7 @@ table(width="100%")
|
|||
1. [Forms](forms.html) handle user data entry and validation within the UI.
|
||||
|
||||
1. [Dependency Injection](dependency-injection.html) is the way we build large, maintainable applications
|
||||
from small, single purpose parts.
|
||||
from small, single-purpose parts.
|
||||
|
||||
1. [Template Syntax](template-syntax.html) is a comprehensive study of Angular template HTML.
|
||||
|
||||
|
|
@ -95,28 +92,31 @@ table(width="100%")
|
|||
// #enddocregion how-to-read-2
|
||||
// #docregion the-rest
|
||||
:marked
|
||||
# Code Samples
|
||||
# Code samples
|
||||
|
||||
Every chapter includes code snippets that we can reuse in our own applications.
|
||||
These snippets are excerpts from a sample application that accompanies the chapter.
|
||||
|
||||
Look for a link to a running version of that sample near the top of each page
|
||||
such as this [live example](/resources/live-examples/architecture/ts/plnkr.html) from the [Architecture](architecture.html) chapter.
|
||||
block example-links
|
||||
:marked
|
||||
Look for a link to a running version of that sample near the top of each page,
|
||||
such as this [live example](/resources/live-examples/architecture/ts/plnkr.html) from the [Architecture](architecture.html) chapter.
|
||||
|
||||
The link launches a browser-based code editor where we can inspect, modify, save, and download the code.
|
||||
The link launches a browser-based code editor where we can inspect, modify, save, and download the code.
|
||||
|
||||
:marked
|
||||
A few early chapters are written as tutorials and are clearly marked as such.
|
||||
Most chapters are *not* tutorials.
|
||||
They highlight key points in code rather than explain each step necessary to build the sample.
|
||||
We can always get the full source by way of the live link.
|
||||
We can always get the full source by way of the #{_liveLink}.
|
||||
|
||||
## References
|
||||
# Reference pages
|
||||
|
||||
The [Cheat Sheet](cheatsheet.html) lists Angular syntax for common scenarios.
|
||||
|
||||
The [Glossary](glossary.html) defines terms that Angular developers should know.
|
||||
|
||||
The [API Guide](../api/) is the authority on every public-facing member of the Angular libraries.
|
||||
The [API Reference](../api/) is the authority on every public-facing member of the Angular libraries.
|
||||
|
||||
# Feedback
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue