docs: Add Component Overview topic to angular.io (#39186)

PR Close #39186

.pullapprove.yml

@@ -324,6 +324,8 @@ groups:
           'aio/content/guide/component-interaction.md',
           'aio/content/examples/component-interaction/**',
           'aio/content/images/guide/component-interaction/**',
+          'aio/content/guide/component-overview.md',
+          'aio/content/examples/component-overview/**',
           'aio/content/guide/component-styles.md',
           'aio/content/guide/view-encapsulation.md',
           'aio/content/examples/component-styles/**',

aio/content/examples/component-overview/e2e/src/app.e2e-spec.ts

@@ -0,0 +1,13 @@
+import { browser, element, by } from 'protractor';
+
+describe('Component Overview', () => {
+
+  beforeAll(() => {
+    browser.get('');
+  });
+
+  it('should display component overview works ', () => {
+    expect(element(by.css('p')).getText()).toEqual('component-overview works!');
+  });
+
+});

aio/content/examples/component-overview/src/app/app.component.html

@@ -0,0 +1 @@
+<app-component-overview></app-component-overview>

aio/content/examples/component-overview/src/app/app.component.spec.ts

@@ -0,0 +1,31 @@
+import { TestBed, async } from '@angular/core/testing';
+import { AppComponent } from './app.component';
+
+describe('AppComponent', () => {
+  beforeEach(async(() => {
+    TestBed.configureTestingModule({
+      declarations: [
+        AppComponent
+      ],
+    }).compileComponents();
+  }));
+
+  it('should create the app', () => {
+    const fixture = TestBed.createComponent(AppComponent);
+    const app = fixture.componentInstance;
+    expect(app).toBeTruthy();
+  });
+
+  it(`should have as title 'component-overview'`, () => {
+    const fixture = TestBed.createComponent(AppComponent);
+    const app = fixture.componentInstance;
+    expect(app.title).toEqual('component-overview');
+  });
+
+  it('should render title', () => {
+    const fixture = TestBed.createComponent(AppComponent);
+    fixture.detectChanges();
+    const compiled = fixture.nativeElement;
+    expect(compiled.querySelector('.content span').textContent).toContain('component-overview app is running!');
+  });
+});

aio/content/examples/component-overview/src/app/app.component.ts

@@ -0,0 +1,10 @@
+import { Component } from '@angular/core';
+
+@Component({
+  selector: 'app-root',
+  templateUrl: './app.component.html',
+  styleUrls: ['./app.component.css']
+})
+export class AppComponent {
+  title = 'component-overview';
+}

aio/content/examples/component-overview/src/app/app.module.ts

@@ -0,0 +1,18 @@
+import { BrowserModule } from '@angular/platform-browser';
+import { NgModule } from '@angular/core';
+
+import { AppComponent } from './app.component';
+import { ComponentOverviewComponent } from './component-overview/component-overview.component';
+
+@NgModule({
+  declarations: [
+    AppComponent,
+    ComponentOverviewComponent
+  ],
+  imports: [
+    BrowserModule
+  ],
+  providers: [],
+  bootstrap: [AppComponent]
+})
+export class AppModule { }

aio/content/examples/component-overview/src/app/component-overview/component-overview.component.1.ts

@@ -0,0 +1,14 @@
+// #docplaster
+import { Component } from '@angular/core';
+
+// #docregion template
+@Component({
+  selector: 'app-component-overview',
+  template: '<h1>Hello World!</h1>',
+})
+// #enddocregion template
+
+export class ComponentOverviewComponent {
+
+}
+

aio/content/examples/component-overview/src/app/component-overview/component-overview.component.2.ts

@@ -0,0 +1,16 @@
+// #docplaster
+import { Component } from '@angular/core';
+
+// #docregion templatebacktick
+@Component({
+  selector: 'app-component-overview',
+  template: `<h1>Hello World!</h1>
+             <p>This template definition spans
+              multiple lines.</p>`
+})
+// #enddocregion templatebacktick
+
+export class ComponentOverviewComponent {
+
+}
+

aio/content/examples/component-overview/src/app/component-overview/component-overview.component.3.ts

@@ -0,0 +1,15 @@
+// #docplaster
+import { Component } from '@angular/core';
+
+// #docregion styles
+@Component({
+  selector: 'app-component-overview',
+  template: '<h1>Hello World!</h1>',
+  styles: ['h1 { font-weight: normal; }']
+})
+// #enddocregion styles
+
+export class ComponentOverviewComponent {
+
+}
+

aio/content/examples/component-overview/src/app/component-overview/component-overview.component.html

@@ -0,0 +1 @@
+<p>component-overview works!</p>

aio/content/examples/component-overview/src/app/component-overview/component-overview.component.spec.ts

@@ -0,0 +1,25 @@
+import { async, ComponentFixture, TestBed } from '@angular/core/testing';
+
+import { ComponentOverviewComponent } from './component-overview.component';
+
+describe('ComponentOverviewComponent', () => {
+  let component: ComponentOverviewComponent;
+  let fixture: ComponentFixture<ComponentOverviewComponent>;
+
+  beforeEach(async(() => {
+    TestBed.configureTestingModule({
+      declarations: [ ComponentOverviewComponent ]
+    })
+    .compileComponents();
+  }));
+
+  beforeEach(() => {
+    fixture = TestBed.createComponent(ComponentOverviewComponent);
+    component = fixture.componentInstance;
+    fixture.detectChanges();
+  });
+
+  it('should create', () => {
+    expect(component).toBeTruthy();
+  });
+});

aio/content/examples/component-overview/src/app/component-overview/component-overview.component.ts

@@ -0,0 +1,22 @@
+// #docplaster
+// #docregion import
+import { Component } from '@angular/core';
+// #enddocregion import
+
+// #docregion decorator, decorator-skeleton, selector, templateUrl
+@Component({
+// #enddocregion decorator-skeleton
+  selector: 'app-component-overview',
+// #enddocregion selector
+  templateUrl: './component-overview.component.html',
+// #enddocregion templateUrl
+  styleUrls: ['./component-overview.component.css']
+// #docregion decorator-skeleton, selector, templateUrl
+})
+// #enddocregion decorator, decorator-skeleton, selector, templateUrl
+
+// #docregion class
+export class ComponentOverviewComponent {
+
+}
+// #enddocregion class

aio/content/examples/component-overview/src/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>ComponentOverview</title>
+  <base href="/">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <link rel="icon" type="image/x-icon" href="favicon.ico">
+</head>
+<body>
+  <app-root></app-root>
+</body>
+</html>

aio/content/examples/component-overview/src/main.ts

@@ -0,0 +1,12 @@
+import { enableProdMode } from '@angular/core';
+import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
+
+import { AppModule } from './app/app.module';
+import { environment } from './environments/environment';
+
+if (environment.production) {
+  enableProdMode();
+}
+
+platformBrowserDynamic().bootstrapModule(AppModule)
+  .catch(err => console.error(err));

aio/content/examples/component-overview/stackblitz.json

@@ -0,0 +1,8 @@
+{
+  "description": "Component Overview",
+  "files":[
+    "!**/*.d.ts",
+    "!**/*.js"
+  ],
+  "tags":["overview", "component"]
+}

aio/content/guide/component-overview.md

@@ -0,0 +1,182 @@
+# Angular Components Overview
+
+Components are the main building block for Angular applications. Each component consists of:
+
+* An HTML template that declares what renders on the page
+* A Typescript class that defines behavior
+* A CSS selector that defines how the component is used in a template
+* Optionally, CSS styles applied to the template
+
+This topic describes how to create and configure an Angular component.
+
+<div class="alert is-helpful">
+
+To view or download the example code used in this topic, see the <live-example></live-example>.
+
+</div>
+
+## Prerequisites
+
+To create a component, verify that you have met the following prerequisites:
+
+1. Install the Angular CLI.
+1. Create an Angular project.
+   If you don't have a project, you can create one using `ng new <project-name>`, where `<project-name>` is the name of your Angular application.
+
+## Creating a component
+
+The easiest way to create a component is with the Angular CLI. You can also create a component manually.
+
+### Creating a component using the Angular CLI
+
+To create a component using the Angular CLI:
+
+1. From a terminal window, navigate to the directory containing your application.
+1. Run the `ng generate component <component-name>` command, where `<component-name>` is the name of your new component.
+
+By default, this command creates the following:
+
+* A folder named after the component
+* A component file, `<component-name>.component.ts`
+* A template file, `<component-name>.component.ts`
+* A CSS file, `<component-name>.component.css`
+* A testing specification file, `<component-name>.component.spec.ts`
+
+Where `<component-name>` is the name of your component.
+
+<div class="alert is-helpful">
+
+You can change how `ng generate component` creates new components.
+For more information, see [ng generate component](cli/generate#component-command) in the Angular CLI documentation.
+
+</div>
+
+### Creating a component manually
+
+Although the Angular CLI is the easiest way to create an Angular component, you can also create a component manually.
+This section describes how to create the core component file within an existing Angular project.
+
+To create a new component manually:
+
+1. Navigate to your Angular project directory.
+1. Create a new file, `<component-name>.component.ts`.
+1. At the top of the file, add the following import statement.
+
+   <code-example
+        path="component-overview/src/app/component-overview/component-overview.component.ts"
+        region="import">
+   </code-example>
+
+1. After the `import` statement, add a `@Component` decorator.
+
+   <code-example
+        path="component-overview/src/app/component-overview/component-overview.component.ts"
+        region="decorator-skeleton">
+   </code-example>
+
+1. Choose a CSS selector for the component.
+
+   <code-example
+        path="component-overview/src/app/component-overview/component-overview.component.ts"
+        region="selector">
+   </code-example>
+
+   For more information on choosing a selector, see [Specifying a component's selector](#specifying-a-components-css-selector).
+
+1. Define the HTML template that the component uses to display information.
+   In most cases, this template is a separate HTML file.
+
+   <code-example
+        path="component-overview/src/app/component-overview/component-overview.component.ts"
+        region="templateUrl">
+   </code-example>
+
+   For more information on defining a component's template, see [Defining a component's template](#defining-a-components-template).
+
+1. Select the styles for the component's template.
+   In most cases, you define the styles for you component's template in a separate file.
+
+   <code-example
+        path="component-overview/src/app/component-overview/component-overview.component.ts"
+        region="decorator">
+   </code-example>
+
+1. Add a `class` statement that includes the code for the component.
+
+   <code-example
+        path="component-overview/src/app/component-overview/component-overview.component.ts"
+        region="class">
+   </code-example>
+
+## Specifying a component's CSS selector
+
+Every component requires a CSS _selector_. A selector instructs Angular to instantiate this component wherever it finds the corresponding tag in template HTML. For example, consider a component, `hello-world.component.ts` that defines its selector as `app-hello-world`. This selector instructs angular to instantiate this component any time the tag, `<app-hellow-world>` in a template.
+
+To specify a component's selector, add a `selector` statement to the `@Component` decorator.
+
+<code-example
+    path="component-overview/src/app/component-overview/component-overview.component.ts"
+    region="selector">
+</code-example>
+
+## Defining a component's template
+
+A template is a block of HTML that tells Angular how to render the component in your application.
+You can define a template for your component in one of two ways: by referencing an external file, or directly within the component.
+
+To define a template as an external file, add a `templateUrl` property to the `@Component` decorator.
+
+<code-example
+    path="component-overview/src/app/component-overview/component-overview.component.ts"
+    region="templateUrl">
+</code-example>
+
+To define a template within the component, add a `template` property to the `@Component` decorator that contains the HTML you want to use.
+
+<code-example
+    path="component-overview/src/app/component-overview/component-overview.component.1.ts"
+    region="template">
+</code-example>
+
+If your want your template to span multiple lines, you can use backticks (<code> ` </code>).
+For example:
+
+<code-example
+    path="component-overview/src/app/component-overview/component-overview.component.2.ts"
+    region="templatebacktick">
+</code-example>
+
+<div class="alert is-helpful">
+
+An Angular component requires a template defined using `template` or `templateUrl`. You cannot have both statements in a component.
+
+</div>
+
+## Declaring a component's styles
+
+You can declare component styles uses for its template in one of two ways: by referencing an external file, or directly within the component.
+
+To declare the styles for a component in a separate file, add a `stylesUrls` property to the `@Component` decorator.
+
+<code-example
+    path="component-overview/src/app/component-overview/component-overview.component.ts"
+    region="decorator">
+</code-example>
+
+To select the styles within the component, add a `styles` property to the `@Component` decorator that contains the styles you want to use.
+
+<code-example
+    path="component-overview/src/app/component-overview/component-overview.component.3.ts"
+    region="styles">
+</code-example>
+
+The `styles` property takes an array of strings that contain the CSS rule declarations.
+
+
+## Next steps
+
+* For an archictural overview of components, see [Introduction to components and templates](guide/architecture-components).
+* For additional options you can use when creating a component, see [Component](api/core/Component) in the API Reference.
+* For more information on styling components, see [Component styles](guide/component-styles).
+* For more information on templates, see [Template syntax](guide/template-syntax).
+

aio/content/navigation.json

@@ -101,6 +101,11 @@
           "title": "Components",
           "tooltip": "Building dynamic views with data binding",
           "children": [
+            {
+              "url": "guide/component-overview",
+              "title": "Overview",
+              "tooltip": "Overview of how to create Angular components."
+            },
             {
               "url": "guide/user-input",
               "title": "User Input",