docs: initial commit of content projection topic. (#41143)

Content projection is an important part of Angular. However, it has
never been documented in the Angular documentation set. This topic
attempts to provide the basics of content projection for developers. It
is not a comprehensive guide; rather, it is a starting point that we
can hopefully expand upon in the future.

PR Close #41143

Author: David Shevitz

.pullapprove.yml

@@ -335,6 +335,8 @@ groups:
           'aio/content/guide/component-styles.md',
           'aio/content/guide/view-encapsulation.md',
           'aio/content/examples/component-styles/**',
+          'aio/content/examples/content-projection/**',
+          'aio/content/guide/content-projection.md',
           'aio/content/guide/dependency-injection.md',
           'aio/content/examples/dependency-injection/**',
           'aio/content/images/guide/dependency-injection/**',

aio/content/examples/content-projection/e2e/src/app.e2e-spec.ts

@@ -0,0 +1,11 @@
+import { browser, element, by } from 'protractor';
+
+describe('Component Overview', () => {
+
+  beforeAll(() => browser.get(''));
+
+  it('should display Angular and Content Projection ', async () => {
+    expect(await element(by.css('h2')).getText()).toEqual('Angular and Content Projection');
+  });
+
+});

aio/content/examples/content-projection/example-config.json

@@ -0,0 +1,3 @@
+p {
+    font-family: Lato;
+  }

aio/content/examples/content-projection/src/app/app.component.css

@@ -0,0 +1,41 @@
+<h2>Angular and Content Projection</h2>
+
+<!-- #docregion single-slot -->
+<app-zippy-basic>
+  <p>Is content projection cool?</p>
+</app-zippy-basic>
+<!-- #enddocregion single-slot -->
+
+<hr />
+
+<!-- #docregion multi-slot -->
+<app-zippy-multislot>
+  <p question>
+    Is content projection cool?
+  </p>
+  <p>Let's learn about content projection!</p>
+</app-zippy-multislot>
+<!-- #enddocregion multi-slot -->
+
+<hr />
+
+<h2>Here's a zippy</h2>
+
+<app-example-zippy>
+  <button appExampleZippyToggle>Is content project cool?</button>
+  <!-- #docregion ng-template-->
+  <ng-template appExampleZippyContent>
+    It depends on what you do with it.
+  </ng-template>
+  <!-- #enddocregion ng-template -->
+</app-example-zippy>
+
+<hr />
+<app-zippy-ngprojectas>
+  <p>Let's learn about content projection!</p>
+  <!-- #docregion ngprojectas-->
+  <ng-container ngProjectAs="question">
+    <p>Is content projection cool?</p>
+  </ng-container>
+  <!-- #enddocregion-->
+</app-zippy-ngprojectas>

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

@@ -0,0 +1,42 @@
+import { Component, Directive, Input, TemplateRef, ContentChild, HostBinding, HostListener } from '@angular/core';
+
+@Component({
+  selector: 'app-root',
+  templateUrl: './app.component.html'
+})
+export class AppComponent {}
+
+@Directive({
+  selector: 'button[appExampleZippyToggle]',
+})
+export class ZippyToggleDirective {
+  @HostBinding('attr.aria-expanded') ariaExpanded = this.zippy.expanded;
+  @HostBinding('attr.aria-controls') ariaControls = this.zippy.contentId;
+  @HostListener('click') toggleZippy() {
+    this.zippy.expanded = !this.zippy.expanded;
+  }
+  constructor(public zippy: ZippyComponent) {}
+}
+
+// #docregion zippycontentdirective
+@Directive({
+  selector: '[appExampleZippyContent]'
+})
+export class ZippyContentDirective {
+  constructor(public templateRef: TemplateRef<unknown>) {}
+}
+// #enddocregion zippycontentdirective
+
+let nextId = 0;
+
+@Component({
+  selector: 'app-example-zippy',
+  templateUrl: 'example-zippy.template.html',
+})
+export class ZippyComponent {
+  contentId = `zippy-${nextId++}`;
+  @Input() expanded = false;
+  // #docregion contentchild
+  @ContentChild(ZippyContentDirective) content: ZippyContentDirective;
+  // #enddocregion contentchild
+}

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

@@ -0,0 +1,28 @@
+import { NgModule } from '@angular/core';
+import { BrowserModule } from '@angular/platform-browser';
+import { FormsModule } from '@angular/forms';
+
+import {
+  AppComponent,
+  ZippyComponent,
+  ZippyContentDirective,
+  ZippyToggleDirective,
+} from './app.component';
+import { ZippyBasicComponent } from './zippy-basic/zippy-basic.component';
+import { ZippyMultislotComponent } from './zippy-multislot/zippy-multislot.component';
+import { ZippyNgprojectasComponent } from './zippy-ngprojectas/zippy-ngprojectas.component';
+
+@NgModule({
+  imports: [BrowserModule, FormsModule],
+  declarations: [
+    AppComponent,
+    ZippyComponent,
+    ZippyToggleDirective,
+    ZippyContentDirective,
+    ZippyBasicComponent,
+    ZippyMultislotComponent,
+    ZippyNgprojectasComponent,
+  ],
+  bootstrap: [AppComponent]
+})
+export class AppModule {}

aio/content/examples/content-projection/src/app/app.module.ts

@@ -0,0 +1,8 @@
+<ng-content></ng-content>
+<!-- #docregion ngif -->
+<div *ngIf="expanded" [id]="contentId">
+    <!-- #docregion ng-container -->
+    <ng-container [ngTemplateOutlet]="content.templateRef"> </ng-container>
+    <!-- #enddocregion ng-container-->
+</div>
+<!-- #enddocregion ngif -->

aio/content/examples/content-projection/src/app/example-zippy.template.html

@@ -0,0 +1,10 @@
+import { Component } from '@angular/core';
+
+@Component({
+  selector: 'app-zippy-basic',
+  template: `
+  <h2>Single-slot content projection</h2>
+  <ng-content></ng-content>
+`
+})
+export class ZippyBasicComponent {}

aio/content/examples/content-projection/src/app/zippy-basic/zippy-basic.component.ts

@@ -0,0 +1,11 @@
+import { Component } from '@angular/core';
+
+@Component({
+  selector: 'app-zippy-multislot',
+  template: `
+  <h2>Multi-slot content projection</h2>
+  <ng-content></ng-content>
+  <ng-content select="[question]"></ng-content>
+`
+})
+export class ZippyMultislotComponent {}