DEV Community: Khang Tran ⚡️

🅰️🚀 𝗔𝗻𝗴𝘂𝗹𝗮𝗿 𝘃𝟭𝟴 𝗛𝘆𝗯𝗿𝗶𝗱 𝗖𝗵𝗮𝗻𝗴𝗲 𝗗𝗲𝘁𝗲𝗰𝘁𝗶𝗼𝗻 𝗠𝗼𝗱𝗲

Khang Tran ⚡️ — Mon, 29 Apr 2024 12:51:56 +0000

From version 18, Angular will adopt Hybrid change detection scheduling by default, leading to DX improvements.

What is exactly the Hybrid Mode?

• When Angular receives a clear indication that templates need to be refreshed and change detection should run again, this should not be ignored, 𝘳𝘦𝘨𝘢𝘳𝘥𝘭𝘦𝘴𝘴 𝘰𝘧 𝘸𝘩𝘢𝘵 𝘡𝘰𝘯𝘦 𝘪𝘵 𝘩𝘢𝘱𝘱𝘦𝘯𝘦𝘥 𝘪𝘯.
• It means now Angular will ensure change detection does run, even when the state update originates 𝘧𝘳𝘰𝘮 𝘰𝘶𝘵𝘴𝘪𝘥𝘦 𝘵𝘩𝘦 𝘻𝘰𝘯𝘦.
• It leads to DX improvements since we no longer need to write code that utilizes Angular Zone on-demand, jumping in and out of the Angular Zone using ngZone.runOutSideAngular(() => ...)/ ngZone.run(() => ...), respectively.

Angular APIs to schedule change detection

• calling ChangeDetectorRef.markForCheck
• calling ComponentRef.setInput
• updating a signal that is read in a template
• when bound host or template listeners are triggered
• attaching a view that is marked dirty
• removing a view
• registering a render hook (templates are only refreshed if render hooks do one of the above)

Back to top example

For more information, highly recommend the following article by Matthieu Riegler:
https://riegler.fr/blog/2024-04-17-zoneless-with-zoneless-hybrid

Angular Directive Grammar & Microsyntax: Demystifying the Hidden Parts

Khang Tran ⚡️ — Fri, 03 Nov 2023 07:44:40 +0000

Introduction

<div *ngFor="let leaf of ['🍀', '🍀🍀', '🍀🍀🍀']; let i = index;">
  <p>{{i + 1}}. {{leaf}}</p>
</div>

1. 🍀
2. 🍀🍀
3. 🍀🍀🍀

If you've worked with Angular, I'm sure you've come across this *ngFor syntax at least once: let leaf of ['🍀', '🍀🍀', '🍀🍀🍀']; let i = index;". However, have you ever wondered?

Is there any alternative *ngFor syntax?
Where does the index variable come from?
How does the leaf variable iterate over and reference items of ['🍀', '🍀🍀', '🍀🍀🍀']?
Why is it let ... of ...? Can we change it to let ... something ...?

What do you think about trying the following syntaxes with *ngFor?

1. let leaf of ['🌱', '🍀', '🌿']; let i = index;
2. let leaf; let i = index; of ['🌱', '🍀', '🌿'];
3. let i = index; let leaf; of ['🌱', '🍀', '🌿'];
4. let i = index let leaf; of: ['🌱', '🍀', '🌿'];
5. let i = index; of ['🌱', '🍀', '🌿']; let leaf;
6. let i = index; of: ['🌱', '🍀', '🌿'] let leaf;
7. 'Magic 🪄'; let i = index; of: ['🌱', '🍀', '🌿']; let leaf;
8. let leaf = $implicit of ['🌱', '🍀', '🌿']; let i = index;
9. let leaf = $implicit; let i = index; of ['🌱', '🍀', '🌿'];
10. let leaf = $implicit, let i = index, of ['🌱', '🍀', '🌿'];

You can quickly find the answer via this StackBlitz link.
Surprisingly, these peculiar syntaxes compile without any errors. 🤔
How does this happen? What are the rules behind these syntax variations?

Demystifying *ngFor syntax

At first glance, you might be under the impression that you're required to use a semicolon to delimit the calls and adhere to a certain order, or that there might be more rules you don't yet understand about how to use the syntax. But that's not the case - the syntax is actually quite flexible more than that.

Angular's microsyntax has 4 building blocks, that when combined in a particular way, make up the entire microsyntax API. These building blocks are:

Expressions
The as keyword
Keyed expressions
let bindings

1. Expressions

Anything that, when referenced, returns a value.

Raw value

<p *hello="'👋 Hey there'"></p>

Calling a function

<p *hello="greeting()"></p>

Referenced a variable

<p *ngIf="shouldDisplay"></p>

Operator (9 * 9)

2. The as keyword

The rules behind the as keyword as an alternative to let. The most commonly used is combining between *ngIf and AsyncPipe.

<div *ngIf="(myFutureGirl$ | async) as myFutureGirl">
  {{myFutureGirl}}
<div>

Oops, 404 🤦‍♂️

3. keyExp - Key Expressions

A key expression is simply an expression that you're able to bind to an input on a structural directive.

For example, the *ngFor directive includes an ngForOf input as follows:

/**
 * The value of the iterable expression, which can be used as a
 * [template input variable](guide/structural-directives#shorthand).
 */
@Input()
set ngForOf(ngForOf: U&NgIterable<T>|undefined|null) {
  this._ngForOf = ngForOf;
  this._ngForOfDirty = true;
}

In this case, the key expression is the of keyword. This directly answers the question, Why is it let ... of ...?

4. let bindings

The let binding is used for reference the Template Context. Let's take a look at our example:

let leaf of ['🌱', '🍀', '🌿']; let i = index;

There are two types of references made using let bindings:

Implicit

In this case, the assigned expression on the right side is omitted, and it is equivalent to the following:

let leaf = $implicit

Angular automatically assigns the reference with the $implicit key in the context.

Explicit

let i = index

When we use let i = index, it is clear that the variable i references the index key in the context.

Combining Things Together

It starts with the * reserved token. It is an Angular special syntax companion with the Angular Structural Directive.
Then, you have to declare the selector value of the directive itself.
Finally, you can bind to the selector as with any other input using the = token.

The contents of the input itself are where the microsyntax goes.

1. First Item

Either an expression or a let binding.

If an expression is passed, the value of the expression will be passed to the same input name as the selector itself.

Let's take a look at *ngIf implementation:

@Directive({
  selector: '[ngIf]',
  standalone: true,
})
export class NgIf<T = unknown> {
  /**
   * The Boolean expression to evaluate as the condition for showing a template.
   */
  @Input()
  set ngIf(condition: T) {
    this._context.$implicit = this._context.ngIf = condition;
    this._updateView();
  }
}

*ngIf includes an ngIf input that is the same as the [ngIf] selector itself.

If a let binding is the first item, it will work exactly as it's explained in the previous section.

<!-- ✅ These ARE valid for the first item -->
<p *ngIf="'Expression'"></p>
<p *ngFor="let i = index; ..."></p>

<!-- 🛑 But these are NOT valid for the first item -->
<p *ngFor="of: ['🌱', '🍀', '🌿']; ..."></p>
<p *ngFor="index as i"></p>

2. Second Item and Beyond

After the first item, you’re able to pass in a let binding, an as binding, or a key expression.

Let's revisit these *ngFor syntaxes at the very beginning of this post:

1. let leaf of ['🌱', '🍀', '🌿']; let i = index;
2. let leaf; let i = index; of ['🌱', '🍀', '🌿'];
3. let i = index; let leaf; of ['🌱', '🍀', '🌿'];
4. let i = index let leaf; of: ['🌱', '🍀', '🌿'];
5. let i = index; of ['🌱', '🍀', '🌿']; let leaf;
6. let i = index; of: ['🌱', '🍀', '🌿'] let leaf;
7. 'Magic 🪄'; let i = index; of: ['🌱', '🍀', '🌿']; let leaf;
8. let leaf = $implicit of ['🌱', '🍀', '🌿']; let i = index;
9. let leaf = $implicit; let i = index; of ['🌱', '🍀', '🌿'];
10. let leaf = $implicit, let i = index, of ['🌱', '🍀', '🌿'];

In fact, these *ngFor syntaxes end up with the same result:

<ng-template ngFor let-leaf [ngForOf]="['🌱', '🍀', '🌿']" let-i="index">
  ...
</ng-template>

Optional Separators

One side note, maybe you've already figured out from these *ngFor syntaxes above.
Just as the : is optional in the a key expression, all separators in the micro syntax are optional.

👋 Hey there

If you want to gain more insights into how Angular Structural Directives internals, you can reference my previous blog post

Demystifying the Angular Structural Directives in a nutshell

Thank you for making it to the end

Thank you for choosing to read this blog post among the tens of thousands of great blog posts out there. And I will be really happy if you find something interesting from my blog post.

Reference

Angular Templates — From Start to Source

Master the Art of Angular Content Projection

Khang Tran ⚡️ — Sun, 29 Oct 2023 13:10:16 +0000

Introduction

🚦 When it comes to creating customizable components in Angular, think of it as customizing your morning coffee - you've got your base (@Input(), @Output()) and your extras (*ngIf) to create the perfect brew. However, the more toppings you add to your morning coffee, the more your component gets too cozy with your underlying business logic.

Ideally, a component’s job is to enable only the user experience.

In this blog post, we're peeling back the layers to reveal its untapped potential to build Angular components that are both flexible and customizable ☕🚀.

Let's begin with Angular content projection.

1. What is Angular content projection? (<ng-content>)

Content projection is a pattern in which you insert or project, the content you want to use inside another component.

To illustrate this concept, consider the following example:

@Component({
  standalone: true,
  selector: 'app-greeny',
  template: `
    <p>Welcome to Greeny Land 🍀!</p>
    <ng-content></ng-content>
  `,
})
export class GreenyComponent {}

@Component({
  selector: 'my-app',
  standalone: true,
  imports: [CommonModule, GreenyComponent],
  template: `
    <app-greeny>
      <p>I'm a Seeding 🌱, a new beginning and a fresh start.</p>
    </app-greeny>
  `,
})
export class App {}

bootstrapApplication(App);

By adding <ng-content></ng-content> within the GreenyComponent template, you empower the dynamic inclusion and the seamless blending of content from the parent component.

Welcome to Greeny Land 🍀!
I'm a Seeding 🌱, a new beginning and a fresh start.

2. Multi-slot content projection

Angular extends content projection beyond its basic concept by introducing multi-slot content projection, which allows content to be inserted into specific designated slots within a component, granting finer control over customization.

Let's explore this advanced feature through a practical example using the Pokémon API:

pokemon.component.ts

@Component({
  standalone: true,
  selector: 'app-pokemon',
  template: `
    <div class="header-wrapper">
      <ng-content select=".pokemon-header"></ng-content>
    </div>
    <div class="detail-wrapper">
      <ng-content select=".pokemon-detail"></ng-content>
    </div>
  `,
})
export class PokemonComponent {}

We've defined the PokemonComponent to support multi-slot content projections by specifying a concrete select attribute (selector) for each <ng-content> slot:

pokemon-header
pokemon-detail

Angular supports selectors for any combination of tag name, attribute, CSS class, and the :not pseudo-class.

standard-pokemon.component.ts

Let's create StandardPokemonComponent to leverage the multi-slot content projection:

@Component({
  selector: 'app-standard-pokemon',
  standalone: true,
  imports: [PokemonComponent, TitleCasePipe],
  template: `
    <div class="standard">
      <app-pokemon [class]="pokemon.type">
        <div class="pokemon-header">
          <div class="number"><small>#{{pokemon.id}}</small></div>
          <img [src]="pokemon.image" [alt]="pokemon.name" />
        </div>
        <div class="pokemon-detail">
          <h3>{{pokemon.name | titlecase}}</h3>
          <small>Type: {{pokemon.type}}</small>
        </div>
      </app-pokemon>
    </div>
  `,
  styleUrls: ['./standard-pokemon.component.scss'],
})
export class StandardPokemonComponent {
  @Input() pokemon: any;
}

To project content into the corresponding slot, you simply need to define a <div> element containing either the pokemon-header or pokemon-detail class.

The pokemon-header will include the Pokemon index and image,

<div class="pokemon-header">
  <div class="number"><small>#{{pokemon.id}}</small></div>
  <img [src]="pokemon.image" [alt]="pokemon.name" />
</div>

while the pokemon-detail will contain the Pokemon name and type.

<div class="pokemon-detail">
  <h3>{{pokemon.name | titlecase}}</h3>
  <small>Type: {{pokemon.type}}</small>
</div>

Additionally, we'll render the background color based on the Pokemon's type.

🔥 Now, let's bring our Pokémons to life:

@Component({
  selector: 'my-app',
  standalone: true,
  imports: [CommonModule, StandardPokemonComponent],
  template: `
    <h1 class="title">Pokémon Evolution</h1>

    <div class="container">
      <ng-container *ngIf="pokemons$ | async as pokemonList">
        <ng-container *ngFor="let pokemon of pokemons">
          <app-standard-pokemon [pokemon]="pokemon"></app-standard-pokemon>
        </ng-container>
      </ng-container>
    </div>
  `,
  styles: [...]
})
export class App {
  pokemons$ = inject(PokemonService).getPokemons();
}

Link to StackBlitz

So far, we've learned how Angular's multi-slot content projection works. However, what is the practical use for it? Why don't we simply compose everything inside the PokemonComponent? Let's address these questions in the upcoming section.

3. It's time to make Content Projection shining

Let's assume we've received a new requirement from our boss. Instead of just supporting standard Pokémon, he wants us to embrace the modern Pokémon style, as follows:

Let's see how the ModernPokemonComponent implementation first:

@Component({
  selector: 'app-modern-pokemon',
  standalone: true,
  imports: [PokemonComponent, TitleCasePipe],
  template: `
    <div class="modern">
      <app-pokemon>
        <div class="pokemon-header">
          <div class="number"><small>{{pokemon.id}}</small></div>
          <img pokemon-image [src]="pokemon.artwork" [alt]="pokemon.name" />
        </div>
        <div class="pokemon-detail">
          <div class="headline">
            <h3 class="name">{{pokemon.name | titlecase}}</h3>
            <div class="type-wrapper">
              <small class="type">{{pokemon.type | titlecase}}</small>
              <small>{{getTypeEmoji(pokemon.type)}}</small>
            </div>
          </div>
          <div class="stat-wrapper">
            <div class="stat">
              <span class="stat-number">{{pokemon.attack}}</span>
              <span class="stat-name">Attack</span>
            </div>
            <div class="stat">
              <span class="stat-number">{{pokemon.defense}}</span>
              <span class="stat-name">Defense</span>
            </div>
            <div class="stat">
              <span class="stat-number">{{pokemon.speed}}</span>
              <span class="stat-name">Speed</span>
            </div>
          </div>
        </div>
      </app-pokemon>
    </div>
  `,
  styleUrls: ['./modern-pokemon.component.scss'],
})
export class ModernPokemonComponent {
  @Input() pokemon: any;

  getTypeEmoji(type: string): string {
    ...
  }
}

The Pokémon header remains unchanged, while the Pokémon detail section comprises two main components: the headline and the stats.

headline

<div class="headline">
  <h3 class="name">{{pokemon.name | titlecase}}</h3>
  <div class="type-wrapper">
    <small class="type">{{pokemon.type | titlecase}}</small>
    <small>{{getTypeEmoji(pokemon.type)}}</small>
  </div>
</div>

stats

<div class="stat-wrapper">
  <div class="stat">
    <span class="stat-number">{{pokemon.attack}}</span>
    <span class="stat-name">Attack</span>
  </div>
  <div class="stat">
    <span class="stat-number">{{pokemon.defense}}</span>
    <span class="stat-name">Defense</span>
  </div>
  <div class="stat">
    <span class="stat-number">{{pokemon.speed}}</span>
    <span class="stat-name">Speed</span>
  </div>
</div>

As you can see, the pokemon-detail is entirely different. However, we don't need to make any changes to the PokemonComponent to support it. Everything is handled separately within the ModernPokemonComponent. Therefore, we can ensure that the StandardPokemonComponent remains unchanged without any effects.

Thanks to Content Projection, we can accommodate two distinct Pokémon cards with entirely different styles.

Separation of Concerns

The UI part is separately handled by StandardPokemonComponent and ModernPokemonComponent

Open-Closed Principle

The Content Projection helps us avoid getting our hands dirty by adding ModernPokemonComponent without modifying the common PokemonComponent.

Link to StackBlitz

Final thought

Thank you for making it to the end! Content Projection is a fundamental tool that helps us create flexible components. We will continue this series by delving into another powerful Angular tool, *ngTemplateOutlet. If you found something interesting in this post or gained some value from it, please let me know by leaving a comment or reacting to this post. Your feedback and engagement are a significant source of motivation that keeps me inspired to continue publishing my next blog. ❤️

Read more:

Demystifying the Angular Structural Directives in a nutshell

Khang Tran ⚡️ — Sun, 15 Oct 2023 13:13:53 +0000

1. Introduction

I'm sure you're definitely familiar with Angular's commonly used structural directives that we use all the time: ngIf, ngFor, and ngSwitch. But have you ever wondered about the ✨magic✨ behind that little asterisk (*)? In this post, I'll take you on a journey to demystify the power of Angular's micro syntax. Let's dive right in.

Let's begin by trying something NEW that you've probably never done before

🔥 Using *ngIf WITHOUT asterisk (*)

<div ngIf="true">Does it really work 🤔?</div>

If you try it on your own, you'll quickly discover that, unfortunately, it doesn't work, and the console will throw this error:

❗Error: NG0201: No provider for TemplateRef found.

So what exactly is TemplateRef and why does removing the asterisk (*) from the ngIf directive trigger this error? (The answer awaits you in the upcoming section)

🔥 What happens if we use only the asterisk (*), as in the headline of this post?

<p *>Demystifying the Angular Structural Directives 
in a nutshell</p>

Perhaps you'll experience the same sense of surprise I did when I first tried this: no errors, and nothing rendered in the view. It sounds like magic, doesn't it? So WHY does this happen??? 🐣

Everything happens for a reason.

Actually, the above syntax is just the shorthand (syntax desugaring) of <ng-template>. This convention is the shorthand that Angular interprets and converts into a longer form like the following:

<ng-template>
  <p>Demystifying the Angular Structural Directives 
in a nutshell</p>
<ng-template>

And based on the Angular documentation, the <ng-template> is not rendered by default.

*ngIf and *ngFor behave in a similar fashion. Angular automates the handling of <ng-template> behind the scenes for these directives as well.

// Shorthand
<div *ngIf="true">Just say hello</div>

// Long form
<ng-template [ngIf]="true">
  <div>Just say hello</div>
</ng-template>

// Shorthand
<span *ngFor="let greenyPlant of ['🌱', '🌿', '🍀']">
  {{greenyPlant}}
</span>

// Long form
<ng-template ngFor let-greenyPlant [ngForOf]="['🌱', '🌿', '🍀']">
  <span>{{greenyPlant}}</span>
</ng-template>

You might be curious because, according to the documentation, <ng-template> isn't rendered by default, and we need to specifically instruct it to do so. So, what exactly does specifically instruct mean, and how do *ngIf and *ngFor handle the rendering of <ng-template>?

2. Create our own custom structural directive

Delve into Angular NgIf source code

The first surprising detail, which might easily go unnoticed without a deeper look into the NgIf source code, is the absence of the asterisk (*) symbol in the NgIf selector. Instead, it ONLY uses plain '[ngIf]' as the selector. (the same applies to other Angular structural directives as well)

From the constructor, you'll find TemplateRef and ViewContainerRef. These are the two key elements required for rendering the template.

TemplateRef

First of all, we need the necessary information to render the template to the DOM, here is where TemplateRef comes into play. You can think of a TemplateRef as a blueprint for generating HTML template content.

<ng-template>
  <p>Everything placed inside ng-template can be
    referenced by using TemplateRef</p>
</ng-template>

Let's take a look at the internal workings of the TemplateRef.

@Directive({
  selector: '[greeting]',
  standalone: true,
})
export class GreetingDirective implements OnInit {
  #templateRef = inject(TemplateRef);

  ngOnInit(): void {
    console.log((this.#templateRef as any)._declarationTContainer.tView.template);
  }
}

@Component({
  selector: 'my-app',
  standalone: true,
  imports: [CommonModule, GreetingDirective],
  template: `
    <p>Demystifying the Angular Structural Directives in a nutshell</p>
    <ng-template greeting>Xin chào - Hello from Viet Nam 🇻🇳!</ng-template>
  `,
})
export class App {}

Under the hood, Angular will translate the <ng-template> into the TemplateRef's instructions, which we can later use to dynamically render the content of the <ng-template> into the view.

function App_ng_template_2_Template(rf, ctx) { if (rf & 1) {
    i0.ɵɵtext(0, "Xin ch\u00E0o - Hello from Viet Nam \uD83C\uDDFB\uD83C\uDDF3!");
} }

ViewContainerRef

Until now, we know how Angular interprets TemplateRef's instructions, but how does Angular handle the process of hooking the template into the view?

Let's return to the previous example and inspect the DOM element.

<!DOCTYPE html>
<html class="ml-js">
  <head>...</head>
  <body>
    <my-app ng-version="16.2.8">
      <!--container-->
    </my-app>
  </body>
</html>

You'll notice that there is a special comment markup . This is exactly where the template will be inserted into the view.

Specifically, it is a comment node that acts as an anchor for a view container where one or more views can be attached. (view_container_ref.ts)

Let's make a minor update to the GreetingDirective to see how it works.

@Directive({
  selector: '[greeting]',
  standalone: true,
})
export class GreetingDirective implements OnInit {
  #vcr = inject(ViewContainerRef);

  ngOnInit(): void {
    console.log(this.#vcr.element.nativeElement);
  }
}

You'll get exactly  comment node from the console.

So let's put everything together by rendering our <ng-template> into the view.

@Directive({
  selector: '[greeting]',
  standalone: true,
})
export class GreetingDirective implements OnInit {
  #templateRef = inject(TemplateRef);
  #vcr = inject(ViewContainerRef);

  ngOnInit(): void {
    this.#vcr.createEmbeddedView(#templateRef);
  }
}

The final piece is createEmbeddedView. It essentially tells Angular to render the content defined in the TemplateRef and insert it within the element that the ViewContainerRef is associated with.

Link to Stackbliz

Can we do it better?

You may wonder if there is a way to automatically render the <ng-template> instead of handling it manually so tedious. You're right; let's delegate the work to *ngTemplateOutlet.

@Component({
  selector: 'my-app',
  standalone: true,
  imports: [CommonModule, NgTemplateOutlet],
  template: `
    <ng-container *ngTemplateOutlet="greetingTemplate"></ng-container>
    <ng-template #greetingTemplate>Xin chào - Hello from Viet Nam 🇻🇳!</ng-template>
  `,
})
export class App {}

The following is a snippet from the source code of ng_template_outlet.ts. It handles exactly as the whole story we discovered above.

@Directive({
  selector: '[ngTemplateOutlet]',
  standalone: true,
})
export class NgTemplateOutlet<C = unknown> implements OnChanges {
  private _viewRef: EmbeddedViewRef<C>|null = null;

  ngOnChanges(changes: SimpleChanges) {
    ...

    if (this._shouldRecreateView(changes)) {
      // Create a context forward `Proxy` that will always bind to the user-specified context,
      // without having to destroy and re-create views whenever the context changes.
      const viewContext = this._createContextForwardProxy();
      this._viewRef = viewContainerRef.createEmbeddedView(this.ngTemplateOutlet, viewContext, {
        injector: this.ngTemplateOutletInjector ?? undefined,
      });
    }
  }
}

Let's create a more complex directive using NASA Open APIs

We all know to render the TemplateRef within the view, we simply need to use the createEmbeddedView from ViewContainerRef. However, what if we want to pass the data from our custom directive to the TemplateRef? The answer is Template Context.

Template Context

Inside the <ng-template> tags you can reference variables present in the surrounding outer template. Additionally, a context object can be associated with <ng-template> elements. Such an object contains variables that can be accessed from within the template contents via template (let and as) declarations. ( context)

Understand template context with NgFor

I have no special talents. I am only passionately curious. - Albert Einstein

At the very beginning, when I first attempted to use NgFor, I just accepted the fact that we can use index, odd, even, and other data-binding context without wondering where they came from. It's a bit clearer to me now 🥰.

<div *ngFor="let greenyPlant of ['🌱', '🌿', '🍀']; let i = index"
  [class.even]="even" [class.odd]="odd">
  {{greenyPlant}}
</div>

In addition to the index, even, odd, you can reference all NgFor local variables and their explanation through NgFor documentation.

It's time to create our NASA Planetary Directive

We will create a custom structural directive to fetch the Astronomy Picture of the Day from NASA Open APIs and make the response data, including the title, image, and explanation, available through the template context for later use in our template.

interface NASAPlanetary {
  hdurl: string;
  title: string;
  explanation: string;
}

@Directive({
  selector: '[nasaPlanetary]',
  standalone: true,
})
export class NASAPlanetaryDirective implements OnInit {
  #templateRef = inject(TemplateRef);
  #vcr = inject(ViewContainerRef);
  #http = inject(HttpClient);

  ngOnInit(): void {
    this.#http.get<NASAPlanetary>('https://api.nasa.gov/planetary/apod?api_key=DEMO_KEY')
      .pipe(take(1))
      .subscribe(({ title, hdurl, explanation }) => {
        this.#vcr.createEmbeddedView(this.#templateRef, {
          title, hdurl, explanation,
        });
    });
  }
}

We can bind data to the template context by passing it as a second parameter of createEmbeddedView, as shown in the code above. You can find out more about it through the documentation.

Rendering Astronomy Picture of the Day into the view

@Component({
  selector: 'my-app',
  standalone: true,
  imports: [CommonModule, HttpClientModule, NASAPlanetaryDirective],
  template: `
    <div *nasaPlanetary="
        let hdurl = hdurl; 
        let title = title; 
        explanation as explanation
      " 
      class="mt-5 d-flex justify-content-center">
      <div class="card" style="width: 18rem;">
      <img [src]="hdurl" class="card-img-top" [alt]="title">
      <div class="card-body">
        <h5 class="card-title">{{title}}</h5>
        <p class="card-text explaination">{{explanation}}</p>
      </div>
    </div>
  `,
  styles: [...],
})
export class App {}

You can use either let or as to reference the data-binding context.

Indeed, the above code will be converted to <ng-template> long form as follows:

<ng-template nasPlanetary let-hdurl="hdurl" let-title="title" let-explanation="explanation">
  ...
</ng-template>

Congratulations, you'll receive today's news from the S P A C E 🚀🌌.

Supporting Dynamic Date

But what if we want to retrieve a picture for a specific date rather than today? Let's enable our directive to support dynamic date through the use of the @Input decorator.

@Input('nasaPlanetary') date = new Date().toLocaleDateString('en-CA');

With this input property, you can specify a date in the format YYYY-MM-DD to fetch an image from a particular day. If no date is provided, the directive will default to today.

To ensure that this input property works seamlessly with our directive, we need to make sure that the input alias matches the directive selector, which is nasaPlanetary in our case. So that it is recognized as the default input of the directive.

To fetch an image for a specific date, we'll need to modify the NASA Open APIs endpoint by including the date query parameter:

`https://api.nasa.gov/planetary/apod?date=${this.date}&api_key=DEMO_KEY`

Finally, binding data to the directive can be achieved as follows:

// The data-binding context remains unchanged
<div *nasaPlanetary="'1998-01-08'; ..."></div>

💡 Property bindding issue
Why can't we bind data to a directive input as we do with a normal component input?

<div *nasaPlanentary [date]="'1998-01-08'">
  Property bidding issue
</div>

We'll end up with the following error:

Can't bind to 'date' since it isn't a known property of 'div'.

Let's examine the long version of the code above to understand the underlying reason.

<div [date]="'1998-01-08'">
  <ng-template>Property bidding issue</ng-template>
</div>

Indeed, the date property is applied to the <div> tag instead of <ng-template> itself. That's why Angular considers date property as a property of the <div> tag, rather than the input of the directive. And this is exactly the reason why we got the error Can't bind to 'date' since it isn't a known property of 'div'.

Supporting loading template

We can bind the default input of the directive by giving it the same name as the directive selector. But what if we want to add additional inputs to the directive? Let's achieve this by implementing support for a loading template.

Let's add a new input to support the loading template:

@Input('nasaPlanetaryLoading') loadingTemplate: TemplateRef<any> | null =
    null;

If you notice, the above input follows the naming convention:

💡 Directive input name = directiveSelector + identifier (first character capital)

For the identifier, we can choose whatever we want. In our case, since we want to add this input to support loading purposes, I've named it loading.

So let's define the loading template and add it to the directive:

<div *nasaPlanetary="'1998-01-08'; loading loadingTemplate; ...">

<ng-template #loadingTemplate>
  You can define whatever you want for the loading template.
  We will pass the loading template to the directive
  by using the #templateVariable.
</ng-template>

Final demo

I believe that covers everything I've learned about Angular Structural Directives that I'd like to share in this post. While it may not be the most practical example for real-life projects, I hope you can still find something interesting.

Link to Stackbliz

3. Final thought

The most important thing in writing is to have written. I can always fix a bad page. I can’t fix a blank one. - Nora Roberts

Thank you for making it to the end! This is my very first blog, and I'm thrilled to have completed it. I'm even more delighted if you found something helpful in my blog post. I'd greatly appreciate hearing your thoughts in the comments below, as it would be a significant source of motivation for me to create another one. ❤️

Read More

Master the Art of Angular Content Projection

References

1. Angular documentation
2. Mastering Angular Structural Directives - The basics (Robin Goetz)
3. Unlocking the Power of ngTemplateOutlet - Angular Tiny Conf 2023 (Trung Vo)
4. Structural Directives in Angular – How to Create Custom Directive (Dmytro Mezhenskyi)

DEV Community: Khang Tran ⚡️

🅰️🚀 𝗔𝗻𝗴𝘂𝗹𝗮𝗿 𝘃𝟭𝟴 𝗛𝘆𝗯𝗿𝗶𝗱 𝗖𝗵𝗮𝗻𝗴𝗲 𝗗𝗲𝘁𝗲𝗰𝘁𝗶𝗼𝗻 𝗠𝗼𝗱𝗲

What is exactly the Hybrid Mode?

Angular APIs to schedule change detection

Back to top example

Angular Directive Grammar & Microsyntax: Demystifying the Hidden Parts

Introduction

Demystifying *ngFor syntax

1. Expressions

2. The `as` keyword

3. `keyExp` - Key Expressions

4. `let` bindings

Combining Things Together

1. First Item

2. Second Item and Beyond

Optional Separators

Master the Art of Angular Content Projection

Introduction

1. What is Angular content projection? (<ng-content>)

2. Multi-slot content projection

3. It's time to make Content Projection shining

Final thought

Demystifying the Angular Structural Directives in a nutshell

1. Introduction

2. Create our own custom structural directive

3. Final thought

DEV Community: Khang Tran ⚡️

🅰️🚀 𝗔𝗻𝗴𝘂𝗹𝗮𝗿 𝘃𝟭𝟴 𝗛𝘆𝗯𝗿𝗶𝗱 𝗖𝗵𝗮𝗻𝗴𝗲 𝗗𝗲𝘁𝗲𝗰𝘁𝗶𝗼𝗻 𝗠𝗼𝗱𝗲

What is exactly the Hybrid Mode?

Angular APIs to schedule change detection

Back to top example

Angular Directive Grammar & Microsyntax: Demystifying the Hidden Parts

Introduction

Demystifying *ngFor syntax

1. Expressions

2. The as keyword

3. keyExp - Key Expressions

4. let bindings

Combining Things Together

1. First Item

2. Second Item and Beyond

Optional Separators

Master the Art of Angular Content Projection

Introduction

1. What is Angular content projection? (<ng-content>)

2. Multi-slot content projection

3. It's time to make Content Projection shining

Final thought

Demystifying the Angular Structural Directives in a nutshell

1. Introduction

2. Create our own custom structural directive

3. Final thought

2. The `as` keyword

3. `keyExp` - Key Expressions

4. `let` bindings