docs(aio): revised "Docs" page
This commit is contained in:
Ward Bell
Pete Bacon Darwin
parent
3d06b18fee
commit
4ac5096232
|
|
@ -1,48 +1,79 @@
|
|||
@title
|
||||
Angular Docs
|
||||
# Angular Docs
|
||||
|
||||
@description
|
||||
Welcome to the Angular documentation where you'll find guidance for beginners and experts alike.
|
||||
|
||||
<div class="card-container clearfix">
|
||||
## What is Angular?
|
||||
|
||||
<a href="./guide/quickstart" class="card">
|
||||
<h2>Quickstart</h2>
|
||||
<p>A quick look at an Angular application.</p>
|
||||
<p class="card-footer">View Quickstart</p>
|
||||
</a>
|
||||
Angular is a platform for building and running web applications on desktop and mobile devices.
|
||||
It's an architecture, a modular library, and a set of tools to help teams
|
||||
build amazing web apps that run anywhere at scales large and small.
|
||||
|
||||
<a href="guide/learning-angular" class="card">
|
||||
<h2>Getting Started</h2>
|
||||
<p>A beginner's guide to basic Angular concepts.</p>
|
||||
<p class="card-footer">View Getting Started</p>
|
||||
</a>
|
||||
## Organization
|
||||
|
||||
<a href="tutorial" class="card">
|
||||
<h2>Tutorial</h2>
|
||||
<p>The "Tour of Heroes" tutorial, a step-by-step.</p>
|
||||
<p class="card-footer">View Tutorial</p>
|
||||
</a>
|
||||
Navigate the docs with the tree-view in the left side panel. Each top level category unfolds into topics that cover Angular from a distinct perspective:
|
||||
|
||||
<a href="api" class="card">
|
||||
<h2>API Reference</h2>
|
||||
<p>The developer's reference to Angular classes, methods, etc.</p>
|
||||
<p class="card-footer">View API Reference</p>
|
||||
</a>
|
||||
- **Getting Started** is a taste of Angular in under five minutes.
|
||||
|
||||
<a href="guide/fundamentals" class="card">
|
||||
<h2>Core Guide</h2>
|
||||
<p>The Fundamentals of Angular.</p>
|
||||
<p class="card-footer">View Fundamentals</p>
|
||||
</a>
|
||||
- **Tutorial** is a step-by-step introduction to the essentials of Angular as you build a data-driven application with multi-page navigation.
|
||||
|
||||
<a href="guide/techniques" class="card">
|
||||
<h2>Angular Techniques</h2>
|
||||
<p>Techniques for setting up, configuring, and deploying your application.</p>
|
||||
<p class="card-footer">View Techniques</p>
|
||||
</a>
|
||||
<div class="alert is-important">
|
||||
|
||||
<div>
|
||||
If you're new to Angular, we recommend that you start with these two categories before moving selectively through the others.
|
||||
|
||||
</div>
|
||||
|
||||
- **Fundamentals** explains each Angular concept and feature in practical terms with loads of examples.
|
||||
|
||||
- **Techniques** covers tools and techniques for setting up, testing, securing, and deploying your application.
|
||||
|
||||
- **API** is the comprehensive, searchable documentation for every Angular class, interface, and programmable feature.
|
||||
|
||||
- **References** include answers to common questions about usage and style.
|
||||
|
||||
## Sample code
|
||||
|
||||
<style>live-example a {font-weight: 800}</style>
|
||||
|
||||
Guide pages are full of code snippets that you can copy and use in your own projects. The snippets are typically drawn from an example app.
|
||||
Look for the <live-example name="quickstart" noDownload style="font-weight: 800 !important;"></live-example> **link** that launches a browser-based editor where you can see it run, inspect the code, modify it, and save changes.
|
||||
|
||||
In most cases you can also <live-example name="quickstart" downloadOnly>download the example,</live-example>
|
||||
unzip it, and run locally with these terminal commands:
|
||||
|
||||
<code-example language="sh" class="code-shell" linenums="false">
|
||||
npm install
|
||||
npm start
|
||||
</code-example>
|
||||
|
||||
## Assumptions
|
||||
|
||||
While we strive to keep these pages beginner-friendly, we have to make a few assumptions about your skills and experience in order to stay focused on Angular.
|
||||
|
||||
We assume that you are a seasoned, front-end web developer with a working knowledge of
|
||||
**HTML, CSS, JavaScript**. The [Mozilla Developer Network](https://developer.mozilla.org/en-US/ "MDN - Mozilla Developer Network") is an excellent resource for reference and general learning.
|
||||
|
||||
Effective Angular developers become familiar with two other technologies:
|
||||
|
||||
**npm** - Modern web development depends on the [npm package management](https://www.npmjs.com/ "npm") system for distribution and installation of third party libraries. Angular is one such library.
|
||||
|
||||
**TypeScript** - [TypeScript](http://www.typescriptlang.org/ "TypeScript") is a _typed_ superset of JavaScript. For the most part it is ES2015 JavaScript with type annotations to improve your design time experience and make it easier for teams to develop sophisticated applications.
|
||||
|
||||
You _can_ write Angular applications in [JavaScript without TypeScript](guide/ts-to-js "Writing Angular in JavaScript"). But you should be able to _read_ TypeScript to understand this documentation and participate in conversations within the Angular community. The Angular CLI productivity tool and AOT high performance compiler only apply to TypeScript applications.
|
||||
|
||||
You don't have to be an expert in npm or TypeScript to get started with Angular. A little knowledge will get you going and you can pick up what you need along the way.
|
||||
|
||||
## Versions
|
||||
|
||||
This is the Angular **version 4** documentation. See what's new in the [documentation changelog](guide/change-log). View the [Angular change log](https://github.com/angular/angular/blob/master/CHANGELOG.md) for enhancement and fixes to Angular itself.
|
||||
|
||||
The Angular **version 2** documentation has been archived at [v2.angular.io](https://v2.angular.io "Angular v2 Docs").
|
||||
|
||||
|
||||
## Feedback
|
||||
|
||||
We welcome feedback!
|
||||
|
||||
You can file documentation [issues](https://github.com/angular/angular/issues "Angular Github Issues") and create [pull requests](https://github.com/angular/angular/pulls "Angular Github PRs") on the Angular Github repository.
|
||||
Please prefix your issue or pull request title with "**docs:**" so that we know it concerns _documentation_ and draws the prompt attention of the appropriate people.
|
||||
|
||||
Remember that a respectful, supportive approach produce the best results. Please consult and adhere to our [code of conduct](https://github.com/angular/code-of-conduct/blob/master/CODE_OF_CONDUCT.md "contributor code of conduct") when engaging with the Angular community.
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
@title
|
||||
Fundamentals of Angular
|
||||
|
||||
@description
|
||||
Learn the fundamental features of Angular in this section of the guide.
|
||||
|
|
@ -1,58 +0,0 @@
|
|||
@title
|
||||
Learning Angular
|
||||
|
||||
@intro
|
||||
A suggested path through the documentation for Angular newcomers.
|
||||
|
||||
@description
|
||||
|
||||
|
||||
|
||||
<figure>
|
||||
<img src="assets/images/guide/intro/people.png" width="200px" height="152px" alt="Us" align="left" style="margin-left:-40px;margin-right:10px"></img>
|
||||
</figure>
|
||||
|
||||
|
||||
|
||||
Everyone learns differently.
|
||||
You don't have to read the documentation straight through. Most pages stand on their own.
|
||||
Those new to Angular may wish to follow this popular learning path.
|
||||
<br class="l-clear-left">
|
||||
|
||||
1. [Setup](guide/setup "Setup locally withe Quickstart seed") for local Angular development, if you haven't already done so.
|
||||
|
||||
1. Take the [*Tour of Heroes* tutorial](tutorial "Tour of Heroes").
|
||||
|
||||
The *Tour of Heroes* takes you step-by-step from [setup](guide/setup)
|
||||
to a full-featured example that demonstrates the essential characteristics of a professional application:
|
||||
a sensible project structure, data binding, master/detail, services, dependency injection, navigation, and remote data access.
|
||||
|
||||
1. {@a architecture}Read the [Architecture](guide/architecture) overview for the big picture.
|
||||
|
||||
1. [The Root Module](guide/appmodule) introduces the `NgModule` class that tells Angular how to compile and run your application.
|
||||
|
||||
1. [Displaying Data](guide/displaying-data) shows how data binding puts component property values on screen.
|
||||
|
||||
1. [User Input](guide/user-input) explains how to respond to user-initiated DOM events.
|
||||
|
||||
1. [Forms](guide/forms) covers data entry and validation within the UI.
|
||||
|
||||
1. [Dependency Injection](guide/dependency-injection) is the way to build large, maintainable applications
|
||||
from small, single-purpose parts.
|
||||
|
||||
1. [Template Syntax](guide/template-syntax) is a comprehensive study of Angular template HTML.
|
||||
|
||||
After reading the above sections, feel free to skip around among the other pages on this site.
|
||||
|
||||
|
||||
<div class="l-sub-section">
|
||||
|
||||
|
||||
|
||||
### Next Step
|
||||
|
||||
Try the [tutorial](tutorial "Tour of Heroes") if you're ready to start coding or
|
||||
visit the [Architecture](guide/architecture "Basic Concepts") page if you prefer to learn the basic concepts first.
|
||||
|
||||
</div>
|
||||
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
@title
|
||||
Techniques
|
||||
|
||||
@description
|
||||
Learn important Angular application techniques such as how to setup, secure, and deploy your application.
|
||||
|
|
@ -88,7 +88,6 @@
|
|||
|
||||
{
|
||||
"title": "Fundamentals",
|
||||
"url": "guide/fundamentals",
|
||||
"tooltip": "The fundamentals of Angular",
|
||||
"children": [
|
||||
|
||||
|
|
@ -261,7 +260,6 @@
|
|||
|
||||
{
|
||||
"title": "Techniques",
|
||||
"url": "guide/techniques",
|
||||
"tooltip": "Techniques for putting Angular to work in your environment",
|
||||
"children": [
|
||||
|
||||
|
|
|
|||
|
|
@ -9,6 +9,9 @@
|
|||
You can also <a [href]="zip" download title="Download example">download this example</a>.
|
||||
</p>
|
||||
</span>
|
||||
<span *ngSwitchCase="'downloadOnly'">
|
||||
<a [href]="zip" download title="{{title}}">{{title}}</a>
|
||||
</span>
|
||||
<span *ngSwitchDefault>
|
||||
<a [href]="plnkr" target="_blank" title="{{title}}">{{title}}</a>
|
||||
<span *ngIf="enableDownload">
|
||||
|
|
|
|||
|
|
@ -167,10 +167,20 @@ describe('LiveExampleComponent', () => {
|
|||
it('should not have a download link when `noDownload` atty present', async(() => {
|
||||
setHostTemplate('<live-example noDownload></live-example>');
|
||||
testComponent(() => {
|
||||
expect(getAnchors().length).toBe(1, 'only the live-example anchor');
|
||||
const hrefs = getHrefs();
|
||||
expect(hrefs.length).toBe(1, 'only the plunker live-example anchor');
|
||||
expect(hrefs[0]).toContain('plnkr.html');
|
||||
});
|
||||
}));
|
||||
|
||||
it('should only have a download link when `downloadOnly` atty present', async(() => {
|
||||
setHostTemplate('<live-example downloadOnly>download this</live-example>');
|
||||
testComponent(() => {
|
||||
const hrefs = getHrefs();
|
||||
expect(hrefs.length).toBe(1, 'only the zip anchor');
|
||||
expect(hrefs[0]).toContain('.zip'); });
|
||||
}));
|
||||
|
||||
it('should have default title when no title attribute or content', async(() => {
|
||||
setHostTemplate('<live-example></live-example>');
|
||||
testComponent(() => {
|
||||
|
|
|
|||
|
|
@ -23,6 +23,7 @@ const zipBase = 'content/zips/';
|
|||
* [embedded-style] // show plnkr in embedded style (default and on narrow screens)
|
||||
* [flat-style] // show plnkr in flat (original) style
|
||||
* [noDownload] // no downloadable zip option
|
||||
* [downloadOnly] // just the zip
|
||||
* [title="..."]> // text for live example link and tooltip
|
||||
* text // higher precedence way to specify text for live example link and tooltip
|
||||
* </live-example>
|
||||
|
|
@ -99,7 +100,12 @@ export class LiveExampleComponent implements OnInit {
|
|||
|
||||
const noDownload = this.getAttrValue(['noDownload', 'nodownload']); // noDownload aliases
|
||||
this.enableDownload = !boolFromAtty(noDownload);
|
||||
|
||||
this.plnkrImg = imageBase + (attrs.img || defaultPlnkrImg);
|
||||
|
||||
if (boolFromAtty(this.getAttrValue(['downloadOnly', 'downloadonly']))) {
|
||||
this.mode = 'downloadOnly';
|
||||
}
|
||||
}
|
||||
|
||||
calcPlnkrLink(width: number) {
|
||||
|
|
@ -154,7 +160,9 @@ export class LiveExampleComponent implements OnInit {
|
|||
|
||||
@HostListener('window:resize', ['$event.target.innerWidth'])
|
||||
onResize(width) {
|
||||
this.calcPlnkrLink(width);
|
||||
if (this.mode !== 'downloadOnly') {
|
||||
this.calcPlnkrLink(width);
|
||||
}
|
||||
}
|
||||
|
||||
toggleEmbedded () { this.showEmbedded = !this.showEmbedded; }
|
||||
|
|
|
|||
Loading…
Reference in New Issue