Creating Custom Directives: Building Reusable DOM Manipulation Logic.

Creating Custom Directives: Building Reusable DOM Manipulation Logic (A Lecture – Hold the Pop Quiz!)

Alright, class! Settle down, settle down! 👋 Today, we’re diving into the glorious world of Angular directives! Forget those dusty old textbooks; we’re talking about building reusable DOM manipulation magic. Think of it as crafting your own superhero tools for your Angular applications. 😎

Course Objective: By the end of this session, you’ll be able to create custom directives that manipulate the DOM like a seasoned stage magician. Abracadabra! ✨

Prerequisites: Basic Angular knowledge (components, modules, templates) and a healthy dose of caffeine. ☕

What Are Directives, Anyway? (Not the Kind Your Boss Gives You)

Imagine directives as tiny, powerful scripts that tell Angular’s compiler how to transform the DOM. They are instructions that augment or modify the behavior of HTML elements. They are the doers of the Angular world. 🏋️‍♀️

Think of it like this: You have a plain, boring HTML button. But with a directive, you can turn it into a pulsing, glowing, unicorn-powered button that plays a delightful melody when clicked. (Okay, maybe not the unicorn part, but you get the idea!) 🦄🎶

Key Concepts:

• DOM (Document Object Model): A tree-like representation of your HTML page. Directives interact with this tree. 🌳
• Angular Compiler: The engine that reads your Angular templates and directives and transforms them into executable code. ⚙️
• Reusability: The superpower of directives! Write once, use everywhere! ♻️

Why Bother with Directives?

• Code Reusability: Avoid repeating the same DOM manipulation logic in multiple components.
• Separation of Concerns: Keep your components focused on data and logic, leaving DOM manipulation to directives.
• Abstraction: Create higher-level abstractions to simplify complex UI interactions.
• Enhanced Readability: Make your templates cleaner and easier to understand.

Types of Directives: The Directive Family

Angular offers three main types of directives, each with its own unique purpose:

Directive Type	Purpose	Use Cases	Example
Component Directives	Directives with a template. They are the most common type and are essentially components! They control a portion of the view. They have their own lifecycle hooks and data binding capabilities. Think of them as mini-applications within your application. 🏠	Creating reusable UI elements like buttons, cards, forms, etc. Building complex views composed of smaller, independent components. Managing the state and behavior of a specific section of the UI.	<app-my-component></app-my-component>
Attribute Directives	Directives that change the appearance or behavior of an existing element. They’re like makeup artists for your HTML elements. 💄 They listen to events, modify attributes, and apply styles. These directives are often used to add interactivity, styling, or validation to elements.	Adding conditional styling based on data. Validating form inputs. Creating custom tooltips. Applying custom behaviors like drag-and-drop.	<div appHighlight></div> (Highlights the div)
Structural Directives	Directives that change the DOM layout by adding, removing, or replacing elements. They’re like architects, reshaping the structure of your HTML. 🏗️ They usually start with an asterisk (*). These directives are used to control the flow of elements based on conditions or data.	Conditionally displaying elements based on a boolean value. Iterating over a list of items and rendering them in the DOM. Hiding or showing sections of the UI based on user roles.	<div *ngIf="condition"></div> (Only shows the div if ‘condition’ is true) <li *ngFor="let item of items">{{item.name}}</li> (Loops through the items array)

Important Note: Components are directives, but not all directives are components. It’s like the animal kingdom: all lions are cats, but not all cats are lions. 🦁🐈

Let’s Get Our Hands Dirty: Creating a Custom Attribute Directive

We’ll start with the easiest type: attribute directives. Let’s create a directive that highlights an element when the mouse hovers over it. We’ll call it appHighlight.

Step 1: Generate the Directive

Open your terminal and navigate to your Angular project directory. Run the following command:

ng generate directive highlight

This will create two files: src/app/highlight.directive.ts and src/app/highlight.directive.spec.ts (for testing). We’ll focus on the .ts file for now.

Step 2: The Code (Highlight.directive.ts)

import { Directive, ElementRef, HostListener, Renderer2 } from '@angular/core';

@Directive({
  selector: '[appHighlight]' // This is how we use the directive in HTML: <element appHighlight>
})
export class HighlightDirective {

  constructor(private el: ElementRef, private renderer: Renderer2) {
    // el: Provides access to the host element (the element where the directive is applied).
    // renderer: Provides a platform-agnostic way to manipulate the DOM.  Safer than direct DOM manipulation.
  }

  @HostListener('mouseenter') onMouseEnter() {
    this.highlight('yellow'); // Call our highlighting function on mouseenter
  }

  @HostListener('mouseleave') onMouseLeave() {
    this.highlight(null); // Remove the highlight on mouseleave
  }

  private highlight(color: string | null) {
    this.renderer.setStyle(this.el.nativeElement, 'backgroundColor', color);
  }
}

Explanation:

• @Directive({ selector: '[appHighlight]' }): This is the directive’s metadata.
  • selector: '[appHighlight]' means we can apply this directive to any element by adding the attribute appHighlight. The square brackets [] indicate that it’s an attribute directive.
• ElementRef: A reference to the host element (the element where the directive is applied). We use it to access the element’s properties.
• Renderer2: Angular’s preferred way to manipulate the DOM. It provides a layer of abstraction, making your code more portable and secure. Avoid directly accessing nativeElement as much as possible.
• @HostListener('mouseenter'): Decorates the onMouseEnter method, making it execute whenever the mouseenter event is triggered on the host element. In simpler terms, it listens for when the mouse hovers over the element.
• @HostListener('mouseleave'): Similarly, listens for the mouseleave event (when the mouse moves off the element).
• highlight(color: string | null): This private method sets the background color of the host element using the Renderer2. If color is null, it removes the background color.

Step 3: Import and Declare the Directive

Make sure your HighlightDirective is declared in your app.module.ts (or the module where you want to use it).

import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';

import { AppComponent } from './app.component';
import { HighlightDirective } from './highlight.directive'; // Import the directive

@NgModule({
  declarations: [
    AppComponent,
    HighlightDirective // Declare the directive
  ],
  imports: [
    BrowserModule
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule { }

Step 4: Use the Directive in Your Template (app.component.html)

<h1>My Amazing App</h1>

<p appHighlight>Hover over me!</p>

<button appHighlight>Click me!</button>

<div appHighlight style="padding: 20px; border: 1px solid black;">
  This is a highlighted div.
</div>

Step 5: Run Your App

ng serve

Now, when you hover over the paragraph, button, and div, they should turn yellow! 🎉

Passing Data to Directives: Making Them Dynamic

Our appHighlight directive is cool, but it always highlights with yellow. Let’s make it more flexible by allowing us to specify the highlight color.

Step 1: Modify the Directive (Highlight.directive.ts)

import { Directive, ElementRef, HostListener, Renderer2, Input } from '@angular/core';

@Directive({
  selector: '[appHighlight]'
})
export class HighlightDirective {

  @Input('appHighlight') highlightColor: string; // Allow passing the color as appHighlight="color"
  //OR
  //@Input() highlightColor: string; //Allow passing the color as highlightColor="color"

  constructor(private el: ElementRef, private renderer: Renderer2) { }

  @HostListener('mouseenter') onMouseEnter() {
    this.highlight(this.highlightColor || 'yellow'); // Use the input color or default to yellow
  }

  @HostListener('mouseleave') onMouseLeave() {
    this.highlight(null);
  }

  private highlight(color: string | null) {
    this.renderer.setStyle(this.el.nativeElement, 'backgroundColor', color);
  }
}

Explanation:

• @Input('appHighlight') highlightColor: string;: This is the key! The @Input() decorator allows us to pass data into the directive from the template.
  • 'appHighlight' is the name of the input binding. When we use the directive, we can set the appHighlight attribute to a value, and that value will be assigned to the highlightColor property within the directive.
  • If we use @Input() highlightColor: string;, then the input binding will be highlightColor and the color will be passed via the attribute highlightColor="color".
• this.highlight(this.highlightColor || 'yellow');: We use the highlightColor property in the onMouseEnter method. If highlightColor is not provided (is null or undefined), it defaults to 'yellow'.

Step 2: Use the Directive with Data (app.component.html)

<h1>My Amazing App</h1>

<p appHighlight="lightgreen">Hover over me!</p>

<button appHighlight="lightblue">Click me!</button>

<div appHighlight="orange" style="padding: 20px; border: 1px solid black;">
  This is an highlighted div with a custom color.
</div>

Now you can specify the highlight color for each element! Pretty neat, huh? 😎

Structural Directives: Reshaping the DOM (The Real Magic!)

Let’s move on to the more powerful (and slightly more complex) structural directives. We’ll create a directive called appUnless that works opposite to *ngIf. It will only display the element if the condition is false.

Step 1: Generate the Directive

ng generate directive unless

Step 2: The Code (Unless.directive.ts)

import { Directive, Input, TemplateRef, ViewContainerRef } from '@angular/core';

@Directive({
  selector: '[appUnless]'
})
export class UnlessDirective {

  private hasView = false;

  constructor(
    private templateRef: TemplateRef<any>, // Represents the embedded template (the content inside the element)
    private viewContainer: ViewContainerRef // Provides access to the container where we can insert or remove views (elements)
  ) { }

  @Input() set appUnless(condition: boolean) {
    if (!condition && !this.hasView) {
      this.viewContainer.createEmbeddedView(this.templateRef);
      this.hasView = true;
    } else if (condition && this.hasView) {
      this.viewContainer.clear();
      this.hasView = false;
    }
  }
}

Explanation:

• TemplateRef: A reference to the template inside the element where the directive is applied. It’s like a blueprint for the content we want to render.
• ViewContainerRef: A reference to the container where we can insert or remove views (elements). It’s like a stage where we can add or remove actors.
• @Input() set appUnless(condition: boolean): This is a setter for the appUnless input property. This allows us to use the directive like this: *appUnless="condition". The asterisk (*) is crucial for structural directives.
  • When the condition changes, the setter is called.
  • If the condition is false and we haven’t created the view yet (!this.hasView), we create an embedded view using this.viewContainer.createEmbeddedView(this.templateRef). This inserts the content into the DOM.
  • If the condition is true and we have created the view (this.hasView), we clear the view container using this.viewContainer.clear(). This removes the content from the DOM.

Step 3: Import and Declare the Directive (app.module.ts)

Make sure you import and declare UnlessDirective in your module, just like you did with HighlightDirective.

Step 4: Use the Directive (app.component.html)

<h1>My Amazing App</h1>

<p *appUnless="isLoggedIn">You are not logged in!</p>

<button (click)="isLoggedIn = !isLoggedIn">Toggle Login</button>

Step 5: Add a Property to Your Component (app.component.ts)

import { Component } from '@angular/core';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css']
})
export class AppComponent {
  isLoggedIn = false; // Initial state: not logged in
}

Now, the paragraph "You are not logged in!" will only be displayed if isLoggedIn is false. Clicking the "Toggle Login" button will switch the value of isLoggedIn, and the paragraph will appear or disappear accordingly. Magic! 🎩🐇

Directive Communication: Passing Data Back and Forth

Sometimes, you need your directives to communicate with the components that use them. You can achieve this using @Output() and custom events.

Let’s modify our appHighlight directive to emit an event when the mouse enters or leaves the element.

Step 1: Modify the Directive (Highlight.directive.ts)

import { Directive, ElementRef, HostListener, Renderer2, Input, Output, EventEmitter } from '@angular/core';

@Directive({
  selector: '[appHighlight]'
})
export class HighlightDirective {

  @Input('appHighlight') highlightColor: string;

  @Output() highlightChange = new EventEmitter<boolean>(); // Create an EventEmitter

  constructor(private el: ElementRef, private renderer: Renderer2) { }

  @HostListener('mouseenter') onMouseEnter() {
    this.highlight(this.highlightColor || 'yellow');
    this.highlightChange.emit(true); // Emit an event when highlighted
  }

  @HostListener('mouseleave') onMouseLeave() {
    this.highlight(null);
    this.highlightChange.emit(false); // Emit an event when un-highlighted
  }

  private highlight(color: string | null) {
    this.renderer.setStyle(this.el.nativeElement, 'backgroundColor', color);
  }
}

Explanation:

• @Output() highlightChange = new EventEmitter<boolean>();: This creates an EventEmitter that will emit a boolean value (true when highlighted, false when un-highlighted).
• this.highlightChange.emit(true);: We emit the true value when the mouse enters, signaling that the element is now highlighted.
• this.highlightChange.emit(false);: We emit the false value when the mouse leaves, signaling that the element is no longer highlighted.

Step 2: Use the Directive and Listen for the Event (app.component.html)

<h1>My Amazing App</h1>

<p appHighlight="lightgreen" (highlightChange)="onHighlightChange($event)">
  Hover over me!  Highlighted: {{ isHighlighted }}
</p>

Step 3: Add a Method to Your Component (app.component.ts)

import { Component } from '@angular/core';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css']
})
export class AppComponent {
  isLoggedIn = false;
  isHighlighted = false; // Add a property to track highlight state

  onHighlightChange(isHighlighted: boolean) {
    this.isHighlighted = isHighlighted; // Update the component's property
  }
}

Now, when you hover over the paragraph, the isHighlighted property in your component will be updated, and the text "Highlighted: true" or "Highlighted: false" will be displayed accordingly. We’ve successfully created a two-way communication channel between the directive and the component! 📡

Best Practices and Common Pitfalls

• Use Renderer2 for DOM manipulation: It’s safer and more portable than directly accessing nativeElement.
• Keep directives focused: A directive should have a single, well-defined purpose.
• Avoid excessive DOM manipulation: Frequent DOM updates can impact performance.
• Use lifecycle hooks wisely: Understand when to use OnInit, AfterViewInit, etc.
• Test your directives: Write unit tests to ensure they behave as expected.
• Don’t over-engineer: Sometimes, a simple component is better than a complex directive.
• Be mindful of memory leaks: Unsubscribe from observables and detach event listeners when the directive is destroyed.

Conclusion

Congratulations, class! You’ve taken your first steps into the fascinating world of custom directives! You’ve learned how to create attribute and structural directives, pass data to them, and communicate back to your components. Now go forth and build amazing, reusable DOM manipulation tools! 🚀

Homework:

1. Create a custom directive that adds a tooltip to an element on hover.
2. Create a structural directive that displays a loading spinner while data is being fetched.

And remember, with great directives comes great responsibility! 😉