From 7fd9c6ab554cd7a0499960b52310b990e2bd62f2 Mon Sep 17 00:00:00 2001 From: bnymncoskuner Date: Thu, 20 Aug 2020 17:06:52 +0300 Subject: [PATCH 1/9] docs: create environment docs for Angular --- docs/en/UI/Angular/Environment.md | 99 +++++++++++++++++++++++++++++ docs/en/UI/Angular/Multi-Tenancy.md | 2 +- docs/en/docs-nav.json | 8 ++- 3 files changed, 106 insertions(+), 3 deletions(-) create mode 100644 docs/en/UI/Angular/Environment.md diff --git a/docs/en/UI/Angular/Environment.md b/docs/en/UI/Angular/Environment.md new file mode 100644 index 00000000000..b1f47ac8643 --- /dev/null +++ b/docs/en/UI/Angular/Environment.md @@ -0,0 +1,99 @@ +# Environment + +Current `Environment` Configuration holds sub config classes. + +```typescript +export interface Environment { + apis: Apis; + application: Application; + hmr?: boolean; + localization?: { defaultResourceName?: string }; + oAuthConfig: AuthConfig; + production: boolean; + remoteEnv?: RemoteEnv; +} +``` + +## Apis + +```typescript +export interface Apis { + [key: string]: ApiConfig; + default: ApiConfig; +} + +export interface ApiConfig { + [key: string]: string; + url: string; +} +``` + +Api config has to have a default config and it may have some additional ones for different modules. +I.e. you may want to connect to different Apis for different modules. + +Take a look at example + +```json +{ + ... + "apis": { + "default": { + "url": "https://localhost:8080", + }, + "AbpIdentity": { + "url": "https://localhost:9090", + } + } +} +``` + +When an api from `AbpIdentity` is called, the request will be sent to `"https://localhost:9090"`. +Everything else will be sent to `"https://localhost:8080"` + +## Application + +```typescript + export interface Application { + name: string; + baseUrl?: string; + logoUrl?: string; +} +``` + +* `name`: Name of the backend Application. It is also used by `logo.component` if `logoUrl` is not provided. +* `logoUrl`: Url of application logo. It is used by `logo.component` +* `baseUrl`: [For detailed information](./Multi-Tenancy.md#domain-tenant-resolver) + +## Localization + +You can read about `Localization` [here in detail](./Localization.md) + +## OAuthConfig + +..... + +## RemoteEnvironment + +To integrate an existing config json into environment, you need to set `remoteEnv` + +```typescript +export type customMergeFn = ( + localEnv: Partial, + remoteEnv: any, +) => Config.Environment; + +export interface RemoteEnv { + url: string; + mergeStrategy: 'deepmerge' | 'overwrite' | customMergeFn; + method?: string; + headers?: ABP.Dictionary; +} +``` + +* `url` *: Required. The url to be used to retrieve environment config +* `mergeStrategy`: Defines how local and remote environment json will be merged + * `deepmerge`: Both local and remote environment json will be merged recursively. If both config has same nested path, remote environment will be prioritized. + * `overwrite`: Remote environment will be used and local environment will be ignored. + * `customMergeFn`: You can also provide your own merge function as shown in the example. It will take two parameters, `localEnv: Partial` and `remoteEnv` and it needs to return a `Config.Environment` object. +* `method`: HTTP method to be used when retrieving environment config. Default: `GET` +* `headers`: If extra headers are needed for the request, it can be set through this field. \ No newline at end of file diff --git a/docs/en/UI/Angular/Multi-Tenancy.md b/docs/en/UI/Angular/Multi-Tenancy.md index fb9fb54f76b..2f768de32a6 100644 --- a/docs/en/UI/Angular/Multi-Tenancy.md +++ b/docs/en/UI/Angular/Multi-Tenancy.md @@ -20,7 +20,7 @@ On the page above, you can; You can switch between existing tenants by using the tenant switching component in the child pages of the `AccountLayoutComponent` (like Login page). Angular UI sends the selected tenant id to the backend as `__tenant` header on each request. -## Domain Tenant Resolver +

Domain Tenant Resolver

Angular UI can get the tenant name from the app running URL. You can determine the current tenant by subdomain (like mytenant1.mydomain.com) or by the whole domain (like mytenant.com). To do this, you need to set the `application.baseUrl` property in the environment: diff --git a/docs/en/docs-nav.json b/docs/en/docs-nav.json index 660f2b1b603..411cced68dc 100644 --- a/docs/en/docs-nav.json +++ b/docs/en/docs-nav.json @@ -219,11 +219,11 @@ "items": [ { "text": "Email Sending System", - "path": "Emailing.md", + "path": "Emailing.md" }, { "text": "MailKit Integration", - "path": "MailKit.md", + "path": "MailKit.md" } ] }, @@ -423,6 +423,10 @@ "text": "Migration Guide v2.x to v3", "path": "UI/Angular/Migration-Guide-v3.md" }, + { + "text": "Environment", + "path": "UI/Angular/Environment.md" + }, { "text": "Service Proxies", "path": "UI/Angular/Service-Proxies.md" From 1bb107bde4443854773c8509cd4d2cd005fdb80c Mon Sep 17 00:00:00 2001 From: bnymncoskuner Date: Fri, 21 Aug 2020 09:02:33 +0300 Subject: [PATCH 2/9] docs: improve environment.md --- docs/en/UI/Angular/Environment.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/en/UI/Angular/Environment.md b/docs/en/UI/Angular/Environment.md index b1f47ac8643..22acc369d94 100644 --- a/docs/en/UI/Angular/Environment.md +++ b/docs/en/UI/Angular/Environment.md @@ -35,7 +35,7 @@ Take a look at example ```json { - ... + // ... "apis": { "default": { "url": "https://localhost:8080", @@ -43,7 +43,8 @@ Take a look at example "AbpIdentity": { "url": "https://localhost:9090", } - } + }, + // ... } ``` @@ -68,9 +69,9 @@ Everything else will be sent to `"https://localhost:8080"` You can read about `Localization` [here in detail](./Localization.md) -## OAuthConfig +## AuthConfig -..... +For authentication, we use [angular-oauth2-oidc](https://github.com/manfredsteyer/angular-oauth2-oidc) ## RemoteEnvironment From 45458342e4fd46e6d51c8761000241bd00d57702 Mon Sep 17 00:00:00 2001 From: bnymncoskuner Date: Fri, 21 Aug 2020 12:17:00 +0300 Subject: [PATCH 3/9] docs: improve environment md --- docs/en/UI/Angular/Environment.md | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/docs/en/UI/Angular/Environment.md b/docs/en/UI/Angular/Environment.md index 22acc369d94..34b7a38370a 100644 --- a/docs/en/UI/Angular/Environment.md +++ b/docs/en/UI/Angular/Environment.md @@ -1,6 +1,8 @@ # Environment -Current `Environment` Configuration holds sub config classes. +Every application needs some ** environment ** variables. In Angular world, this is usually managed by `environment.ts`, `environment.prod.ts` and so on. It is the same for Abp as well. + +Current `Environment` configuration holds sub config classes as follows: ```typescript export interface Environment { @@ -31,7 +33,7 @@ export interface ApiConfig { Api config has to have a default config and it may have some additional ones for different modules. I.e. you may want to connect to different Apis for different modules. -Take a look at example +Take a look at following example ```json { @@ -62,7 +64,7 @@ Everything else will be sent to `"https://localhost:8080"` ``` * `name`: Name of the backend Application. It is also used by `logo.component` if `logoUrl` is not provided. -* `logoUrl`: Url of application logo. It is used by `logo.component` +* `logoUrl`: Url of the application logo. It is used by `logo.component` * `baseUrl`: [For detailed information](./Multi-Tenancy.md#domain-tenant-resolver) ## Localization @@ -71,11 +73,14 @@ You can read about `Localization` [here in detail](./Localization.md) ## AuthConfig -For authentication, we use [angular-oauth2-oidc](https://github.com/manfredsteyer/angular-oauth2-oidc) +For authentication, we use angular-oauth2-oidc. Please check their [docs](https://github.com/manfredsteyer/angular-oauth2-oidc) out ## RemoteEnvironment -To integrate an existing config json into environment, you need to set `remoteEnv` +Some applications need to integrate an existing config into the `environment` used throughout the application. +Abp Framework supports this out of box. + +To integrate an existing config json into the `environment`, you need to set `remoteEnv` ```typescript export type customMergeFn = ( @@ -92,9 +97,9 @@ export interface RemoteEnv { ``` * `url` *: Required. The url to be used to retrieve environment config -* `mergeStrategy`: Defines how local and remote environment json will be merged - * `deepmerge`: Both local and remote environment json will be merged recursively. If both config has same nested path, remote environment will be prioritized. - * `overwrite`: Remote environment will be used and local environment will be ignored. +* `mergeStrategy` *: Required. Defines how the local and the remote `environment` json will be merged + * `deepmerge`: Both local and remote `environment` json will be merged recursively. If both configs have same nested path, the remote `environment` will be prioritized. + * `overwrite`: Remote `environment` will be used and local environment will be ignored. * `customMergeFn`: You can also provide your own merge function as shown in the example. It will take two parameters, `localEnv: Partial` and `remoteEnv` and it needs to return a `Config.Environment` object. * `method`: HTTP method to be used when retrieving environment config. Default: `GET` * `headers`: If extra headers are needed for the request, it can be set through this field. \ No newline at end of file From 6db86830a9c1636b170d939011d82b6662a43928 Mon Sep 17 00:00:00 2001 From: Bunyamin Coskuner Date: Mon, 24 Aug 2020 10:37:34 +0300 Subject: [PATCH 4/9] docs: capitalize ABP Co-authored-by: Mehmet Erim <34455572+mehmet-erim@users.noreply.github.com> --- docs/en/UI/Angular/Environment.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/en/UI/Angular/Environment.md b/docs/en/UI/Angular/Environment.md index 34b7a38370a..cfdfb4cce1b 100644 --- a/docs/en/UI/Angular/Environment.md +++ b/docs/en/UI/Angular/Environment.md @@ -1,6 +1,6 @@ # Environment -Every application needs some ** environment ** variables. In Angular world, this is usually managed by `environment.ts`, `environment.prod.ts` and so on. It is the same for Abp as well. +Every application needs some ** environment ** variables. In Angular world, this is usually managed by `environment.ts`, `environment.prod.ts` and so on. It is the same for ABP as well. Current `Environment` configuration holds sub config classes as follows: @@ -102,4 +102,4 @@ export interface RemoteEnv { * `overwrite`: Remote `environment` will be used and local environment will be ignored. * `customMergeFn`: You can also provide your own merge function as shown in the example. It will take two parameters, `localEnv: Partial` and `remoteEnv` and it needs to return a `Config.Environment` object. * `method`: HTTP method to be used when retrieving environment config. Default: `GET` -* `headers`: If extra headers are needed for the request, it can be set through this field. \ No newline at end of file +* `headers`: If extra headers are needed for the request, it can be set through this field. From b0dbd4e8f1a34e10942f92fa3ea89cec67ca2492 Mon Sep 17 00:00:00 2001 From: Bunyamin Coskuner Date: Mon, 24 Aug 2020 10:38:51 +0300 Subject: [PATCH 5/9] docs: remove hmr and localization fields Co-authored-by: Mehmet Erim <34455572+mehmet-erim@users.noreply.github.com> --- docs/en/UI/Angular/Environment.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/en/UI/Angular/Environment.md b/docs/en/UI/Angular/Environment.md index cfdfb4cce1b..5ffe7b1ba5d 100644 --- a/docs/en/UI/Angular/Environment.md +++ b/docs/en/UI/Angular/Environment.md @@ -8,8 +8,6 @@ Current `Environment` configuration holds sub config classes as follows: export interface Environment { apis: Apis; application: Application; - hmr?: boolean; - localization?: { defaultResourceName?: string }; oAuthConfig: AuthConfig; production: boolean; remoteEnv?: RemoteEnv; From 9e4b2a7335259bf3cc20c795c687be0031adc15d Mon Sep 17 00:00:00 2001 From: Bunyamin Coskuner Date: Mon, 24 Aug 2020 10:39:16 +0300 Subject: [PATCH 6/9] docs: remove localization part Co-authored-by: Mehmet Erim <34455572+mehmet-erim@users.noreply.github.com> --- docs/en/UI/Angular/Environment.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/en/UI/Angular/Environment.md b/docs/en/UI/Angular/Environment.md index 5ffe7b1ba5d..af50e341559 100644 --- a/docs/en/UI/Angular/Environment.md +++ b/docs/en/UI/Angular/Environment.md @@ -65,9 +65,6 @@ Everything else will be sent to `"https://localhost:8080"` * `logoUrl`: Url of the application logo. It is used by `logo.component` * `baseUrl`: [For detailed information](./Multi-Tenancy.md#domain-tenant-resolver) -## Localization - -You can read about `Localization` [here in detail](./Localization.md) ## AuthConfig From 325f13020825f92f5c87e4a19ec0f3a06d1a67c3 Mon Sep 17 00:00:00 2001 From: bnymncoskuner Date: Mon, 24 Aug 2020 15:46:01 +0300 Subject: [PATCH 7/9] docs: update nav between docs --- docs/en/UI/Angular/Environment.md | 8 +++++++- docs/en/UI/Angular/Migration-Guide-v3.md | 2 +- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/en/UI/Angular/Environment.md b/docs/en/UI/Angular/Environment.md index 34b7a38370a..ceacf8f0389 100644 --- a/docs/en/UI/Angular/Environment.md +++ b/docs/en/UI/Angular/Environment.md @@ -102,4 +102,10 @@ export interface RemoteEnv { * `overwrite`: Remote `environment` will be used and local environment will be ignored. * `customMergeFn`: You can also provide your own merge function as shown in the example. It will take two parameters, `localEnv: Partial` and `remoteEnv` and it needs to return a `Config.Environment` object. * `method`: HTTP method to be used when retrieving environment config. Default: `GET` -* `headers`: If extra headers are needed for the request, it can be set through this field. \ No newline at end of file +* `headers`: If extra headers are needed for the request, it can be set through this field. + + +## What's Next? + +* [Service Proxies](./Service-Proxies.md) + diff --git a/docs/en/UI/Angular/Migration-Guide-v3.md b/docs/en/UI/Angular/Migration-Guide-v3.md index 725a04c0886..810d830ca37 100644 --- a/docs/en/UI/Angular/Migration-Guide-v3.md +++ b/docs/en/UI/Angular/Migration-Guide-v3.md @@ -473,5 +473,5 @@ Some interfaces have long been marked as deprecated and now they are removed. ## What's Next? -* [Service Proxies](./Service-Proxies.md) +* [Environment](./Environment.md) From c61d273c5b62cdf24dfe6442f41d950a9b09aece Mon Sep 17 00:00:00 2001 From: bnymncoskuner Date: Tue, 25 Aug 2020 18:28:05 +0300 Subject: [PATCH 8/9] docs: update ApiConfig with rootNamespace --- docs/en/UI/Angular/Environment.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/en/UI/Angular/Environment.md b/docs/en/UI/Angular/Environment.md index 1119e7781a1..86978cfa16c 100644 --- a/docs/en/UI/Angular/Environment.md +++ b/docs/en/UI/Angular/Environment.md @@ -24,6 +24,7 @@ export interface Apis { export interface ApiConfig { [key: string]: string; + rootNamespace?: string; url: string; } ``` @@ -51,6 +52,8 @@ Take a look at following example When an api from `AbpIdentity` is called, the request will be sent to `"https://localhost:9090"`. Everything else will be sent to `"https://localhost:8080"` +* `rootNamespace` **(new)** : Root namespace of the related API. e.g. Acme.BookStore + ## Application ```typescript From 9e4ecc0a4a7d0cf56fc1487f5e671b5dc6497de4 Mon Sep 17 00:00:00 2001 From: Bunyamin Coskuner Date: Tue, 25 Aug 2020 18:45:46 +0300 Subject: [PATCH 9/9] docs: revert title change MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Levent Arman Özak --- docs/en/UI/Angular/Multi-Tenancy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/UI/Angular/Multi-Tenancy.md b/docs/en/UI/Angular/Multi-Tenancy.md index 2f768de32a6..fb9fb54f76b 100644 --- a/docs/en/UI/Angular/Multi-Tenancy.md +++ b/docs/en/UI/Angular/Multi-Tenancy.md @@ -20,7 +20,7 @@ On the page above, you can; You can switch between existing tenants by using the tenant switching component in the child pages of the `AccountLayoutComponent` (like Login page). Angular UI sends the selected tenant id to the backend as `__tenant` header on each request. -

Domain Tenant Resolver

+## Domain Tenant Resolver Angular UI can get the tenant name from the app running URL. You can determine the current tenant by subdomain (like mytenant1.mydomain.com) or by the whole domain (like mytenant.com). To do this, you need to set the `application.baseUrl` property in the environment: