Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?
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

This comment has been minimized.

Copy link

@alirezamirian 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

This comment has been minimized.

Copy link

@ja02 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

This comment has been minimized.

Copy link

@crutchcorn 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

This comment has been minimized.

Copy link

@ssuperczynski ssuperczynski commented Jul 2, 2019

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

@crutchcorn

This comment has been minimized.

Copy link

@crutchcorn crutchcorn commented Jul 2, 2019

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

@crutchcorn

This comment has been minimized.

Copy link

@crutchcorn crutchcorn commented Jul 11, 2019

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

This comment has been minimized.

Copy link
Owner Author

@mhevery mhevery commented Jul 11, 2019

@crutchcorn

This comment has been minimized.

Copy link

@crutchcorn crutchcorn commented Jul 22, 2019

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.