From f3ab97a4443686dedef2d3c1da3cba4bc6554912 Mon Sep 17 00:00:00 2001 From: Arman Ozak Date: Wed, 23 Sep 2020 21:25:16 +0300 Subject: [PATCH 1/4] docs: describe how ABP Angular feature libs work --- docs/en/UI/Angular/Environment.md | 2 +- docs/en/UI/Angular/Feature-Libraries.md | 98 +++++++++++++++++++++++++ 2 files changed, 99 insertions(+), 1 deletion(-) create mode 100644 docs/en/UI/Angular/Feature-Libraries.md diff --git a/docs/en/UI/Angular/Environment.md b/docs/en/UI/Angular/Environment.md index 67fe4eb3151..0cd946079fb 100644 --- a/docs/en/UI/Angular/Environment.md +++ b/docs/en/UI/Angular/Environment.md @@ -105,4 +105,4 @@ export interface RemoteEnv { ## What's Next? -* [Service Proxies](./Service-Proxies.md) +* [Anatomy of a Feature Library](./Feature-Libraries.md) diff --git a/docs/en/UI/Angular/Feature-Libraries.md b/docs/en/UI/Angular/Feature-Libraries.md new file mode 100644 index 00000000000..2ef681663a6 --- /dev/null +++ b/docs/en/UI/Angular/Feature-Libraries.md @@ -0,0 +1,98 @@ +# Anatomy of a Feature Library + +ABP has an ever-growing number of feature modules and [introducing a new one](../../Module-Development-Basics.md) is always possible. When the UI is Angular, these features have modular Angular libraries accompanying them. + +## Feature Library Content + +Each library has at least two modules: + +1. The main module contains all components, services, types, enums, etc. to deliver the required UI when the feature is loaded. From here on, we will refer to these modules as **"feature module"**. +2. There is also a **"config module"** per library which helps us configure applications to run these modules or make them accessible. + +## How to Add a Feature Library to Your Project + + + +Manual consumption of a feature library has three steps: + +### 1. Install the Library + +Feature libraries are usually published as an npm package. If a library you want to use does not exist in your project, you may install it via the following command: + +```shell +yarn add @my-company-name/my-project-name +``` + +...or... + +```shell +npm install @my-company-name/my-project-name +``` + +The `my-company-name` and `my-project-name` parts are going to change according to the package you want to use. For example, if we want to install the ABP Identity module, the package installation will be as seen below: + +```shell +yarn add @abp/ng.identity +``` + +> Identity is used just as an example. If you have initiated your project with ABP CLI or ABP Suite, the identity library will already be installed and configured in your project. + +### 2. Import the Config Module + +As of ABP v3.0, every lazy-loaded module has a config module available via a secondary entry point on the same package. Importing them in your root module looks like this: + +```js +import { IdentityConfigModule } from "@abp/ng.identity/config"; + +@NgModule({ + imports: [ + // other imports + IdentityConfigModule.forRoot(), + ], + // providers, declarations, and bootstrap +}) +export class AppModule {} +``` + +We need the config modules for actions required before feature modules are loaded (lazily). For example, the above import configures the menu to display links to identity pages. + +Furthermore, depending on the library, the `.forRoot` static method may receive some options that configure how the feature works. + +### 3. Import the Feature Module + +Finally, the feature module should be [loaded lazily via Angular router](https://angular.io/guide/lazy-loading-ngmodules). If you open the `/src/app/app-routing.module.ts` file, you should see `IdentityModule` is loaded exactly as follows: + +```js +import { NgModule } from "@angular/core"; +import { RouterModule, Routes } from "@angular/router"; + +const routes: Routes = [ + // other routes + { + path: "identity", + loadChildren: () => + import("@abp/ng.identity").then((m) => m.IdentityModule.forLazy()), + }, + // other routes +]; + +@NgModule({ + imports: [RouterModule.forRoot(routes)], + exports: [RouterModule], +}) +export class AppRoutingModule {} +``` + +When you load the identity feature like this, the "Users" page, for example, will have a route path of `/identity/users`. [1](#f-modify-route) + +Depending on the library, the `.forLazy` static method may also receive some options that configure how the feature works. + +--- + +1 _Libraries expect to work at a predefined path. Please check [how to patch a navigation element](./Modifying-the-Menu.md#how-to-patch-or-remove-a-navigation-element), if you want to use a different path from the default one (e.g. '/identity')._ [↩](#a-modify-route) + +--- + +## What's Next? + +- [Service Proxies](./Service-Proxies.md) From 4d73ef56979b048e4bdebad8700cd00df0467e41 Mon Sep 17 00:00:00 2001 From: Arman Ozak Date: Wed, 23 Sep 2020 21:25:38 +0300 Subject: [PATCH 2/4] docs: add feature libs document to navigation --- docs/en/docs-nav.json | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/en/docs-nav.json b/docs/en/docs-nav.json index a70ddea62cc..68107b666a4 100644 --- a/docs/en/docs-nav.json +++ b/docs/en/docs-nav.json @@ -442,6 +442,10 @@ "text": "Environment Variables", "path": "UI/Angular/Environment.md" }, + { + "text": "Anatomy of a Feature Library", + "path": "UI/Angular/Feature-Libraries.md" + }, { "text": "Service Proxies", "path": "UI/Angular/Service-Proxies.md" From 1d3e894020fcf8d51bbc68d5d633d075ddbeee51 Mon Sep 17 00:00:00 2001 From: Arman Ozak Date: Thu, 24 Sep 2020 09:05:03 +0300 Subject: [PATCH 3/4] docs: change title for feature libraries --- docs/en/UI/Angular/Environment.md | 2 +- docs/en/UI/Angular/Feature-Libraries.md | 2 +- docs/en/docs-nav.json | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/en/UI/Angular/Environment.md b/docs/en/UI/Angular/Environment.md index 0cd946079fb..ab2a99c8d8a 100644 --- a/docs/en/UI/Angular/Environment.md +++ b/docs/en/UI/Angular/Environment.md @@ -105,4 +105,4 @@ export interface RemoteEnv { ## What's Next? -* [Anatomy of a Feature Library](./Feature-Libraries.md) +- [About Feature Libraries](./Feature-Libraries.md) diff --git a/docs/en/UI/Angular/Feature-Libraries.md b/docs/en/UI/Angular/Feature-Libraries.md index 2ef681663a6..b2e5c759ec6 100644 --- a/docs/en/UI/Angular/Feature-Libraries.md +++ b/docs/en/UI/Angular/Feature-Libraries.md @@ -1,4 +1,4 @@ -# Anatomy of a Feature Library +# About Feature Libraries ABP has an ever-growing number of feature modules and [introducing a new one](../../Module-Development-Basics.md) is always possible. When the UI is Angular, these features have modular Angular libraries accompanying them. diff --git a/docs/en/docs-nav.json b/docs/en/docs-nav.json index 68107b666a4..9116fca5a0d 100644 --- a/docs/en/docs-nav.json +++ b/docs/en/docs-nav.json @@ -443,7 +443,7 @@ "path": "UI/Angular/Environment.md" }, { - "text": "Anatomy of a Feature Library", + "text": "About Feature Libraries", "path": "UI/Angular/Feature-Libraries.md" }, { From 3b65d8a8b97d4d49600fbaa22f3198c4985a8e1a Mon Sep 17 00:00:00 2001 From: Arman Ozak Date: Thu, 24 Sep 2020 11:50:06 +0300 Subject: [PATCH 4/4] docs: use setup instead of consumption --- docs/en/UI/Angular/Feature-Libraries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/UI/Angular/Feature-Libraries.md b/docs/en/UI/Angular/Feature-Libraries.md index b2e5c759ec6..937bae7245c 100644 --- a/docs/en/UI/Angular/Feature-Libraries.md +++ b/docs/en/UI/Angular/Feature-Libraries.md @@ -13,7 +13,7 @@ Each library has at least two modules: -Manual consumption of a feature library has three steps: +The manual setup of a feature library has three steps: ### 1. Install the Library