Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs(learn): Revise Angular tutorial for v17 #32701

Merged
merged 7 commits into from
Mar 19, 2024
Merged

docs(learn): Revise Angular tutorial for v17 #32701

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
fde04dd
docs(learn): Revise Angular tutorial for v17
bsmth Mar 15, 2024
a2203fa
Apply suggestions from code review
bsmth Mar 16, 2024
7770ed2
Some more improvements
OnkarRuikar Mar 17, 2024
6f5192d
Merge branch 'main' into learn-angular-v17
bsmth Mar 18, 2024
05285a9
Apply suggestions from code review
bsmth Mar 19, 2024
7ff0d4f
Update files/en-us/learn/tools_and_testing/client-side_javascript_fra…
bsmth Mar 19, 2024
131a2fe
Update files/en-us/learn/tools_and_testing/client-side_javascript_fra…
bsmth Mar 19, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions ...n/tools_and_testing/client-side_javascript_frameworks/angular_building/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,17 @@ Because these files are static, you can host them on any web server capable of s

You can use any backend such as [Firebase](https://firebase.google.com/docs/hosting), [Google Cloud](https://cloud.google.com/solutions/web-hosting), or [App Engine](https://cloud.google.com/appengine/docs/standard/python/getting-started/hosting-a-static-website).

### Host locally

For fun, you can host the built app on your machine using [`http-server`](https://www.npmjs.com/package/http-server) package by running following command after running a build:

```bash
npx http-server ./dist/todo/browser/ -o
```

This command serves the `dist/todo/browser` directory on port `8080` so you can open `http://127.0.0.1:8080` in your browser to see the app running.
The HTTP server also lets you access the app at your computer's IP address from any other device on your local network, and this address is listed under the `127.0.0.1` address in the console.

## What's next

At this point, you've built a basic application, but your Angular journey is just beginning.
Expand Down
146 changes: 74 additions & 72 deletions ..._and_testing/client-side_javascript_frameworks/angular_getting_started/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,9 @@ page-type: learn-module-chapter

It is now time to look at Google's Angular framework, another popular option that you'll come across often. In this article we look at what Angular has to offer, install the prerequisites and set up a sample app, and look at Angular's basic architecture.

> **Note:**
> This tutorial targets [Angular version 17](https://angular.io/guide/update-to-version-17) and was last revised in March 2024 (`Angular CLI: 17.3.0`).

<table>
<tbody>
<tr>
Expand Down Expand Up @@ -35,52 +38,23 @@ It is now time to look at Google's Angular framework, another popular option tha

## What is Angular?

Angular is a development platform, built on [TypeScript](https://www.typescriptlang.org/). As a platform, Angular includes:
Angular is a framework and development platform, built on [TypeScript](https://www.typescriptlang.org/). It is used for creating single-page web applications. As a platform, Angular includes:

- A component-based framework for building scalable web applications
- A collection of well-integrated libraries that cover a wide variety of features, including routing, forms management, client-server communication, and more
- A suite of developer tools to help you develop, build, test, and update your code

When you build applications with Angular, you're taking advantage of a platform that can scale from single-developer projects to enterprise-level applications. Angular is designed to make updating as easy as possible, so you can take advantage of the latest developments with a minimum of effort. Best of all, the Angular ecosystem consists of a diverse group of over 1.7 million developers, library authors, and content creators.

Before you start exploring the Angular platform, you should know about the Angular CLI. The Angular CLI is the fastest, easiest, and recommended way to develop Angular applications. The Angular CLI makes a number of tasks easy. Here are some examples:
Before you start exploring the Angular platform, you should know about the Angular CLI. The Angular CLI is the fastest, easiest, and recommended way to develop Angular applications. The Angular CLI makes a number of tasks easy. Here are some example commands that you'll use frequently:

<table class="standard-table">
<tbody>
<tr>
<td>
<code><a href="https://angular.io/cli/build">ng build</a></code>
</td>
<td>Compiles an Angular app into an output directory.</td>
</tr>
<tr>
<td>
<code><a href="https://angular.io/cli/serve">ng serve</a></code>
</td>
<td>Builds and serves your application, rebuilding on file changes.</td>
</tr>
<tr>
<td>
<code><a href="https://angular.io/cli/generate">ng generate</a></code>
</td>
<td>Generates or modifies files based on a schematic.</td>
</tr>
<tr>
<td>
<code><a href="https://angular.io/cli/test">ng test</a></code>
</td>
<td>Runs unit tests on a given project.</td>
</tr>
<tr>
<td>
<code><a href="https://angular.io/cli/e2e">ng e2e</a></code>
</td>
<td>
Builds and serves an Angular application, then runs end-to-end tests.
</td>
</tr>
</tbody>
</table>
| Command | Description |
| ------------------------------------------------ | --------------------------------------------------------------------- |
| [`ng build`](https://angular.io/cli/build) | Compiles an Angular app into an output directory. |
| [`ng serve`](https://angular.io/cli/serve) | Builds and serves your application, rebuilding on file changes. |
| [`ng generate`](https://angular.io/cli/generate) | Generates or modifies files based on a schematic. |
| [`ng test`](https://angular.io/cli/test) | Runs unit tests on a given project. |
| [`ng e2e`](https://angular.io/cli/e2e) | Builds and serves an Angular application, then runs end-to-end tests. |

You'll find the Angular CLI to be a valuable tool for building out your applications.

Expand All @@ -94,9 +68,9 @@ To install Angular on your local system, you need the following:

- **Node.js**

Angular requires a [current, active LTS, or maintenance LTS](https://nodejs.org/en/about/previous-releases) version of Node.js. For information about specific version requirements, see the `engines` key in the [package.json](https://unpkg.com/@angular/cli/package.json) file.
Angular requires a [active LTS or maintenance LTS](https://nodejs.org/en/about/previous-releases) version of Node.js. For information about specific version requirements, see the [Version compatibility](https://angular.io/guide/versions) page.

For more information on installing Node.js, see [nodejs.org](https://nodejs.org).
For more information on installing Node.js, see [nodejs.org](https://nodejs.org/en/download).
If you are unsure what version of Node.js runs on your system, run `node -v` in a terminal window.

- **npm package manager**
Expand All @@ -106,69 +80,74 @@ To install Angular on your local system, you need the following:
This guide uses the [npm client](https://docs.npmjs.com/cli/install/) command line interface, which is installed with `Node.js` by default.
To check that you have the npm client installed, run `npm -v` in a terminal window.

## Set up your application
## Creating an Angular application

You can use the Angular CLI to run commands in your terminal for generating, building, testing, and deploying Angular applications.
To install the Angular CLI, run the following command in your terminal:
To install the Angular CLI globally, run the following command in your terminal:

```bash
npm install -g @angular/cli
```

Angular CLI commands all start with `ng`, followed by what you'd like the CLI to do.
In the Desktop directory, use the following `ng new` command to create a new application called `todo`:
Create a new directory where you want to build your app, and switch to the directory in the terminal. Then use the following [`ng new`](https://angular.io/cli/new) command to create a new application called `todo`:

```bash
ng new todo --routing=false --style=css
ng new todo --routing=false --style=css --ssr=false
```

The `ng new` command creates a minimal starter Angular application on your Desktop.
The additional flags, `--routing` and `--style`, define how to handle navigation and styles in the application.
The `ng new` command creates a minimal starter Angular application.
The additional flags, `--routing` and `--style`, and `--ssr` define how to handle navigation and styles in the application, and configures server-side rendering.
This tutorial describes these features later in more detail.

If you are prompted to enforce stricter type checking, you can respond with yes.
The first time you run `ng`, you may be asked if you want to enable terminal [autocompletion](https://angular.io/cli/completion) and analytics.
Autocompletion is convenient because pressing <kbd>TAB</kbd> while typing `ng` commands will show possible options and will autocomplete arguments.

Navigate into your new project with the following `cd` command:
You can also decide if you want to allow analytics about the CLI usage to be sent to Angular maintainers at Google.
To find out more about analytics, see the [Angular `ng analytics` CLI documentation](https://angular.io/cli/analytics).

```bash
cd todo
```

To run your `todo` application, use `ng serve`:
To run your `todo` application, navigate into your new project with the `cd` command and run `ng serve`:

```bash
cd todo
ng serve
```

When the CLI prompts you about analytics, answer `no`.

In the browser, navigate to `http://localhost:4200/` to see your new starter application.
If you change any of the source files, the application automatically reloads.

While `ng serve` is running, you might want to open a second terminal tab or window in order to run commands.
If at any point you would like to stop serving your application, press `Ctrl+c` while in the terminal.
While `ng serve` is running, open a second terminal tab or terminal window to run commands without stopping the server.
If at any point you would like to stop serving your application, press `Ctrl+c` in the terminal that's running the `ng serve` command.

## Get familiar with your Angular application

The application source files that this tutorial focuses on are in `src/app`.
Key files that the CLI generates automatically include the following:
The application source files that this tutorial focuses on are in `src/app`:

1. `app.module.ts`: Specifies the files that the application uses.
This file acts as a central hub for the other files in your application.
2. `app.component.ts`: Also known as the class, contains the logic for the application's main page.
3. `app.component.html`: Contains the HTML for `AppComponent`. The contents of this file are also known as the template.
```plain
src/app
├── app.component.css
├── app.component.html
├── app.component.spec.ts
├── app.component.ts
└── app.config.ts
```

Key files that the CLI generates automatically are the following:

1. `app.component.ts`: Also known as the class, contains the logic for the application's main page.
2. `app.component.html`: Contains the HTML for `AppComponent`. The contents of this file are also known as the template.
The template determines the view or what you see in the browser.
4. `app.component.css`: Contains the styles for `AppComponent`. You use this file when you want to define styles that only apply to a specific component, as opposed to your application overall.
3. `app.component.css`: Contains the styles for `AppComponent`. You use this file when you want to define styles that only apply to a specific component, as opposed to your application overall.

A component in Angular is made up of three main parts—the template, styles, and the class.
For example, `app.component.ts`, `app.component.html`, and `app.component.css` together constitute the `AppComponent`.
This structure separates the logic, view, and styles so that the application is more maintainable and scalable.

In this way, you are using the best practices from the very beginning.

The Angular CLI also generates a file for component testing called `app.component.spec.ts`, but this tutorial doesn't go into testing, so you can ignore that file.
Whenever you generate a component, the CLI creates these files in a directory with the name you specify and we'll see an example of that later.

Whenever you generate a component, the CLI creates these four files in a directory with the name you specify.
To learn more about testing, see the [Angular testing guide](https://angular.io/guide/testing).

## The structure of an Angular application

Expand Down Expand Up @@ -197,22 +176,23 @@ import { Component } from "@angular/core";

@Component({
selector: "app-item",
standalone: true,
// the following metadata specifies the location of the other parts of the component
templateUrl: "./item.component.html",
styleUrls: ["./item.component.css"],
})
export class ItemComponent {
// your code goes here
// code goes here
}
```

This component is called `ItemComponent`, and its selector is `app-item`.
You use a selector just like regular HTML tags by placing it within other templates.
You use a selector just like regular HTML tags by placing it within other templates, i.e. `<app-item></app-item>`.
When a selector is in a template, the browser renders the template of that component whenever an instance of the selector is encountered.
This tutorial guides you through creating two components and using one within the other.

**NOTE:** The name of the component above is `ItemComponent` which is also the name of the class. Why?
The names are the same simply because a component is nothing but a class supplemented by a TypeScript decorator.
> **Note:** The name of the component above is `ItemComponent` which is also the name of the class.
> The names are the same simply because a component is nothing but a class supplemented by a TypeScript decorator.

Angular's component model offers strong encapsulation and an intuitive application structure.
Components also make your application easier to unit test and can improve the overall readability of your code.
Expand All @@ -239,7 +219,7 @@ To write inline HTML, use the `template` property and write your HTML within bac
```js
@Component({
selector: "app-root",
template: `<h1>Hi!</h1>`,
template: `<h1>To do application</h1>`,
})
export class AppComponent {
// code goes here
Expand All @@ -262,7 +242,8 @@ import { Component } from "@angular/core";

@Component({
selector: "app-root",
templateUrl: "./app.component.html",
standalone: true,
template: "<h1>{{ title }}</h1>",
styleUrls: ["./app.component.css"],
})
export class AppComponent {
Expand Down Expand Up @@ -303,6 +284,27 @@ Typically, a component uses styles in a separate file using the `styleUrls` prop

With component-specific styles, you can organize your CSS so that it is easily maintainable and portable.

### Standalone components

It's recommended to [make components standalone](https://angular.io/guide/component-overview#creating-a-component-manually-1) unless a project already makes use of [NgModules](https://angular.io/guide/ngmodules) (Angular modules) to organize code.
This tutorial uses [standalone components](https://angular.io/guide/standalone-components) which are easier to start with.

It's common to import [`CommonModule`](https://angular.io/api/common/CommonModule) so that your component can make use of common [directives](https://angular.io/api/common#directives) and [pipes](https://angular.io/api/common#pipes).
This tutorial makes use of `ngFor` and `ngIf`, so we can make sure they're available like so:

```js
import { Component } from "@angular/core";
import { CommonModule } from '@angular/common';

@Component({
standalone: true,
selector: 'app-root',
templateUrl: './app.component.html',
styleUrls: ['./app.component.css'],
imports: [CommonModule],
})
```

## Summary

That's it for your first introduction to Angular. At this point you should be set up and ready to build an Angular app, and have a basic understanding of how Angular works. In the next article we'll deepen that knowledge and start to build up the structure of our to-do list application.
Expand Down
Loading
Loading