docs(external-router): clarify README and getting started guides #4034
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,39 +1,41 @@ | ||
| # Magento | ||
|
|
||
| This guide provides instructions on how to use various Magento drivers with `@daffodil/external-router`. | ||
|
|
||
| ## Installation | ||
|
|
||
| ```bash | ||
| 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+ | `provideDaffExternalRouterMagentoDriver` | `@daffodil/external-router/driver/magento/2.4.3` | Yes | | ||
|
|
||
| ## Usage | ||
|
|
||
| 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(), | ||
| ], | ||
| }; | ||
| ``` |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -1,97 +1,153 @@ | ||||||
| # Usage | ||||||
|
|
||||||
| This guide walks you through setting up `@daffodil/external-router` to enable dynamic route resolution from external systems in your Angular application. | ||||||
|
|
||||||
| ## Quick Start | ||||||
|
Member
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
| ### Installation | ||||||
|
|
||||||
| First, install the package: | ||||||
|
Member
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
| ```bash | ||||||
| npm install @daffodil/external-router --save | ||||||
| ``` | ||||||
|
Member
There was a problem hiding this comment. Do we want to add installation instruction for yarn? yarn add @daffodil/external-router |
||||||
|
|
||||||
| ### Basic Setup | ||||||
|
Member
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
| 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: [ | ||||||
| provideClientHydration(), | ||||||
| provideRouter(routes), | ||||||
| provideExternalRouter(), | ||||||
| ], | ||||||
| }; | ||||||
| ``` | ||||||
|
|
||||||
| ### Configure a Driver | ||||||
|
Member
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
| 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: | ||||||
|
Member
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
| ```ts | ||||||
| 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: [ | ||||||
| provideClientHydration(), | ||||||
| provideRouter(routes), | ||||||
| provideExternalRouter(), | ||||||
| provideDaffExternalRouterTestingDriver({ | ||||||
| 'products/shirts': 'PRODUCT_CATEGORY', | ||||||
| 'products/pants': 'PRODUCT_CATEGORY', | ||||||
| 'about-us': 'CMS_PAGE', | ||||||
| contact: 'CMS_PAGE', | ||||||
| }), | ||||||
| ], | ||||||
| }; | ||||||
| ``` | ||||||
|
|
||||||
| ### Define Route Handlers | ||||||
|
Member
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
| 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 = [ | ||||||
| // 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, | ||||||
| }, | ||||||
| ]; | ||||||
| ``` | ||||||
|
|
||||||
| > **Important:** | ||||||
| > | ||||||
| > - Static routes are evaluated first | ||||||
| > - External routes use `path: '**'` with `canMatch` guards | ||||||
| > - Order matters - more specific types should come first | ||||||
|
Member
There was a problem hiding this comment.
Suggested change
|
||||||
| > - Always include a fallback route at the end | ||||||
|
|
||||||
| ### Step 5: Use in Templates | ||||||
|
Member
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
| Navigate to external routes using standard Angular router directives: | ||||||
|
|
||||||
| ```html | ||||||
| <!-- app.component.html --> | ||||||
| <nav> | ||||||
| <a routerLink="/">Home</a> | ||||||
| <a routerLink="/products/shirts">Shirts</a> | ||||||
| <a routerLink="/products/pants">Pants</a> | ||||||
| <a routerLink="/about-us">About</a> | ||||||
| <a routerLink="/contact">Contact</a> | ||||||
| <a routerLink="/cart">Cart</a> | ||||||
| </nav> | ||||||
|
|
||||||
| <router-outlet></router-outlet> | ||||||
| ``` | ||||||
|
|
||||||
| ```ts | ||||||
| // Or navigate programmatically | ||||||
| constructor(private router: Router) {} | ||||||
|
|
||||||
| navigateToProduct() { | ||||||
| this.router.navigate(['/products/shirts']); | ||||||
| } | ||||||
| ``` | ||||||
|
|
||||||
| ## Advanced Configuration | ||||||
|
Member
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
| See the [configuration guide](/libs/external-router/guides/configuration.md) for all available options. | ||||||
|
|
||||||
| ### Production Setup | ||||||
|
Member
There was a problem hiding this comment. Should this be nested within ## Advanced configuration? |
||||||
|
|
||||||
| 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(), | ||||||
| ], | ||||||
| }; | ||||||
| ``` | ||||||
|
|
||||||
| ## Next Steps | ||||||
|
Member
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
| - [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) | ||||||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.