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
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
//- _docsFor: used to identify the language this version of the docs if for;
|
||||
//- Should be one of: 'ts', 'dart' or 'js'. Set in lang specific _util-fns file.
|
||||
- var _docsFor = '';
|
||||
- var _docsFor = '';
|
||||
|
||||
//- Should match `_docsFor`, but in this case provides the full capitalized
|
||||
//- name of the language.
|
||||
|
|
@ -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 = '';
|
||||
|
||||
|
|
@ -46,7 +50,7 @@ mixin adjExPath(path)
|
|||
| #{adjustExamplePath(path)}
|
||||
else
|
||||
| #{path}
|
||||
|
||||
|
||||
mixin includeShared(filePath, region)
|
||||
- var newPath = translatePath(filePath, region);
|
||||
!=partial(newPath)
|
||||
|
|
@ -69,8 +73,8 @@ mixin makeExample(_filePath, region, _title, stylePatterns)
|
|||
code-example(language="#{language}" format="#{format}")
|
||||
!= styleString(frag, stylePatterns)
|
||||
|
||||
//- Like makeExample, but the first argument is a path that is
|
||||
//- relative to the project root. Unless title is defined,
|
||||
//- Like makeExample, but the first argument is a path that is
|
||||
//- relative to the project root. Unless title is defined,
|
||||
//- the project relative path will be used.
|
||||
mixin makeProjExample(projRootRelativePath, region, title, stylePatterns)
|
||||
- var relPath = projRootRelativePath.trim();
|
||||
|
|
@ -83,7 +87,7 @@ mixin makeProjExample(projRootRelativePath, region, title, stylePatterns)
|
|||
+makeExample(filePath, region, title, stylePatterns)
|
||||
|
||||
//- Like makeExample, but doesn't show line numbers, and the first
|
||||
//- argument is a path that is relative to the example project root.
|
||||
//- argument is a path that is relative to the example project root.
|
||||
//- Unless title is defined, the project relative path will be used.
|
||||
//- Title will always end with a phrase in parentheses; if no such
|
||||
//- ending is given, then the title will be suffixed with
|
||||
|
|
@ -164,7 +168,7 @@ script.
|
|||
el.style.display = isVerbose ? 'block' : 'none';
|
||||
var el = document.querySelector('button.verbose.on');
|
||||
el.style.display = isVerbose ? 'none' : 'block';
|
||||
|
||||
|
||||
CCSStylesheetRuleStyle('main','.l-verbose-section', 'display',
|
||||
isVerbose ? 'block' : 'none');
|
||||
}
|
||||
|
|
|
|||
|
|
@ -11,13 +11,14 @@ 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
|
||||
|
||||
mixin liveExampleLink2(linkText, exampleUrlPartName)
|
||||
- var liveExampleSourceLinkText = attributes.srcLinkText || 'view source'
|
||||
| #[+liveExampleLink(linkText, exampleUrlPartName)]
|
||||
| #[+liveExampleLink(linkText, exampleUrlPartName)]
|
||||
| (#[a(href='https://github.com/angular-examples/#{exampleUrlPartName}' target="_blank") #{liveExampleSourceLinkText}])
|
||||
|
||||
- var adjustExamplePath = function(_path) {
|
||||
|
|
@ -29,7 +30,7 @@ mixin liveExampleLink2(linkText, exampleUrlPartName)
|
|||
- var baseName = getBaseFileName(path) || path; // TODO: have getBaseFileName() return path
|
||||
- var baseNameNoExt = baseName.substr(0,baseName.length - (extn.length + 1));
|
||||
- var inWebFolder = baseNameNoExt.match(/^(main|index(\.\d)?)$/);
|
||||
- // Adjust the folder path, e.g., ts -> dart
|
||||
- // Adjust the folder path, e.g., ts -> dart
|
||||
- folder = folder.replace(/(^|\/)ts($|\/)/, '$1dart$2').replace(/(^|\/)app($|\/)/, inWebFolder ? '$1web$2' : '$1lib$2');
|
||||
- // Special case not handled above: e.g., index.html -> web/index.html
|
||||
- if(baseNameNoExt.match(/^(index|styles)(\.\d)?$/)) folder = (folder ? folder + '/' : '') + 'web';
|
||||
|
|
|
|||
|
|
@ -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'
|
||||
|
|
@ -17,7 +18,7 @@ figure
|
|||
<a id="learning-path"></a>
|
||||
:marked
|
||||
# Organization
|
||||
|
||||
|
||||
The documentation is divided into major thematic sections, each
|
||||
a collection of chapters devoted to that theme.
|
||||
// #enddocregion how-to-read-1
|
||||
|
|
@ -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,86 +47,83 @@ 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
|
||||
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.
|
||||
# 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. 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.
|
||||
|
||||
1. Take the *Tour of Heroes* [Tutorial](../tutorial) which picks up from where the QuickStart leaves off
|
||||
and builds a simple data-driven app.
|
||||
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 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
|
||||
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.
|
||||
|
||||
a sensible project structure, data binding, master/detail, services, dependency injection, navigation, and remote data access.
|
||||
|
||||
Return to the *Basics* section and continue in the suggested order:
|
||||
|
||||
|
||||
1. [Displaying Data](displaying-data.html) explains how to get information on to the screen.
|
||||
|
||||
|
||||
1. [User Input](user-input.html) covers the basics of responding to user behavior.
|
||||
|
||||
|
||||
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.
|
||||
|
||||
1. [Template Syntax](template-syntax.html) is a comprehensive study of Angular template HTML.
|
||||
from small, single-purpose parts.
|
||||
|
||||
1. [Template Syntax](template-syntax.html) is a comprehensive study of Angular template HTML.
|
||||
|
||||
With this foundation, we can read and understand any chapter in the guide.
|
||||
// #enddocregion how-to-read-2
|
||||
// #docregion the-rest
|
||||
:marked
|
||||
# Code Samples
|
||||
|
||||
Every chapter includes code snippets that we can reuse in our own applications.
|
||||
# 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.
|
||||
|
||||
The link launches a browser-based code editor where we can inspect, modify, save, and download the code.
|
||||
|
||||
A few early chapters are written as tutorials and are clearly marked as such.
|
||||
Most chapters are *not* tutorials.
|
||||
|
||||
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.
|
||||
|
||||
: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.
|
||||
|
||||
## References
|
||||
|
||||
We can always get the full source by way of the #{_liveLink}.
|
||||
|
||||
# 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
|
||||
|
||||
|
||||
We welcome feedback! Leave a comment by clicking the icon in upper right corner of the banner.
|
||||
|
||||
Post *documentation* issues and pull requests on the
|
||||
|
||||
Post *documentation* issues and pull requests on the
|
||||
[angular.io](https://github.com/angular/angular.io) github repository.
|
||||
|
||||
|
||||
Post issues with *Angular 2 itself* to the [angular](https://github.com/angular/angular) github repository.
|
||||
// #enddocregion the-rest
|
||||
|
|
|
|||
Loading…
Reference in New Issue