From c529be9f2427d7bd1b0fded23dca58019634f8cd Mon Sep 17 00:00:00 2001 From: Kapunahele Wong Date: Tue, 9 Jul 2019 12:30:55 -0400 Subject: [PATCH] docs: add microsyntax details (#31517) PR Close #31517 --- aio/content/guide/structural-directives.md | 152 +++++++++++++++++++-- 1 file changed, 139 insertions(+), 13 deletions(-) diff --git a/aio/content/guide/structural-directives.md b/aio/content/guide/structural-directives.md index 77ee244e19..7bba38a380 100644 --- a/aio/content/guide/structural-directives.md +++ b/aio/content/guide/structural-directives.md @@ -275,53 +275,179 @@ In this example, the `[ngClass]="odd"` stays on the `
`. {@a microsyntax} -### Microsyntax +## Microsyntax The Angular microsyntax lets you configure a directive in a compact, friendly string. The microsyntax parser translates that string into attributes on the ``: * The `let` keyword declares a [_template input variable_](guide/structural-directives#template-input-variable) that you reference within the template. The input variables in this example are `hero`, `i`, and `odd`. -The parser translates `let hero`, `let i`, and `let odd` into variables named, +The parser translates `let hero`, `let i`, and `let odd` into variables named `let-hero`, `let-i`, and `let-odd`. -* The microsyntax parser takes `of` and `trackBy`, title-cases them (`of` -> `Of`, `trackBy` -> `TrackBy`), -and prefixes them with the directive's attribute name (`ngFor`), yielding the names `ngForOf` and `ngForTrackBy`. -Those are the names of two `NgFor` _input properties_ . +* The microsyntax parser title-cases all directives and prefixes them with the directive's +attribute name, such as `ngFor`. For example, the `ngFor` input properties, +`of` and `trackBy`, become `ngForOf` and `ngForTrackBy`, respectively. That's how the directive learns that the list is `heroes` and the track-by function is `trackById`. * As the `NgFor` directive loops through the list, it sets and resets properties of its own _context_ object. -These properties include `index` and `odd` and a special property named `$implicit`. +These properties can include, but aren't limited to, `index`, `odd`, and a special property +named `$implicit`. * The `let-i` and `let-odd` variables were defined as `let i=index` and `let odd=odd`. Angular sets them to the current value of the context's `index` and `odd` properties. * The context property for `let-hero` wasn't specified. Its intended source is implicit. -Angular sets `let-hero` to the value of the context's `$implicit` property +Angular sets `let-hero` to the value of the context's `$implicit` property, which `NgFor` has initialized with the hero for the current iteration. -* The [API guide](api/common/NgForOf "API: NgFor") +* The [`NgFor` API guide](api/common/NgForOf "API: NgFor") describes additional `NgFor` directive properties and context properties. -* `NgFor` is implemented by the `NgForOf` directive. Read more about additional `NgForOf` directive properties and context properties [NgForOf API reference](api/common/NgForOf). +* The `NgForOf` directive implements `NgFor`. Read more about additional `NgForOf` directive properties and context properties in the [NgForOf API reference](api/common/NgForOf). + +### Writing your own structural directives + +These microsyntax mechanisms are also available to you when you write your own structural directives. +For example, microsyntax in Angular allows you to write `
{{item}}
` +instead of `
{{item}}
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
prefixHTML attribute key
keyHTML attribute key
locallocal variable name used in the template
exportvalue exported by the directive under a given name
expressionstandard Angular expression
+ + + + + + + + + + + + + + + +
keyExp = :key ":"? :expression ("as" :local)? ";"?
let = "let" :local "=" :export ";"?
as = :export "as" :local ";"?
-These microsyntax mechanisms are available to you when you write your own structural directives. +### Translation + +A microsyntax is translated to the normal binding syntax as follows: + + + + + + + + + + + + + + + + + + + +
MicrosyntaxTranslation
prefix and naked expression[prefix]="expression"
keyExp[prefixKey] "expression" + (let-prefixKey="export") +
+ Notice that the prefix + is added to the key +
letlet-local="export"
+ +### Microsyntax examples + +The following table demonstrates how Angular desugars microsyntax. + + + + + + + + + + + + + + + + + + + + + + +
MicrosyntaxDesugared
*ngFor="let item of [1,2,3]"<ng-template ngFor let-item [ngForOf]="[1,2,3]">
*ngFor="let item of [1,2,3] as items; trackBy: myTrack; index as i"<ng-template ngFor let-item [ngForOf]="[1,2,3]" let-items="ngForOf" [ngForTrackBy]="myTrack" let-i="index"> +
*ngIf="exp"<ng-template [ngIf]="exp">
*ngIf="exp as value"<ng-template [ngIf]="exp" let-value="ngIf">
+ Studying the [source code for `NgIf`](https://github.com/angular/angular/blob/master/packages/common/src/directives/ng_if.ts "Source: NgIf") and [`NgForOf`](https://github.com/angular/angular/blob/master/packages/common/src/directives/ng_for_of.ts "Source: NgForOf") is a great way to learn more. - {@a template-input-variable} {@a template-input-variables} -### Template input variable +## Template input variable A _template input variable_ is a variable whose value you can reference _within_ a single instance of the template. There are several such variables in this example: `hero`, `i`, and `odd`. @@ -346,7 +472,7 @@ variable as the `hero` declared as `#hero`. {@a one-per-element} -### One structural directive per host element +## One structural directive per host element Someday you'll want to repeat a block of HTML but only when a particular condition is true. You'll _try_ to put both an `*ngFor` and an `*ngIf` on the same host element.