diff --git a/libs/external-router/README.md b/libs/external-router/README.md index e5e1f56841..128c48d250 100644 --- a/libs/external-router/README.md +++ b/libs/external-router/README.md @@ -1,8 +1,23 @@ # @daffodil/external-router +`@daffodil/external-router` extends `@angular/router` and allows you to render routes defined in external systems like Wordpress, Magento, Contentful, etc, as if you had defined the routes statically in your Angular `Routes`. -## Purpose -This package extends `@angular/router` and allows you to render routes defined in external systems like Wordpress, Magento, Contentful, etc, as if you had defined the routes statically in your Angular `Routes`. This is useful when you are trying to generate "user-friendly" routes in external applications and want to resolve them by their "user-friendly" uri, e.g. `sweatshirts` instead of something like `category/6` or `category/sweatshirts`. +## Overview +It's useful when you are trying to generate "user-friendly" routes in external applications and want to resolve them by their "user-friendly" uri, like `sweatshirts`, instead of paths such as `category/6` or `category/sweatshirts`. +## Installation +To install `@daffodil/external-router` and its dependencies, use the following commands in the terminal. + +Install with npm: +```bash +npm install @daffodil/external-router @daffodil/core --save +``` + +Install with yarn: +```bash +yarn add @daffodil/external-router @daffodil/core +``` + +## Usage As an example scenario, you could: 1. Define a page with a "user-friendly" url, e.g. `sweatshirts` in an external service like Magento diff --git a/libs/external-router/guides/configuration.md b/libs/external-router/guides/configuration.md index c7b596ebd0..73539f8860 100644 --- a/libs/external-router/guides/configuration.md +++ b/libs/external-router/guides/configuration.md @@ -1,7 +1,7 @@ # Configuration +You can configure the way that `@daffodil/external-router` works by providing configurations to the `DaffExternalRouterModule`. -The External Router exposes configuration via a configuration object passed to the `forRoot` of the `DaffExternalRouterModule`. - +## Usage An array of `DaffTypeRoutePair`s can be passed as the second argument to `forRoot`. They can also be provided through DI using the `daffProvideRouteResolvableByType` function. ```ts @@ -24,10 +24,10 @@ An array of `DaffTypeRoutePair`s can be passed as the second argument to `forRoo class AppModule {} ``` -## Configuration Options - -For further information beyond the documentation here, see `DaffExternalRouterConfiguration`. +### Configuration options -| Setting | Purpose | Default Value | +| Property | Purpose | Default Value | | -------------------- | ------------------------------------------------------------- | ------------- | | failedResolutionPath | The path to redirect to when external route resolution fails. | '/' | + +For more information, see `DaffExternalRouterConfiguration`. diff --git a/libs/external-router/guides/drivers.md b/libs/external-router/guides/drivers.md index 4a604f4789..a224227512 100644 --- a/libs/external-router/guides/drivers.md +++ b/libs/external-router/guides/drivers.md @@ -1,35 +1,31 @@ # Drivers +`@daffodil/external-router` provides an interface along with a few pre-fabricated drivers for you to simply drop into your app and get started with external route resolution. -The External Router package provides an interface along with a few pre-fabricated drivers for you to simply drop into your app and get started with external route resolution. - -## Available Drivers - -### `@daffodil/external-router/driver/testing` +## Supported drivers +### Testing driver When working with external services, you often want to run tests without depending on the external system's relability or performance. As you write tests for features that depend upon the `@daffodil/external-router/driver` you will find yourself looking for a simple way to meet the `DaffExternalRouterDriverInterface` interface requirements without over-complicating your tests. In these scenarios, having a testing driver that emulates the behavior of an external service is extremely useful. The `DaffExternalRouterTestingDriver` is well-suited for these purposes. -The `DaffExternalRouterTestingDriver` of the `@daffodil/external-router/driver/testing` is useful for Unit Tests, Integration Tests, and simple Acceptance Tests where you don't want to depend on an external service over HTTP. The driver is intended to be: +The `DaffExternalRouterTestingDriver` is useful for unit tests, integration tests, and simple acceptance tests where you don't want to depend on an external service over HTTP. +The driver is intended to be: 1. Small 2. Fast 3. Simple -4. Exhibits similar behaviors to how a real external routing service would behave. +4. Exhibit similar behaviors to how a real external routing service would behave #### Using the testing driver in a spec +You can see a sample usage of the testing driver in the `DaffExternalRouterExistenceGuard` [spec](https://github.com/graycoreio/daffodil/tree/develop/libs/external-router/routing/src/guard). -You can see a sample usage of the testing driver in the `DaffExternalRouterExistenceGuard` [spec](https://github.com/graycoreio/daffodil/tree/develop/libs/external-router/routing/src/guard/existence.guard.spec.ts). - -### `@daffodil/external-router/driver/in-memory` - -Working with a fully featured backend can be cumbersome for rapid frontend development. Daffodil therefore provides `@daffodil/external-router/driver/in-memory` as a way to mimic a real backend without the associated burden. +### In-memory driver +Working with a fully featured backend can be cumbersome for rapid frontend development. To simplify this, `@daffodil/external-router/driver/in-memory` allows you to simulate a real backend without the associated burden. `@daffodil/external-router/driver/in-memory` is thin, deferring most of resolving burden to the app. The app should provide a configuration to `DaffExternalRouterDriverInMemoryModule#forRoot` containing logic for resolving a URL. Daffodil recommends relying on the existing in-memory backends for querying URLs for the entities that the app may attempt to externally resolve. -## Custom Drivers - +## Custom drivers If you would like to provide your own driver, simply write a service that meets the `DaffExternalRouterDriverInterface` of `@daffodil/external-router/driver` and provide it. -### Parsing and Processing URL +### Parsing and processing URL The `url` passed to the `resolve` method can and will have extra info such as query parameters, fragments, and leading slashes. Drivers should take care to parse the passed URL into a form that can be resolved by the platform. Additionally, URLs returned by the driver's `resolve` method should be in a form that satisfies Angular's `Route#path` type. That is, they should not have leading slashes or other info such as query parameters or fragments. diff --git a/libs/external-router/guides/installation.md b/libs/external-router/guides/installation.md deleted file mode 100644 index 63848a2b13..0000000000 --- a/libs/external-router/guides/installation.md +++ /dev/null @@ -1,7 +0,0 @@ -# Installation - -```bash -npm install @daffodil/core @daffodil/external-router --save -``` - -Refer to the usage guides (TODO) for information on how to use `@daffodil/external-router`.