From 0e3eeb4e7144a6480b3d7af31f630eac576d92f8 Mon Sep 17 00:00:00 2001 From: Judy Bogart Date: Wed, 8 Jan 2020 12:18:18 -0800 Subject: [PATCH] docs: restructure nav for beginner concepts (#34681) PR Close #34681 --- aio/content/guide/architecture-next-steps.md | 73 ++++++++++++++------ aio/content/guide/architecture.md | 20 ++++-- aio/content/marketing/docs.md | 27 ++++---- aio/content/navigation.json | 72 +++++++++---------- 4 files changed, 116 insertions(+), 76 deletions(-) diff --git a/aio/content/guide/architecture-next-steps.md b/aio/content/guide/architecture-next-steps.md index 53f5ba4c9a..10999c9e00 100644 --- a/aio/content/guide/architecture-next-steps.md +++ b/aio/content/guide/architecture-next-steps.md @@ -1,55 +1,88 @@ # Next steps: tools and techniques -After you understand the basic Angular building blocks, you can begin to learn more -about the features and tools that are available to help you develop and deliver Angular applications. -Here are some key features. +After you understand the basic Angular building blocks, you can learn more +about the features and tools that can help you develop and deliver Angular applications. + +* Work through the [Tour of Heroes](tutorial/index) tutorial to get a feel for how to fit the basic building blocks together to create a well-designed application. + +* Check out the [Glossary](guide/glossary) to understand Angular-specific terms and usage. + +* Use the documentation to learn about key features in more depth, according to your stage of development and areas of interest. + +## Application architecture + +* The [NgModules](guide/ngmodules) guide provides in-depth information on the modular structure of an Angular application. + +* The [Routing and navigation](guide/router) guide provides in-depth information on how to construct applications that allow a user to navigate to different [views](guide/glossary#view) within your single-page app. + +* The [Dependency injection](guide/dependency-injection) guide provides in-depth information on how to construct an application such that each component class can acquire the services and objects it needs to perform its function. ## Responsive programming +The **Components and Templates** guide provides guidance and details of the [template syntax](guide/template-syntax) that you use to display your component data when and where you want it within a view, and to collect input from users that you can respond to. + +Additional pages and sections describe some basic programming techniques for Angular apps. + * [Lifecycle hooks](guide/lifecycle-hooks): Tap into key moments in the lifetime of a component, from its creation to its destruction, by implementing the lifecycle hook interfaces. * [Observables and event processing](guide/observables): How to use observables with components and services to publish and subscribe to messages of any type, such as user-interaction events and asynchronous operation results. -## Client-server interaction +* [Angular elements](guide/elements): How to package components as *custom elements* using Web Components, a web standard for defining new HTML elements in a framework-agnostic way. -* [HTTP](guide/http): Communicate with a server to get data, save data, and invoke server-side actions with an HTTP client. - -* [Server-side Rendering](guide/universal): Angular Universal generates static application pages on the server through server-side rendering (SSR). This allows you to run your Angular app on the server in order to improve performance and show the first page quickly on mobile and low-powered devices, and also facilitate web crawlers. - -* [Service Workers](guide/service-worker-intro): Use a service worker to reduce dependency on the network -significantly improving the user experience. - -## Domain-specific libraries +* [Forms](guide/forms-overview): Support complex data entry scenarios with HTML-based input validation. * [Animations](guide/animations): Use Angular's animation library to animate component behavior without deep knowledge of animation techniques or CSS. -* [Forms](guide/forms): Support complex data entry scenarios with HTML-based validation and dirty checking. +## Client-server interaction + +Angular provides a framework for single-page apps, where most of the logic and data resides on the client. +Most apps still need to access a server using the `HttpClient` to access and save data. +For some platforms and applications, you might also want to use the PWA (Progressive Web App) model to improve the user experience. + +* [HTTP](guide/http): Communicate with a server to get data, save data, and invoke server-side actions with an HTTP client. + +* [Server-side rendering](guide/universal): Angular Universal generates static application pages on the server through server-side rendering (SSR). This allows you to run your Angular app on the server in order to improve performance and show the first page quickly on mobile and low-powered devices, and also facilitate web crawlers. + +* [Service workers and PWA](guide/service-worker-intro): Use a service worker to reduce dependency on the network and significantly improve the user experience. + +* [Web workers](guide/web-worker): Learn how to run CPU-intensive computations in a background thread. ## Support for the development cycle +The **Development Workflow** section describes the tools and processes you use to compile, test, and and deploy Angular applications. + +* [CLI Command Reference](cli): The Angular CLI is a command-line tool that you use to create projects, generate application and library code, and perform a variety of ongoing development tasks such as testing, bundling, and deployment. + * [Compilation](guide/aot-compiler): Angular provides just-in-time (JIT) compilation for the development environment, and ahead-of-time (AOT) compilation for the production environment. * [Testing platform](guide/testing): Run unit tests on your application parts as they interact with the Angular framework. -* [Internationalization](guide/i18n): Make your app available in multiple languages with Angular's internationalization (i18n) tools. +* [Deployment](guide/deployment): Learn techniques for deploying your Angular application to a remote server. * [Security guidelines](guide/security): Learn about Angular's built-in protections against common web-app vulnerabilities and attacks such as cross-site scripting attacks. -## Setup, build, and deployment configuration +* [Internationalization](guide/i18n): Make your app available in multiple languages with Angular's internationalization (i18n) tools. -* [CLI Command Reference](cli): The Angular CLI is a command-line tool that you use to create projects, generate application and library code, and perform a variety of ongoing development tasks such as testing, bundling, and deployment. +* [Accessibility](guide/accessibility): Make your app accessible to all users. -* [Workspace and File Structure](guide/file-structure): Understand the structure of Angular workspace and project folders. -* [npm Packages](guide/npm-packages): The Angular Framework, Angular CLI, and components used by Angular applications are packaged as [npm](https://docs.npmjs.com/) packages and distributed via the npm registry. The Angular CLI creates a default `package.json` file, which specifies a starter set of packages that work well together and jointly support many common application scenarios. +## File structure, configuration, and dependencies + +* [Workspace and file structure](guide/file-structure): Understand the structure of Angular workspace and project folders. + +* [Building and serving](guide/build): Learn to define different build and proxy server configurations for your project, such as development, staging, and production. + +* [npm packages](guide/npm-packages): The Angular Framework, Angular CLI, and components used by Angular applications are packaged as [npm](https://docs.npmjs.com/) packages and distributed via the npm registry. The Angular CLI creates a default `package.json` file, which specifies a starter set of packages that work well together and jointly support many common application scenarios. * [TypeScript configuration](guide/typescript-configuration): TypeScript is the primary language for Angular application development. * [Browser support](guide/browser-support): Make your apps compatible across a wide range of browsers. -* [Building and Serving](guide/build): Learn to define different build and proxy server configurations for your project, such as development, staging, and production. +## Extending Angular -* [Deployment](guide/deployment): Learn techniques for deploying your Angular application to a remote server. +* [Angular libraries](guide/libraries): Learn about using and creating re-usable libraries. +* [Schematics](guide/schematics): Learn about customizing and extending the CLI's generation capabilities. +* [CLI builders](guide/cli-builder): Learn about customizing and extending the CLI's ability to apply tools to perform complex tasks, such as building and testing applications. diff --git a/aio/content/guide/architecture.md b/aio/content/guide/architecture.md index 427583c50f..47ea5432e0 100644 --- a/aio/content/guide/architecture.md +++ b/aio/content/guide/architecture.md @@ -1,11 +1,13 @@ -# Architecture overview +# Introduction to Angular concepts -Angular is a platform and framework for building client applications in HTML and TypeScript. -Angular is written in TypeScript. It implements core and optional functionality as a set of TypeScript libraries that you import into your apps. +Angular is a platform and framework for building single-page client applications in HTML and TypeScript. +Angular is written in TypeScript. +It implements core and optional functionality as a set of TypeScript libraries that you import into your apps. -The basic building blocks of an Angular application are *NgModules*, which provide a compilation context for *components*. NgModules collect related code into functional sets; an Angular app is defined by a set of NgModules. An app always has at least a *root module* that enables bootstrapping, and typically has many more *feature modules*. +The architecture of an Angular application relies on certain fundamental concepts. +The basic building blocks are *NgModules*, which provide a compilation context for *components*. NgModules collect related code into functional sets; an Angular app is defined by a set of NgModules. An app always has at least a *root module* that enables bootstrapping, and typically has many more *feature modules*. -* Components define *views*, which are sets of screen elements that Angular can choose among and modify according to your program logic and data. +* Components define *views*, which are sets of screen elements that Angular can choose among and modify according to your program logic and data. * Components use *services*, which provide specific functionality not directly related to views. Service providers can be *injected* into components as *dependencies*, making your code modular, reusable, and efficient. @@ -17,6 +19,12 @@ Both components and services are simply classes, with *decorators* that mark the An app's components typically define many views, arranged hierarchically. Angular provides the `Router` service to help you define navigation paths among views. The router provides sophisticated in-browser navigational capabilities. +
Introduction to the Angular Docs +Angular is an app-design framework and development platform for creating efficient and sophisticated single-page apps. - -These Angular docs help you learn and use the Angular platform and framework, from your first app to optimizing complex enterprise apps. -Tutorials and guides include downloadable example to accelerate your projects. +These Angular docs help you learn and use the Angular framework and development platform, from your first app to optimizing complex single-page apps for enterprises. +Tutorials and guides include downloadable examples to accelerate your projects.
Learn
-

Create your first Angular app, without any setup

-

Getting Started

+

Play with and extend a small ready-made Angular app, without any setup

+

Getting Started

 @@ -18,10 +18,10 @@ Tutorials and guides include downloadable example to accelerate your projects.

Set up your local environment with the Angular CLI

Local Setup

 - +
Explore
-

Learn more about Angular apps and framework features

-

Architecture

+

Learn about the fundamental design concepts and architecture of Angular apps

+

Introduction to Angular concepts
@@ -29,13 +29,13 @@ Tutorials and guides include downloadable example to accelerate your projects. ## Assumptions -These docs assume that you are already familiar with [HTML](https://developer.mozilla.org/docs/Learn/HTML/Introduction_to_HTML "Learn HTML"), [CSS](https://developer.mozilla.org/docs/Learn/CSS/First_steps "Learn CSS"), [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript/A_re-introduction_to_JavaScript "Learn JavaScript"), -and some of the tools from the [latest standards](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Language_Resources "Latest JavaScript standards"), such as [classes](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes "ES2015 Classes") and [modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import "ES2015 Modules"). -The code samples are written using [TypeScript](https://www.typescriptlang.org/ "TypeScript"). +These docs assume that you are already familiar with [HTML](https://developer.mozilla.org/docs/Learn/HTML/Introduction_to_HTML "Learn HTML"), [CSS](https://developer.mozilla.org/docs/Learn/CSS/First_steps "Learn CSS"), [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript/A_re-introduction_to_JavaScript "Learn JavaScript"), +and some of the tools from the [latest standards](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Language_Resources "Latest JavaScript standards"), such as [classes](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes "ES2015 Classes") and [modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import "ES2015 Modules"). +The code samples are written using [TypeScript](https://www.typescriptlang.org/ "TypeScript"). Most Angular code can be written with just the latest JavaScript, using [types](https://www.typescriptlang.org/docs/handbook/classes.html "TypeScript Types") for dependency injection, and using [decorators](https://www.typescriptlang.org/docs/handbook/decorators.html "Decorators") for metadata. -## Feedback +## Feedback

You can sit with us!

@@ -45,8 +45,7 @@ Contribute to Angular docs by creating [pull requests](https://github.com/angular/angular/pulls "Angular Github pull requests") on the Angular Github repository. See [Contributing to Angular](https://github.com/angular/angular/blob/master/CONTRIBUTING.md "Contributing guide") -for information about submission guidelines. +for information about submission guidelines. Our community values respectful, supportive communication. Please consult and adhere to the [Code of Conduct](https://github.com/angular/code-of-conduct/blob/master/CODE_OF_CONDUCT.md "Contributor code of conduct"). - diff --git a/aio/content/navigation.json b/aio/content/navigation.json index 6428757c59..5e236bc44a 100644 --- a/aio/content/navigation.json +++ b/aio/content/navigation.json @@ -97,6 +97,37 @@ "title": "Fundamentals", "tooltip": "The fundamentals of Angular", "children": [ + { + "title": "Angular Concepts", + "tooltip": "Introduction to basic concepts for Angular applications.", + "children": [ + { + "url": "guide/architecture", + "title": "Intro to Basic Concepts", + "tooltip": "Basic building blocks of Angular applications." + }, + { + "url": "guide/architecture-modules", + "title": "Intro to Modules", + "tooltip": "About NgModules." + }, + { + "url": "guide/architecture-components", + "title": "Intro to Components", + "tooltip": "About Components, Templates, and Views." + }, + { + "url": "guide/architecture-services", + "title": "Intro to Services and DI", + "tooltip": "About services and dependency injection." + }, + { + "url": "guide/architecture-next-steps", + "title": "Next Steps", + "tooltip": "Beyond the basics." + } + ] + }, { "title": "Tour of Heroes App", "tooltip": "The Tour of Heroes app is used as a reference point in many Angular examples.", @@ -143,37 +174,6 @@ } ] }, - { - "title": "Architecture", - "tooltip": "The basic building blocks of Angular applications.", - "children": [ - { - "url": "guide/architecture", - "title": "Architecture Overview", - "tooltip": "Basic building blocks of Angular applications." - }, - { - "url": "guide/architecture-modules", - "title": "Intro to Modules", - "tooltip": "About NgModules." - }, - { - "url": "guide/architecture-components", - "title": "Intro to Components", - "tooltip": "About Components, Templates, and Views." - }, - { - "url": "guide/architecture-services", - "title": "Intro to Services and DI", - "tooltip": "About services and dependency injection." - }, - { - "url": "guide/architecture-next-steps", - "title": "Next Steps", - "tooltip": "Beyond the basics." - } - ] - }, { "title": "Components & Templates", "tooltip": "Building dynamic views with data binding", @@ -297,11 +297,6 @@ } ] }, - { - "url": "guide/bootstrapping", - "title": "Bootstrapping", - "tooltip": "Tell Angular how to construct and bootstrap the app in the root \"AppModule\"." - }, { "title": "NgModules", "tooltip": "NgModules.", @@ -316,6 +311,11 @@ "title": "JS Modules vs NgModules", "tooltip": "Differentiate between JavaScript modules and NgModules." }, + { + "url": "guide/bootstrapping", + "title": "App Root NgModule", + "tooltip": "Tell Angular how to construct and bootstrap the app in the root \"AppModule\"." + }, { "url": "guide/frequent-ngmodules", "title": "Frequently Used NgModules",