diff --git a/packages/core/src/application_ref.ts b/packages/core/src/application_ref.ts index 4ca238321c..a701f7518e 100644 --- a/packages/core/src/application_ref.ts +++ b/packages/core/src/application_ref.ts @@ -135,7 +135,7 @@ export class NgProbeToken { /** * Creates a platform. - * Platforms have to be eagerly created via this function. + * Platforms must be created on launch using this function. * * @publicApi */ @@ -153,7 +153,13 @@ export function createPlatform(injector: Injector): PlatformRef { } /** - * Creates a factory for a platform + * Creates a factory for a platform. Can be used to provide or override `Providers` specific to + * your applciation's runtime needs, such as `PLATFORM_INITIALIZER` and `PLATFORM_ID`. + * @param parentPlatformFactory Another platform factory to modify. Allows you to compose factories + * to build up configurations that might be required by different libraries or parts of the + * application. + * @param name Identifies the new platform factory. + * @param providers A set of dependency providers for platforms created with the new factory. * * @publicApi */ @@ -182,7 +188,7 @@ export function createPlatformFactory( } /** - * Checks that there currently is a platform which contains the given token as a provider. + * Checks that there is currently a platform that contains the given token as a provider. * * @publicApi */ @@ -202,7 +208,8 @@ export function assertPlatform(requiredToken: any): PlatformRef { } /** - * Destroy the existing platform. + * Destroys the current Angular platform and all Angular applications on the page. + * Destroys all modules and listeners registered with the platform. * * @publicApi */ @@ -259,12 +266,11 @@ export interface BootstrapOptions { } /** - * The Angular platform is the entry point for Angular on a web page. Each page - * has exactly one platform, and services (such as reflection) which are common + * The Angular platform is the entry point for Angular on a web page. + * Each page has exactly one platform. Services (such as reflection) which are common * to every Angular application running on the page are bound in its scope. - * - * A page's platform is initialized implicitly when a platform is created via a platform factory - * (e.g. {@link platformBrowser}), or explicitly by calling the {@link createPlatform} function. + * A page's platform is initialized implicitly when a platform is created using a platform + * factory such as `PlatformBrowser`, or explicitly by calling the `createPlatform()` function. * * @publicApi */ @@ -278,11 +284,11 @@ export class PlatformRef { constructor(private _injector: Injector) {} /** - * Creates an instance of an `@NgModule` for the given platform - * for offline compilation. + * Creates an instance of an `@NgModule` for the given platform for offline compilation. * * @usageNotes - * ### Simple Example + * + * The following example creates the NgModule for a browser platform. * * ```typescript * my_module.ts: @@ -384,14 +390,14 @@ export class PlatformRef { } /** - * Register a listener to be called when the platform is disposed. + * Registers a listener to be called when the platform is destroyed. */ onDestroy(callback: () => void): void { this._destroyListeners.push(callback); } /** - * Retrieve the platform {@link Injector}, which is the parent injector for + * Retrieves the platform {@link Injector}, which is the parent injector for * every Angular application on the page and provides singleton providers. */ get injector(): Injector { @@ -399,7 +405,8 @@ export class PlatformRef { } /** - * Destroy the Angular platform and all Angular applications on the page. + * Destroys the current Angular platform and all Angular applications on the page. + * Destroys all modules and listeners registered with the platform. */ destroy() { if (this._destroyed) { diff --git a/packages/platform-browser/src/browser.ts b/packages/platform-browser/src/browser.ts index 9fdae91883..65be438171 100644 --- a/packages/platform-browser/src/browser.ts +++ b/packages/platform-browser/src/browser.ts @@ -58,6 +58,9 @@ export const BROWSER_SANITIZATION_PROVIDERS__POST_R3__ = []; export const BROWSER_SANITIZATION_PROVIDERS = BROWSER_SANITIZATION_PROVIDERS__PRE_R3__; /** + * A factory function that returns a `PlatformRef` instance associated with browser service + * providers. + * * @publicApi */ export const platformBrowser: (extraProviders?: StaticProvider[]) => PlatformRef = diff --git a/packages/platform-browser/src/browser/meta.ts b/packages/platform-browser/src/browser/meta.ts index 7b33e66cb0..aa5a421b54 100644 --- a/packages/platform-browser/src/browser/meta.ts +++ b/packages/platform-browser/src/browser/meta.ts @@ -10,7 +10,11 @@ import {DOCUMENT, ɵDomAdapter as DomAdapter, ɵgetDOM as getDOM} from '@angular import {Inject, Injectable, ɵɵinject} from '@angular/core'; /** - * Represents a meta element. + * Represents the attributes of an HTML `` element. The element itself is + * represented by the internal `HTMLMetaElement`. + * + * @see [HTML meta tag](https://developer.mozilla.org/docs/Web/HTML/Element/meta) + * @see `Meta` * * @publicApi */ @@ -30,14 +34,31 @@ export type MetaDefinition = { }; /** - * Factory to create Meta service. + * Factory to create a `Meta` service instance for the current DOM document. */ export function createMeta() { return new Meta(ɵɵinject(DOCUMENT)); } /** - * A service that can be used to get and add meta tags. + * A service for managing HTML `` tags. + * + * Properties of the `MetaDefinition` object match the attributes of the + * HTML `` tag. These tags define document metadata that is important for + * things like configuring a Content Security Policy, defining browser compatibility + * and security settings, setting HTTP Headers, defining rich content for social sharing, + * and Search Engine Optimization (SEO). + * + * To identify specific `` tags in a document, use an attribute selection + * string in the format `"tag_attribute='value string'"`. + * For example, an `attrSelector` value of `"name='description'"` matches a tag + * whose `name` attribute has the value `"description"`. + * Selectors are used with the `querySelector()` Document method, + * in the format `meta[{attrSelector}]`. + * + * @see [HTML meta tag](https://developer.mozilla.org/docs/Web/HTML/Element/meta) + * @see [Document.querySelector()](https://developer.mozilla.org/docs/Web/API/Document/querySelector) + * * * @publicApi */ @@ -47,12 +68,29 @@ export class Meta { constructor(@Inject(DOCUMENT) private _doc: any) { this._dom = getDOM(); } - + /** + * Retrieves or creates a specific `` tag element in the current HTML document. + * In searching for an existing tag, Angular attempts to match the `name` or `property` attribute + * values in the provided tag definition, and verifies that all other attribute values are equal. + * If an existing element is found, it is returned and is not modified in any way. + * @param tag The definition of a `` element to match or create. + * @param forceCreation True to create a new element without checking whether one already exists. + * @returns The existing element with the same attributes and values if found, + * the new element if no match is found, or `null` if the tag parameter is not defined. + */ addTag(tag: MetaDefinition, forceCreation: boolean = false): HTMLMetaElement|null { if (!tag) return null; return this._getOrCreateElement(tag, forceCreation); } + /** + * Retrieves or creates a set of `` tag elements in the current HTML document. + * In searching for an existing tag, Angular attempts to match the `name` or `property` attribute + * values in the provided tag definition, and verifies that all other attribute values are equal. + * @param tags An array of tag definitions to match or create. + * @param forceCreation True to create new elements without checking whether they already exist. + * @returns The matching elements if found, or the new elements. + */ addTags(tags: MetaDefinition[], forceCreation: boolean = false): HTMLMetaElement[] { if (!tags) return []; return tags.reduce((result: HTMLMetaElement[], tag: MetaDefinition) => { @@ -63,17 +101,38 @@ export class Meta { }, []); } + /** + * Retrieves a `` tag element in the current HTML document. + * @param attrSelector The tag attribute and value to match against, in the format + * `"tag_attribute='value string'"`. + * @returns The matching element, if any. + */ getTag(attrSelector: string): HTMLMetaElement|null { if (!attrSelector) return null; return this._doc.querySelector(`meta[${attrSelector}]`) || null; } + /** + * Retrieves a set of `` tag elements in the current HTML document. + * @param attrSelector The tag attribute and value to match against, in the format + * `"tag_attribute='value string'"`. + * @returns The matching elements, if any. + */ getTags(attrSelector: string): HTMLMetaElement[] { if (!attrSelector) return []; const list /*NodeList*/ = this._doc.querySelectorAll(`meta[${attrSelector}]`); return list ? [].slice.call(list) : []; } + /** + * Modifies an existing `` tag element in the current HTML document. + * @param tag The tag description with which to replace the existing tag content. + * @param selector A tag attribute and value to match against, to identify + * an existing tag. A string in the format `"tag_attribute=`value string`"`. + * If not supplied, matches a tag with the same `name` or `property` attribute value as the + * replacement tag. + * @return The modified element. + */ updateTag(tag: MetaDefinition, selector?: string): HTMLMetaElement|null { if (!tag) return null; selector = selector || this._parseSelector(tag); @@ -84,10 +143,19 @@ export class Meta { return this._getOrCreateElement(tag, true); } + /** + * Removes an existing `` tag element from the current HTML document. + * @param attrSelector A tag attribute and value to match against, to identify + * an existing tag. A string in the format `"tag_attribute=`value string`"`. + */ removeTag(attrSelector: string): void { this.removeTagElement(this.getTag(attrSelector)!); } + /** + * Removes an existing `` tag element from the current HTML document. + * @param meta The tag definition to match against to identify an existing tag. + */ removeTagElement(meta: HTMLMetaElement): void { if (meta) { this._dom.remove(meta);