Skip to content

Docs: Alias

Jump to bottom
ng-druid edited this page Aug 8, 2025 · 1 revision

Documentation for Angular Alias Library

Table of Contents

  1. Introduction
  2. Installation
  3. Overview
  4. Key Concepts
    • Alias Plugins
    • Loading and Matching Strategies
    • Routing and Redirection
  5. Core Components
    • AliasModule
  6. Key Services
    • AliasPluginManager
  7. Guards
    • CatchAllGuard
  8. Usage
    • Defining Alias Plugins
    • Managing Routes Dynamically
    • Integrating the Catch-All Guard
  9. API Reference
  10. Examples
  11. Testing

1. Introduction

The Angular Alias Library provides a mechanism for dynamically resolving routes, managing plugins tied to routing strategies, and redirecting users based on custom logic. It is designed to facilitate complex routing workflows and integration with plugin-based architecture.

2. Installation

Install the library along with its dependencies:

npm install @rollthecloudinc/plugin @rollthecloudinc/utils

Ensure the library is added to your project and properly configured in your Angular application.

3. Overview

The Alias Library enables dynamic routing and plugin-based redirection logic in Angular applications. At its core, it defines AliasPlugin objects which load and match routing strategies dynamically.

Features:

  • Alias Plugins: Define custom plugins for routing and redirection logic.
  • Dynamic Routing: Resolved based on plugin criteria.
  • Routing Guards: Control access and redirection using custom logic.
  • Catch-All Router Component: A versatile component for handling non-specific paths.

4. Key Concepts

4.1 Alias Plugins

An AliasPlugin is the core construct for defining customizable routing strategies. Each plugin can implement loading and matching strategies to define route behavior.

Key Plugin Properties:

  • loadingStrategy: Defines the logic for loading plugin-specific resources.
  • matchingStrategy: Specifies how the plugin evaluates and matches routes dynamically.
  • redirectHandler: Implements redirection logic to intercept and alter navigation paths.

Example:

const myAliasPlugin: AliasPlugin<string> = new AliasPlugin<string>({
  loadingStrategy: {
    load: () => of(true),
    isLoaded: () => true
  },
  matchingStrategy: {
    match: (state) => of(state.url.includes('my-route'))
  },
  redirectHandler: {
    redirect: (route, state) => console.log('Redirecting...', state.url)
  }
});

4.2 Loading and Matching Strategies

The library introduces AliasLoadingStrategy and AliasMatchingStrategy interfaces:

  • Loading Strategy: Defines how resources or plugin settings are loaded.

    • load(): Observable<boolean>: Observable that resolves loading status.
    • isLoaded(): boolean: Indicates if the resources are fully loaded.

  • Matching Strategy: Determines whether a plugin matches a given route.

    • match(state: RouterStateSnapshot): Observable<boolean>: Evaluates and returns if the plugin matches the current route state.

4.3 Routing and Redirection

The Alias Library integrates Angular Router by analyzing states through AliasPlugin. The redirection workflow is customizable using the AliasRedirectHandler interface.

Key Method in Redirect Handler:

  • redirect(route: ActivatedRouteSnapshot, state: RouterStateSnapshot): void: Implements custom redirection based on route and state.

5. Core Components

AliasModule

The AliasModule is the primary module exported by the library. This module declares and encapsulates all necessary components, guards, and services required for routing and alias management.

Contains:

  • CatchAllRouterComponent for handling unmatched routes.
  • Routing definitions for wildcard paths (path: **).

6. Key Services

AliasPluginManager

The AliasPluginManager service manages the registration and retrieval of AliasPlugin instances. It extends the BasePluginManager for dynamic configuration of alias-related plugins.

Responsibilities:

  • Handles plugin definitions (PluginDef).
  • Dynamically loads modules required by alias plugins.
  • Provides APIs to retrieve loaded plugins and configurations.

Example:

constructor(private aliasPluginManager: AliasPluginManager) {}

ngOnInit() {
  this.aliasPluginManager.pluginDef().subscribe((pluginDef) => {
    console.log('Alias Plugin Definition:', pluginDef.name);
  });
}

7. Guards

CatchAllGuard

The CatchAllGuard ensures that unmatched routes (**) are intercepted and handled dynamically using registered AliasPlugins. It evaluates active plugins and redirects users based on matching strategies.

Flow:

  1. Plugins are loaded using the loading strategy.
  2. Each plugin evaluates the route using the matching strategy.
  3. Matching plugins handle redirection, or default navigation is allowed.

8. Usage

8.1 Defining Alias Plugins

Create custom plugins by extending the AliasPlugin class and implementing loading/matching strategies.

Example:

const examplePlugin = new AliasPlugin<string>({
  loadingStrategy: {
    load: () => of(true),
    isLoaded: () => true,
  },
  matchingStrategy: {
    match: (state: RouterStateSnapshot) => of(state.url.includes('example')),
  },
  redirectHandler: {
    redirect: (route, state) => console.log(`Redirecting ${state.url}`),
  },
});

this.aliasPluginManager.register(examplePlugin);

8.2 Managing Routes Dynamically

Using CatchAllGuard, you can handle unmatched routes and dynamically evaluate them against active plugins.

Routing Example:

const routes = [
  { path: '**', component: CatchAllRouterComponent, canActivate: [CatchAllGuard] }
];

@NgModule({
  imports: [RouterModule.forRoot(routes)],
  declarations: [CatchAllRouterComponent],
  providers: [CatchAllGuard],
})
export class AppRoutingModule {}

8.3 Integrating Catch-All Guard

Apply the CatchAllGuard to wildcard routes (**), allowing plugins to dynamically resolve navigation paths based on state.

9. API Reference

Classes and Interfaces

  1. AliasPlugin

    • loadingStrategy: AliasLoadingStrategy
    • matchingStrategy: AliasMatchingStrategy
    • redirectHandler: AliasRedirectHandler

  2. AliasPluginManager

    • pluginDef(): Returns plugin definitions.
    • Extends BasePluginManager.

  3. CatchAllGuard

    • Method: canActivate.

10. Examples

Example 1: Dynamic Plugin Registration

this.aliasPluginManager.register(
  new AliasPlugin<string>({
    loadingStrategy: { load: () => of(true), isLoaded: () => true },
    matchingStrategy: { match: (state) => of(state.url.includes('alias')) },
    redirectHandler: { redirect: (route, state) => console.log('Redirecting:', state.url) },
  })
);

Example 2: Using CatchAllGuard in Routing

{
  path: '**',
  component: CatchAllRouterComponent,
  canActivate: [CatchAllGuard],
}

11. Testing

Example: Testing Catch-All Guard

describe('CatchAllGuard', () => {
  let guard: CatchAllGuard;

  it('should return true for non-matching routes', async () => {
    const state = { url: '/not-handled' } as RouterStateSnapshot;
    const result = await guard.canActivate(null, state);
    expect(result).toBe(true);
  });
});

Conclusion

The Angular Alias Library provides a powerful system for dynamic route management using plugins, guards, and redirection strategies. It streamlines routing workflows in applications requiring runtime configurability and modularity.

For questions or contributions, feel free to reach out!

Clone this wiki locally