From 3d1a4d5cc3ab5ba8fe7c68789bff9a276a1c313a Mon Sep 17 00:00:00 2001 From: Judy Bogart Date: Fri, 30 Nov 2018 11:58:42 -0800 Subject: [PATCH] docs: add api doc for switch directives (#27378) PR Close #27378 --- packages/common/src/directives/ng_switch.ts | 128 +++++++++++++------- 1 file changed, 81 insertions(+), 47 deletions(-) diff --git a/packages/common/src/directives/ng_switch.ts b/packages/common/src/directives/ng_switch.ts index 68b392179b..83d20067d9 100644 --- a/packages/common/src/directives/ng_switch.ts +++ b/packages/common/src/directives/ng_switch.ts @@ -36,9 +36,53 @@ export class SwitchView { /** * @ngModule CommonModule * + * @description A structural directive that adds or removes templates (displaying or hiding views) + * when the next match expression matches the switch expression. + * + * The `[ngSwitch]` directive on a container specifies an expression to match against. + * The expressions to match are provided by `ngSwitchCase` directives on views within the container. + * - Every view that matches is rendered. + * - If there are no matches, a view with the `ngSwitchDefault` directive is rendered. + * - Elements within the `[NgSwitch]` statement but outside of any `NgSwitchCase` + * or `ngSwitchDefault` directive are preserved at the location. + * * @usageNotes + * Define a container element for the directive, and specify the switch expression + * to match against as an attribute: + * * ``` - * + * + * ``` + * + * Within the container, `*ngSwitchCase` statements specify the match expressions + * as attributes. Include `*ngSwitchDefault` as the final case. + * + * ``` + * + * ... + * ... + * ... + * + * ``` + * + * ### Usage Examples + * + * The following example shows how to use more than one case to display the same view: + * + * ``` + * + * + * ... + * ... + * ... + * + * ... + * + * ``` + * + * The following example shows how cases can be nested: + * ``` + * * ... * ... * ... @@ -50,28 +94,12 @@ export class SwitchView { * ... * * ``` - * @description - * - * Adds / removes DOM sub-trees when the nest match expressions matches the switch expression. - * - * `NgSwitch` stamps out nested views when their match expression value matches the value of the - * switch expression. - * - * In other words: - * - you define a container element (where you place the directive with a switch expression on the - * `[ngSwitch]="..."` attribute) - * - you define inner views inside the `NgSwitch` and place a `*ngSwitchCase` attribute on the view - * root elements. - * - * Elements within `NgSwitch` but outside of a `NgSwitchCase` or `NgSwitchDefault` directives will - * be preserved at the location. - * - * The `ngSwitchCase` directive informs the parent `NgSwitch` of which view to display when the - * expression is evaluated. - * When no matching expression is found on a `ngSwitchCase` view, the `ngSwitchDefault` view is - * stamped out. * * @publicApi + * @see `NgSwitchCase` + * @see `NgSwitchDefault` + * @see [Stuctural Directives](guide/structural-directives) + * */ @Directive({selector: '[ngSwitch]'}) export class NgSwitch { @@ -129,31 +157,42 @@ export class NgSwitch { /** * @ngModule CommonModule * + * @description + * Provides a switch case expression to match against an enclosing `ngSwitch` expression. + * When the expressions match, the given `NgSwitchCase` template is rendered. + * If multiple match expressions match the switch expression value, all of them are displayed. + * * @usageNotes + * + * Within a switch container, `*ngSwitchCase` statements specify the match expressions + * as attributes. Include `*ngSwitchDefault` as the final case. + * * ``` * * ... + * ... + * ... * - *``` - * @description + * ``` * - * Creates a view that will be added/removed from the parent {@link NgSwitch} when the - * given expression evaluate to respectively the same/different value as the switch - * expression. + * Each switch-case statement contains an in-line HTML template or template reference + * that defines the subtree to be selected if the value of the match expression + * matches the value of the switch expression. * - * Insert the sub-tree when the expression evaluates to the same value as the enclosing switch - * expression. - * - * If multiple match expressions match the switch expression value, all of them are displayed. - * - * See {@link NgSwitch} for more details and example. + * Unlike JavaScript, which uses strict equality, Angular uses loose equality. + * This means that the empty string, `""` matches 0. * * @publicApi + * @see `NgSwitch` + * @see `NgSwitchDefault` + * */ @Directive({selector: '[ngSwitchCase]'}) export class NgSwitchCase implements DoCheck { private _view: SwitchView; - + /** + * Stores the HTML template to be selected on match. + */ @Input() ngSwitchCase: any; @@ -164,30 +203,25 @@ export class NgSwitchCase implements DoCheck { this._view = new SwitchView(viewContainer, templateRef); } + /** + * Performs case matching. For internal use only. + */ ngDoCheck() { this._view.enforceState(this.ngSwitch._matchCase(this.ngSwitchCase)); } } /** * @ngModule CommonModule - * @usageNotes - * ``` - * - * ... - * ... - * - * ``` * * @description * - * Creates a view that is added to the parent {@link NgSwitch} when no case expressions - * match the switch expression. - * - * Insert the sub-tree when no case expressions evaluate to the same value as the enclosing switch - * expression. - * - * See {@link NgSwitch} for more details and example. + * Creates a view that is rendered when no `NgSwitchCase` expressions + * match the `NgSwitch` expression. + * This statement should be the final case in an `NgSwitch`. * * @publicApi + * @see `NgSwitch` + * @see `NgSwitchCase` + * */ @Directive({selector: '[ngSwitchDefault]'}) export class NgSwitchDefault {