Creating Custom Structural Directives in Angular

This talk is about creating custom structural directives to implement the logic to create embedded views. It gives a brief introduction to directives, views and dynamic views, and TemplateRef, view containers and ViewContainerRef, naming input properties, how structural directives pass context to embedded views which they access using template input variables. It also talks about the syntactic sugar provided by the asterisk and the microsyntax in the string passed to structural directives when using the asterisk syntax.

Transcript

1. Creating Custom Structural Directives By Ashnita Bali @ashnita01
2. What we will cover 1. Directives 2. Views and dynamic views 3. Steps to create custom structural directives a. <ng-template> and TemplateRef b. View containers and ViewContainerRef 4. Magic behind the asterisk 5. Microsyntax
3. 1. Directives
4. “Directives are HTML elements and attributes created by Angular applications and Angular libraries.”
5. Directives Components Attribute Directives Structural Directives
6. Component View (html) Styles (css) Data & methods (ts) Attribute Directives Appearance and behaviour Structural Directives View structure
7. Directives @Component({ selector: ‘app-book-detail’ }) export class BookDetailComponent {} @Directive({ selector: ‘[appHover]’ }) export class HoverDirective {}
8. Changes host element’s appearance or behaviour Any element @HostBinding @HostListener @Input @Output Attribute Directive Structural Directive Changes view structure <ng-template> asterisk * syntax TemplateRef ViewContainerRef @Input Context object
9. @Component({ selector: ‘app-book-list’, template: ` <app-book-detail appHover *ngfor=”let book of books$ | async”> </app-book-detail>` }) export class BookListComponent {}
10. Directives examples Angular Application Angular Libraries HTML elements <app-root> <app-book-list> <router-outlet> <ng-template>, <ng-container>, <ng-content> HTML attributes appCarousel appHighlight ngFor, ngIf, ngTemplateOutlet, ngSwitchCase routerLink, ngClass, ngStyle, ngForm
11. 2. Views & Dynamic views
12. “A view is the smallest grouping of display elements that can be created and destroyed together. “ - angular.io
13. @Component({ template: ` <h1>Defines component view</h1> <app-item *ngFor=”let item of items$ | async”> </app-item> `, }) Add Remove Move
14. Dynamic views Dynamic components ComponentFactoryResolver Embedded views <ng-template> TemplateRef ViewContainerRef
15. Embedded views (TemplateRef) ViewContainerRef Structural directive
16. “Structural directives implement the logic to render embedded views.”
17. 1. Rendering a view based on some reusable logic: *appHasRole, *appHasPermision, *appHasFeature 2. Only implement the functionality, allowing the user to define the view: *appCarousel 3. Declare variables *appLet Examples of when to create structural directives
18. <div *appLet=”{ obs1: obs1$ | async, obs2: obs2$ | async } as data”> {{ data.obs1.prop }} {{ data.obs2.prop }} </div>
19. 3. Steps to create structural directives
20. What logic does the structural directive implement? API: input properties, context object Plan
21. @Component({ template: ` <div *appHasRole=”’admin’”> User with admin role can see this </div> `})
22. 1. ng g d hasRole Creating custom structural directive
23. import { Directive } from '@angular/core'; @Directive({ selector: '[appHasRole]' }) export class HasRoleDirective { constructor() {} }
24. 2. Get the TemplateRef instance Creating custom structural directive
25. Dependency Injection export class HasRoleDirective { constructor( private templateRef: TemplateRef<HasRoleContext> ) {} }
26. <ng-template> and TemplateRef
27. <ng-template></ng-template>
28. compiler/src/ml_parser/tags.ts
29. <ng-template> @Component({ template: ` <ng-template [appHasRole]=”’admin’”> <div>User with admin role can see this</div> </ng-template> `})
30. TemplateRef abstract class TemplateRef<C> { abstract elementRef: ElementRef abstract createEmbeddedView(context: C): EmbeddedViewRef<C> }
31. 3. Get the ViewContainerRef instance Creating custom structural directive
32. Dependency Injection export class HasRoleDirective { constructor( private vcr: ViewContainerRef, private templateRef: TemplateRef<HasRoleContext> ) {} }
33. View container and ViewContainerRef
34. ViewContainerRef API Methods: createComponent() createEmbeddedView() insert(viewRef, index) clear() detach(index) move(viewRef, index) remove(index) get(index) indexOf(viewRef) Properties: element length injector _embeddedViews Create Manipulate Query
35. ViewContainerRef element _embeddedViews createComponent() createEmbeddedView() move() remove() ... View container <my-comp> <h1>Component View</h1> <!----> </my-comp> <div>User with admin role can see this</div>
36. 4. Input properties Creating custom structural directive
37. @Directive({ selector: '[appHasRole]' }) export class HasRoleDirective { @Input() appHasRole; @Input() appHasRoleElse: TemplateRef<HasRoleContext>; @Input() appHasRoleThen: TemplateRef<HasRoleContext>; } Input properties
38. Input property name = directive attribute name @Component({ template: ` <ng-template [appHasRole]=”’admin’”> <div>User with admin role can see this</div> </ng-template> `})
39. @Component({ template: ` <div *appHasRole=”customer”> User with customer role can see this. </div> `})
40. @Component({ template: ` <div *appHasRole=”’customer’”; else elseRef> User with customer role can see this. </div> <ng-template #elseRef>Render if user doesn’t have role</ng-template> `})
41. 5. Context object Creating custom structural directive
42. Passing context to embedded view instance vcr.createEmbeddedView(templateRef, context);
43. export class HasRoleDirective { @Input() appHasRole; context = { $implicit: this.appHasRole, role: this.appHasRole, } } Context object
44. export class CarouselDirective { @Input() appCarouselFrom; index = 0; context = { $implicit: this.appCarouselFrom[index], control: { next: () => this.next(), previous: () => this.previous() } } } Context object
45. “let localVar2=contextProperty” “contextProperty as localVar3”
46. Template input variables access context properties <ng-template let-book let-next=”next” let-prev=”previous”> <h1>...}<h1> <ng-template> context = { $implicit: currentItem, next: () => this.next(), previous: () => this.previous() }
47. Create type for context object abstract class TemplateRef<C> { abstract createEmbeddedView(context: C): EmbeddedViewRef<C> }
48. ngFor export class NgForOfContext<T> { constructor( public $implicit: T, public ngForOf: NgIterable<T>, public index: number, public count: number) {} get first(): boolean { return this.index === 0; } get last(): boolean { return this.index === this.count - 1; } get even(): boolean { return this.index % 2 === 0; } get odd(): boolean { return !this.even; } }
49. 5. Implement logic Creating custom structural directive
50. export class HasRoleDirective { @Input() appHasRole; constructor(private roleService: RoleService) {} ngOnInit() { this.sub = this.roleService.user$ .pipe(filter(roles => roles.includes(this.appHasRole))) .subscribe(() => { this.vcr.clear(); this.vcr.createEmbeddedView(this.templateRef) }) } }
51. 4.Magic behind the asterisk
52. <div *ngFor=”let book of books”></div> Microsyntax Template input variables Property binding For compiler
53. template_parser.ts ... // ...
54. Component template @Component({ template: ` <div *ngFor=” let book of books; index as i” class=”” appHighlight> <p>Embedded view with book details</p> </div> `})
55. <ng-template ngFor let-book [ngForOf]=”books” let-i=”index”> <div><p>Embedded view with book details</p></div> </ng-template>`
56. <ng-template ngFor let-book [ngForOf]=”books” let-i=”index”> <div><p>Embedded view with book details</p></div> </ng-template>` Host element Root element Property binding Var declaration
57. Component template @Component({ template: ` <div *ngFor=” let book of books; index as i” class=”” appHighlight> <p>Embedded view with book details</p> </div> `})
58. 5. Microsyntax
59. <div *ngFor=”let book of books”></div> Microsyntax Template input variables Property binding
60. *dir=“expr” *dir=“let var” Start of the structural directive string
61. *dir=“expr key2 expr2 key3 expr3” *dir=“expr; key2: expr2; key3: expr3” Separators for readability
62. *dir=“let var1 key1:expr1; ctxProp as var2; key2: expr2” *ngFor=”let item of items; index as i; trackby: f” Input property declarations and property bindings
63. “let localVar1” “let localVar2=contextProperty” “contextProperty as localVar3” Template input variable declarations
64. “let localVar1” “let localVar2=ctxProp1” “ctxProp2 as localVar3” Template input variable declarations
65. Desugared
66. “let localVar1” “let localVar2=ctxProp1” “ctxProp2 as localVar3” Template input variable declarations let-localVar1=”$implicit” let-localVar2=”ctxProp1” let-localVar3=”ctxProp2”
67. *dir=“expr” *dir=“expr; key2: expr2” Input property bindings
68. *dirAttrName=“expr; key2: expr2” Eg: *ngIf=”data; else: elseRef” Input property bindings
69. Desugared
70. *dirAttrName=“expr; key2: expr2” *ngIf=”data; else: elseRef” [dirAttrName]=“expr” [dirAttrNameKey2]=”expr2” [ngIf]=“data” [ngIfElse]=”elseRef” Input property bindings
71. Credit Alexey Zuev @yurzui Reactive Fox @thekiba_io Alex Rickabaugh @synalx Netanel Basal @NetanelBasal
72. Resources 1. https://angular.io/guide/structural-directives 2. https://itnext.io/angular-structural-directives-b54ea21b39a7 3. https://netbasal.com/building-a-simple-carousel-component-with-angular-3a94092b7080 4. https://netbasal.com/understanding-angular-structural-directives-659acd0f67e 5. https://stackoverflow.com/questions/56062311/what-is-the-exact-grammar-for-angulars-structural-dir ectives 6. https://stackoverflow.com/questions/46616334/where-does-angular-4-define-as-local-var-behavior-f or-ngif 7. https://stackoverflow.com/questions/38752744/angular2-how-is-ngfor-expanded
73. Thank you! By Ashnita Bali @ashnita01