Skip to content

Instantly share code, notes, and snippets.

@mhevery
Last active November 21, 2022 09:53
Show Gist options
  • Save mhevery/d3530294cff2e4a1b3fe15ff75d08855 to your computer and use it in GitHub Desktop.
Save mhevery/d3530294cff2e4a1b3fe15ff75d08855 to your computer and use it in GitHub Desktop.
Angular microsyntax gramar

Microsyntax

Microsyntax in Angular allows you to write <div *ngFor="let item of items">{{item}}</div> instead of <ng-template ngFor [ngForOf]="items"><div>{{item}}</div></ng-template.

Constraints

The microsyntax must:

  • be know ahead of time so that IDEs can parse it without knowing what is the underlying semantics of the directive or what directives are present.
  • must translate to key-value attributes in the DOM.

Gramar

*:prefix="( :let | :expression ) (';' | ',')? ( :let | :as | :keyExp )*"

  • :prefix: HTML attribute key.
  • :key: HTML attribute key.
  • :local: local variable name used in the template.
  • :export: value exported by the directive under a given name.
  • :experession: standard angular expression
  • :keyExp = :key ":"? :expression ("as" :local)? ";"?
  • :let = "let" :local "=" :export ";"?
  • :as = :export "as" :local ";"?

Traslation

A microsyntax is translated to the normal binding syntax as follows:

  • :prefix and naked :expression translate to [prefix]="expression"
  • :keyExp - [prefixKey]="expression" (let-prefixKey="export") Notice that the prefix is added to the key
  • :let - let-local="export"
  • :as - let-local="export"

Example

  • *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">
@alirezamirian
Copy link

alirezamirian commented Feb 12, 2018

This is kind of missing in the docs. Perhaps in a less formal, more exemplified form. Inside ngFor kind of covers it but I think it's not complete and general enough.
BTW, the :let in grammar seems to be incomplete as it doesn't cover usage of $implicit export.
Maybe it should be:
:let = "let" :local ("=" :export)? ";"?

@ja02
Copy link

ja02 commented May 31, 2019

Dear @mhevery, milý Mišo,

thanks a lot for posting this info, but, how come this still is not covered by the official DOC? They would just jokingly encourage us to review the sources of ngIf and NgForOf, which don't even seem to contain any parsing logic whatsoever AFAICS.
Also please note that I failed to find out what a "standard angular expression" actually is.

Have been learning Angular for 3 weeks and this "microsyntax" thing is my biggest source of confusion, frustration and disappointment so far.

@crutchcorn
Copy link

crutchcorn commented Jun 9, 2019

@ja02 Microsyntax is not a simple part of Angular. I've been coding professionally in Angular full-time for the past ~2.5 years and still couldn't tell you what the full microsyntax is (which is why I'm here while I'm working on a huge blogpost about this + other template stuff).

Suffice it to say that if you're unfamiliar with front-end frameworks (or even are just learning Angular), you can likely handwave a lot of the microsyntax for now, follow the API docs for ngIf and ngFor for how and when to use stuff like let index = index and you'd be okay. Otherwise, you might end up more frustrated than not for a bit

@ssuperczynski
Copy link

Hey @crutchcorn, could you share link to the post you are working on when ready.

@crutchcorn
Copy link

@ssuperczynski absolutely! I'll have it out sometime in the next week or so.

@crutchcorn
Copy link

Actually, I realize now that this isn't quite right either:
*:prefix="( :let | :expression ) (';' | ',')? ( :let | :as | :keyExp )*"

As it misses the ability to do expression then as for the first item:

*:prefix="( :let | (:expression ("as" :local)?) ) (';' | ',')? ( :let | :as | :keyExp )*"

Would fix that

@mhevery
Copy link
Author

mhevery commented Jul 11, 2019

@crutchcorn
Copy link

I turned this gist into a fairly comprehensive blog post that explains templates in depth, the micro-syntax (including charts for these "regex"s) and even some insight into ngIf and ngFor source (including writing our own rudimentary versions of each)

The charts that I converted from this gist are here:
https://unicorn-utterances.com/posts/angular-templates-start-to-source/#microsyntax-rules

@ssuperczynski

@mojtabadarzi
Copy link

please edit
<ng-template ngFor [ngForOf]="items"><div>{{item}}</div></ng-template
to
<ng-template ngFor let-item [ngForOf]="items"><div>{{item}}</div></ng-template>

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment