refactor(portal): rename PortalHost to PortalOutlet (#7546)

Renames the `PortalHost` and related symbols to `PortalOutlet` for consistency with core.

Fixes #7544.

Author: crisbeto

src/cdk/overlay/overlay-ref.ts

@@ -7,7 +7,7 @@
  */
 
 import {NgZone} from '@angular/core';
-import {PortalHost, Portal} from '@angular/cdk/portal';
+import {PortalOutlet, Portal} from '@angular/cdk/portal';
 import {OverlayConfig} from './overlay-config';
 import {OverlayKeyboardDispatcher} from './keyboard/overlay-keyboard-dispatcher';
 import {Observable} from 'rxjs/Observable';
@@ -19,7 +19,7 @@ import {first} from 'rxjs/operators';
  * Reference to an overlay that has been created with the Overlay service.
  * Used to manipulate or dispose of said overlay.
  */
-export class OverlayRef implements PortalHost {
+export class OverlayRef implements PortalOutlet {
   private _backdropElement: HTMLElement | null = null;
   private _backdropClick: Subject<any> = new Subject();
   private _attachments = new Subject<void>();
@@ -29,7 +29,7 @@ export class OverlayRef implements PortalHost {
   _keydownEvents = new Subject<KeyboardEvent>();
 
   constructor(
-      private _portalHost: PortalHost,
+      private _portalOutlet: PortalOutlet,
       private _pane: HTMLElement,
       private _config: OverlayConfig,
       private _ngZone: NgZone,
@@ -51,7 +51,7 @@ export class OverlayRef implements PortalHost {
    * @returns The portal attachment result.
    */
   attach(portal: Portal<any>): any {
-    let attachResult = this._portalHost.attach(portal);
+    let attachResult = this._portalOutlet.attach(portal);
 
     if (this._config.positionStrategy) {
       this._config.positionStrategy.attach(this);
@@ -118,7 +118,7 @@ export class OverlayRef implements PortalHost {
       this._config.scrollStrategy.disable();
     }
 
-    const detachmentResult = this._portalHost.detach();
+    const detachmentResult = this._portalOutlet.detach();
 
     // Only emit after everything is detached.
     this._detachments.next();
@@ -142,7 +142,7 @@ export class OverlayRef implements PortalHost {
     }
 
     this.detachBackdrop();
-    this._portalHost.dispose();
+    this._portalOutlet.dispose();
     this._attachments.complete();
     this._backdropClick.complete();
     this._detachments.next();
@@ -153,7 +153,7 @@ export class OverlayRef implements PortalHost {
    * Checks whether the overlay has been attached.
    */
   hasAttached(): boolean {
-    return this._portalHost.hasAttached();
+    return this._portalOutlet.hasAttached();
   }
 
   /**

src/cdk/overlay/overlay.md

@@ -4,7 +4,7 @@ The `overlay` package provides a way to open floating panels on the screen.
 Calling `overlay.create()` will return an `OverlayRef` instance. This instance is a handle for
 managing that specific overlay.
 
-The `OverlayRef` _is_ a `PortalHost`- once created, content can be added by attaching a `Portal`.
+The `OverlayRef` _is_ a `PortalOutlet`- once created, content can be added by attaching a `Portal`.
 See the documentation on portals for further information.
 ```ts
 const overlayRef = overlay.create();

src/cdk/overlay/overlay.ts

@@ -13,7 +13,7 @@ import {
   Injector,
   NgZone,
 } from '@angular/core';
-import {DomPortalHost} from '@angular/cdk/portal';
+import {DomPortalOutlet} from '@angular/cdk/portal';
 import {OverlayConfig} from './overlay-config';
 import {OverlayRef} from './overlay-ref';
 import {OverlayPositionBuilder} from './position/overlay-position-builder';
@@ -35,7 +35,7 @@ let defaultConfig = new OverlayConfig();
  * selects, etc. can all be built using overlays. The service should primarily be used by authors
  * of re-usable components rather than developers building end-user applications.
  *
- * An overlay *is* a PortalHost, so any kind of Portal can be loaded into one.
+ * An overlay *is* a PortalOutlet, so any kind of Portal can be loaded into one.
  */
 @Injectable()
 export class Overlay {
@@ -57,8 +57,8 @@ export class Overlay {
    */
   create(config: OverlayConfig = defaultConfig): OverlayRef {
     const pane = this._createPaneElement();
-    const portalHost = this._createPortalHost(pane);
-    return new OverlayRef(portalHost, pane, config, this._ngZone, this._keyboardDispatcher);
+    const portalOutlet = this._createPortalOutlet(pane);
+    return new OverlayRef(portalOutlet, pane, config, this._ngZone, this._keyboardDispatcher);
   }
 
   /**
@@ -85,12 +85,12 @@ export class Overlay {
   }
 
   /**
-   * Create a DomPortalHost into which the overlay content can be loaded.
-   * @param pane The DOM element to turn into a portal host.
-   * @returns A portal host for the given DOM element.
+   * Create a DomPortalOutlet into which the overlay content can be loaded.
+   * @param pane The DOM element to turn into a portal outlet.
+   * @returns A portal outlet for the given DOM element.
    */
-  private _createPortalHost(pane: HTMLElement): DomPortalHost {
-    return new DomPortalHost(pane, this._componentFactoryResolver, this._appRef, this._injector);
+  private _createPortalOutlet(pane: HTMLElement): DomPortalOutlet {
+    return new DomPortalOutlet(pane, this._componentFactoryResolver, this._appRef, this._injector);
   }
 
 }

src/cdk/portal/dom-portal-host.ts renamed to src/cdk/portal/dom-portal-outlet.ts

@@ -13,14 +13,14 @@ import {
   ApplicationRef,
   Injector,
 } from '@angular/core';
-import {BasePortalHost, ComponentPortal, TemplatePortal} from './portal';
+import {BasePortalOutlet, ComponentPortal, TemplatePortal} from './portal';
 
 
 /**
- * A PortalHost for attaching portals to an arbitrary DOM element outside of the Angular
+ * A PortalOutlet for attaching portals to an arbitrary DOM element outside of the Angular
  * application context.
  */
-export class DomPortalHost extends BasePortalHost {
+export class DomPortalOutlet extends BasePortalOutlet {
   constructor(
       private _hostDomElement: Element,
       private _componentFactoryResolver: ComponentFactoryResolver,
@@ -75,8 +75,9 @@ export class DomPortalHost extends BasePortalHost {
     viewRef.detectChanges();
 
     // The method `createEmbeddedView` will add the view as a child of the viewContainer.
-    // But for the DomPortalHost the view can be added everywhere in the DOM (e.g Overlay Container)
-    // To move the view to the specified host element. We just re-append the existing root nodes.
+    // But for the DomPortalOutlet the view can be added everywhere in the DOM
+    // (e.g Overlay Container) To move the view to the specified host element. We just
+    // re-append the existing root nodes.
     viewRef.rootNodes.forEach(rootNode => this._hostDomElement.appendChild(rootNode));
 
     this.setDisposeFn((() => {

src/cdk/portal/portal-directives.ts

@@ -17,7 +17,7 @@ import {
     OnDestroy,
     Input,
 } from '@angular/core';
-import {Portal, TemplatePortal, ComponentPortal, BasePortalHost} from './portal';
+import {Portal, TemplatePortal, ComponentPortal, BasePortalOutlet} from './portal';
 
 
 /**
@@ -36,18 +36,18 @@ export class TemplatePortalDirective extends TemplatePortal<any> {
 
 
 /**
- * Directive version of a PortalHost. Because the directive *is* a PortalHost, portals can be
+ * Directive version of a PortalOutlet. Because the directive *is* a PortalOutlet, portals can be
  * directly attached to it, enabling declarative use.
  *
  * Usage:
- * <ng-template [cdkPortalHost]="greeting"></ng-template>
+ * <ng-template [cdkPortalOutlet]="greeting"></ng-template>
  */
 @Directive({
-  selector: '[cdkPortalHost], [portalHost]',
-  exportAs: 'cdkPortalHost',
-  inputs: ['portal: cdkPortalHost']
+  selector: '[cdkPortalOutlet], [cdkPortalHost], [portalHost]',
+  exportAs: 'cdkPortalOutlet, cdkPortalHost',
+  inputs: ['portal: cdkPortalOutlet']
 })
-export class PortalHostDirective extends BasePortalHost implements OnDestroy {
+export class PortalOutletDirective extends BasePortalOutlet implements OnDestroy {
   /** The attached portal. */
   private _portal: Portal<any> | null = null;
 
@@ -62,7 +62,12 @@ export class PortalHostDirective extends BasePortalHost implements OnDestroy {
   get _deprecatedPortal() { return this.portal; }
   set _deprecatedPortal(v) { this.portal = v; }
 
-  /** Portal associated with the Portal host. */
+  /** @deprecated */
+  @Input('cdkPortalHost')
+  get _deprecatedPortalHost() { return this.portal; }
+  set _deprecatedPortalHost(v) { this.portal = v; }
+
+  /** Portal associated with the Portal outlet. */
   get portal(): Portal<any> | null {
     return this._portal;
   }
@@ -85,16 +90,16 @@ export class PortalHostDirective extends BasePortalHost implements OnDestroy {
   }
 
   /**
-   * Attach the given ComponentPortal to this PortalHost using the ComponentFactoryResolver.
+   * Attach the given ComponentPortal to this PortalOutlet using the ComponentFactoryResolver.
    *
-   * @param portal Portal to be attached to the portal host.
+   * @param portal Portal to be attached to the portal outlet.
    * @returns Reference to the created component.
    */
   attachComponentPortal<T>(portal: ComponentPortal<T>): ComponentRef<T> {
     portal.setAttachedHost(this);
 
     // If the portal specifies an origin, use that as the logical location of the component
-    // in the application tree. Otherwise use the location of this PortalHost.
+    // in the application tree. Otherwise use the location of this PortalOutlet.
     let viewContainerRef = portal.viewContainerRef != null ?
         portal.viewContainerRef :
         this._viewContainerRef;
@@ -129,7 +134,7 @@ export class PortalHostDirective extends BasePortalHost implements OnDestroy {
 
 
 @NgModule({
-  exports: [TemplatePortalDirective, PortalHostDirective],
-  declarations: [TemplatePortalDirective, PortalHostDirective],
+  exports: [TemplatePortalDirective, PortalOutletDirective],
+  declarations: [TemplatePortalDirective, PortalOutletDirective],
 })
 export class PortalModule {}

src/cdk/portal/portal-errors.ts

@@ -26,25 +26,25 @@ export function throwPortalAlreadyAttachedError() {
  * Throws an exception when attempting to attach a portal to an already-disposed host.
  * @docs-private
  */
-export function throwPortalHostAlreadyDisposedError() {
-  throw Error('This PortalHost has already been disposed');
+export function throwPortalOutletAlreadyDisposedError() {
+  throw Error('This PortalOutlet has already been disposed');
 }
 
 /**
  * Throws an exception when attempting to attach an unknown portal type.
  * @docs-private
  */
 export function throwUnknownPortalTypeError() {
-  throw Error('Attempting to attach an unknown Portal type. BasePortalHost accepts either ' +
-                  'a ComponentPortal or a TemplatePortal.');
+  throw Error('Attempting to attach an unknown Portal type. BasePortalOutlet accepts either ' +
+              'a ComponentPortal or a TemplatePortal.');
 }
 
 /**
  * Throws an exception when attempting to attach a portal to a null host.
  * @docs-private
  */
-export function throwNullPortalHostError() {
-  throw Error('Attempting to attach a portal to a null PortalHost');
+export function throwNullPortalOutletError() {
+  throw Error('Attempting to attach a portal to a null PortalOutlet');
 }
 
 /**

src/cdk/portal/portal.md

@@ -3,20 +3,20 @@ The `portals` package provides a flexible system for rendering dynamic content i
 ### Portals
 A `Portal `is a piece of UI that can be dynamically rendered to an open slot on the page.
 
-The "piece of UI" can be either a `Component` or a `TemplateRef` and the "open slot" is 
-a `PortalHost`.
+The "piece of UI" can be either a `Component` or a `TemplateRef` and the "open slot" is
+a `PortalOutlet`.
 
-Portals and PortalHosts are low-level building blocks that other concepts, such as overlays, are
+Portals and PortalOutlets are low-level building blocks that other concepts, such as overlays, are
 built upon.
 
 ##### `Portal<T>`
 | Method | Description |
 | --- | --- |
-| `attach(PortalHost): Promise<T>` | Attaches the portal to a host. |
+| `attach(PortalOutlet): Promise<T>` | Attaches the portal to a host. |
 | `detach(): Promise<void>` | Detaches the portal from its host. |
 | `isAttached: boolean` | Whether the portal is attached. |
 
-##### `PortalHost`
+##### `PortalOutlet`
 | Method | Description |
 | --- | --- |
 | `attach(Portal): Promise<void>` | Attaches a portal to the host. |
@@ -57,11 +57,11 @@ this.userSettingsPortal = new ComponentPortal(UserSettingsComponent);
 ```
 
 
-##### `PortalHostDirective`
-Used to add a portal host to a template. `PortalHostDirective` *is* a `PortalHost`.
+##### `PortalOutletDirective`
+Used to add a portal outlet to a template. `PortalOutletDirective` *is* a `PortalOutlet`.
 
 Usage:
 ```html
 <!-- Attaches the `userSettingsPortal` from the previous example. -->
-<ng-template [cdkPortalHost]="userSettingsPortal"></ng-template>
+<ng-template [cdkPortalOutlet]="userSettingsPortal"></ng-template>
 ```