diff --git a/libs/external-router/README.md b/libs/external-router/README.md index 941f90f2da..defd85ef81 100644 --- a/libs/external-router/README.md +++ b/libs/external-router/README.md @@ -21,11 +21,23 @@ Install with yarn: yarn add @daffodil/external-router ``` +## Getting Started + +See the [usage guide](/libs/external-router/guides/usage.md) for a step-by-step walkthrough of setting up external routing in your application. + +## Configuration + +Configure the external router behavior with custom options. See the [configuration guide](/libs/external-router/guides/configuration.md) for available options. + ## Drivers We provide a driver interface along with a few pre-fabricated drivers for you to simply drop into your app and get started with external route resolution. -- [Customize your own driver](/libs/external-router/guides/drivers/custom.md) -- [In-Memory](/libs/external-router/guides/drivers/in-memory.md) -- [Magento](/libs/external-router/guides/drivers/magento.md) -- [Testing](/libs/external-router/guides/drivers/testing.md) +- [Custom Driver](/libs/external-router/guides/drivers/custom.md) - Create your own driver for any external system +- [In-Memory Driver](/libs/external-router/guides/drivers/in-memory.md) - Store routes in memory for development +- [Magento Driver](/libs/external-router/guides/drivers/magento.md) - Integration with Magento 2 URL resolution +- [Testing Driver](/libs/external-router/guides/drivers/testing.md) - Mock driver for unit testing + +## Testing + +Learn how to test your external router configuration and route guards. See the [testing guide](/libs/external-router/guides/testing.md) for examples and best practices. diff --git a/libs/external-router/guides/drivers/magento.md b/libs/external-router/guides/drivers/magento.md index d5c0221623..08b6e13465 100644 --- a/libs/external-router/guides/drivers/magento.md +++ b/libs/external-router/guides/drivers/magento.md @@ -1,39 +1,41 @@ # Magento + This guide provides instructions on how to use various Magento drivers with `@daffodil/external-router`. ## Installation -Like all Magento drivers, you will need to install [Apollo GraphQl](https://the-guild.dev/graphql/apollo-angular/docs). ```bash -npm install --save @daffodil/driver apollo-angular +npm install @daffodil/external-router --save ``` ## Getting started + To use the Magento drivers, you need to import and configure the appropriate modules and services in your Angular application. Magento's GraphQl API has changed with its various versions, with the most recent versions of Magento supporting the `routes` GraphQl query. As such, most recent versions of Magento should use the driver version which first introduced support for this: `DaffExternalRouterDriverMagentoModule` from `@daffodil/external-router/driver/magento/2.4.3`. -| Magento Version | Module | Package | SEO Data Support | -| --------------- | --------------------------------------- | ------------------------------------------------ | ---------------- | -| v2.4.1 | `DaffExternalRouterDriverMagentoModule` | `@daffodil/external-router/driver/magento/2.4.1` | No | -| v2.4.2 | `DaffExternalRouterDriverMagentoModule` | `@daffodil/external-router/driver/magento/2.4.2` | No | -| v2.4.3+ | `DaffExternalRouterDriverMagentoModule` | `@daffodil/external-router/driver/magento/2.4.3` | Yes | +| Magento Version | Module | Package | SEO Data Support | +| --------------- | ---------------------------------------- | ------------------------------------------------ | ---------------- | +| v2.4.1 | `DaffExternalRouterDriverMagentoModule` | `@daffodil/external-router/driver/magento/2.4.1` | No | +| v2.4.2 | `DaffExternalRouterDriverMagentoModule` | `@daffodil/external-router/driver/magento/2.4.2` | No | +| v2.4.3+ | `provideDaffExternalRouterMagentoDriver` | `@daffodil/external-router/driver/magento/2.4.3` | Yes | ## Usage -To use the Magento driver for external router: + +To use the Magento driver for external router with the latest version of Magento: ```ts import { ApplicationConfig, importProvidersFrom } from '@angular/core'; import { provideDaffExternalRouterMagentoDriver } from '@daffodil/external-router/driver/magento/2.4.3'; export const appConfig: ApplicationConfig = { - providers: [ - provideRouter(routes), - provideClientHydration(), - provideExternalRouter(), - provideDaffExternalRouterMagentoDriver(), - ], + providers: [ + provideRouter(routes), + provideClientHydration(), + provideExternalRouter(), + provideDaffExternalRouterMagentoDriver(), + ], }; ``` diff --git a/libs/external-router/guides/usage.md b/libs/external-router/guides/usage.md index 94b684cbce..d4acdd2560 100644 --- a/libs/external-router/guides/usage.md +++ b/libs/external-router/guides/usage.md @@ -1,97 +1,153 @@ # Usage -## Getting started -Add `provideExternalRouter` to the `providers` of your `appConfig` or `AppModule`. +This guide walks you through setting up `@daffodil/external-router` to enable dynamic route resolution from external systems in your Angular application. + +## Quick Start + +### Installation + +First, install the package: + +```bash +npm install @daffodil/external-router --save +``` + +### Basic Setup + +Add `provideExternalRouter` to your application configuration: ```ts import { ApplicationConfig } from '@angular/core'; +import { provideRouter } from '@angular/router'; import { provideExternalRouter } from '@daffodil/external-router'; export const appConfig: ApplicationConfig = { - providers: [ - provideRouter(routes), - provideClientHydration(), - provideExternalRouter(), - ], + providers: [ + provideClientHydration(), + provideRouter(routes), + provideExternalRouter(), + ], }; ``` -## Configurations +### Configure a Driver -1. Configure your [driver of choice](/libs/external-router/README.md#drivers). This example uses the [testing driver](/libs/external-router/guides/driver/testing.md): +Choose and configure a driver based on your needs. This example uses the testing driver for development, but you should use the driver which matches your platform requirements: ```ts -import { ApplicationConfig, importProvidersFrom } from '@angular/core'; -import { DaffExternalRouterDriverTestingModule } from '@daffodil/external-router/driver/testing'; +import { ApplicationConfig } from '@angular/core'; +import { provideRouter } from '@angular/router'; +import { provideExternalRouter } from '@daffodil/external-router'; +import { provideDaffExternalRouterTestingDriver } from '@daffodil/external-router/driver/testing'; export const appConfig: ApplicationConfig = { - providers: [ - provideRouter(routes), - provideClientHydration(), - provideExternalRouter(), - provideDaffExternalRouterTestingDriver({ - 'test-page': 'TEST_TYPE', - 'other-page': 'OTHER_TYPE', - 'another-page': 'OTHER_TYPE', - }), - ], + providers: [ + provideClientHydration(), + provideRouter(routes), + provideExternalRouter(), + provideDaffExternalRouterTestingDriver({ + 'products/shirts': 'PRODUCT_CATEGORY', + 'products/pants': 'PRODUCT_CATEGORY', + 'about-us': 'CMS_PAGE', + contact: 'CMS_PAGE', + }), + ], }; ``` -2. Configure your routes to use the `daffExternalMatcherTypeGuard`: +### Define Route Handlers + +Configure your Angular routes with `canMatch` to handle different external route types: ```ts import { Routes } from '@angular/router'; - import { daffExternalMatcherTypeGuard } from '@daffodil/external-router/routing'; export const routes: Routes = [ - { - path: '', - pathMatch: 'full', - component: HomeComponent, - }, - { - path: '**', - component: TestComponent, - canMatch: [daffExternalMatcherTypeGuard('TEST_TYPE')], - }, - { - path: '**', - component: OtherTypeComponent, - canMatch: [daffExternalMatcherTypeGuard('OTHER_TYPE')], - }, + // Static routes take precedence + { + path: '', + pathMatch: 'full', + component: HomeComponent, + }, + + // External routes handled by type + { + path: '**', + component: ProductCategoryComponent, + canMatch: [daffExternalMatcherTypeGuard('PRODUCT_CATEGORY')], + }, + { + path: '**', + component: CmsPageComponent, + canMatch: [daffExternalMatcherTypeGuard('CMS_PAGE')], + }, + + // Fallback for unresolved routes + { + path: '**', + component: NotFoundComponent, + }, ]; ``` -> You can use whatever type values you would like, just ensure they match the types set in `provideDaffExternalRouterTestingDriver`. +> **Important:** +> +> - Static routes are evaluated first +> - External routes use `path: '**'` with `canMatch` guards +> - Order matters - more specific types should come first +> - Always include a fallback route at the end -> These components are also just examples, so you can replace them with whatever components you want. +### Step 5: Use in Templates + +Navigate to external routes using standard Angular router directives: + +```html + + -3. Add links to your `AppComponent`: + +``` ```ts -@Component({ - selector: 'app-root', - templateUrl: './app.component.html', - styleUrl: './app.component.scss', - standalone: true, - imports: [ - RouterOutlet, - RouterLink - ], -}) -export class AppComponent {} +// Or navigate programmatically +constructor(private router: Router) {} + +navigateToProduct() { + this.router.navigate(['/products/shirts']); +} ``` -```html - - +## Advanced Configuration + +See the [configuration guide](/libs/external-router/guides/configuration.md) for all available options. + +### Production Setup + +For production environments, you'll typically use a driver that connects to your backend: + +```ts +// Example with Magento +import { provideDaffMagentoExternalRouterDriver } from '@daffodil/external-router/driver/magento'; + +export const appConfig: ApplicationConfig = { + providers: [ + provideRouter(routes), + provideExternalRouter(), + provideDaffMagentoExternalRouterDriver(), + ], +}; ``` -4. Serve your app. You can now navigate to `"/test-page"`, `"/other-page"`, and `"/another-page"` as if it was defined in your Angular routes. +## Next Steps + +- [Configure external router options](/libs/external-router/guides/configuration.md) +- [Create a custom driver](/libs/external-router/guides/drivers/custom.md) +- [Test your configuration](/libs/external-router/guides/testing.md)