From ad962b1c1626652b8242f47bc8a5caa20b8b5c17 Mon Sep 17 00:00:00 2001 From: TheDiaval Date: Mon, 9 Mar 2020 11:19:24 +0300 Subject: [PATCH] docs(angular): correct mistakes --- docs/en/Angular/AddingASettingsTab/index.md | 6 +- docs/en/Angular/Localization/Index.md | 32 +++--- docs/en/Angular/PermissionManagement/index.md | 10 +- .../en/Angular/ReplaceableComponents/index.md | 4 +- docs/en/Authorization.md | 97 ++++++++++--------- docs/en/docs-nav.json | 26 +++++ 6 files changed, 102 insertions(+), 73 deletions(-) diff --git a/docs/en/Angular/AddingASettingsTab/index.md b/docs/en/Angular/AddingASettingsTab/index.md index f402d6ec50..dba9ca1a3d 100644 --- a/docs/en/Angular/AddingASettingsTab/index.md +++ b/docs/en/Angular/AddingASettingsTab/index.md @@ -4,14 +4,14 @@ There are several settings tabs from different modules. You can add custom setti 1. Create a Component -```ts +```js import { Select } from '@ngxs/store'; import { Component } from '@angular/core'; @Component({ selector: 'app-your-custom-settings', template: ` - your-custom-settings works! mySetting: {{ mySetting$ | async }} + your-custom-settings works! mySetting: {%{{ mySetting$ | async }}%} `, }) export class YourCustomSettingsComponent { @@ -24,7 +24,7 @@ export class YourCustomSettingsComponent { 3. Open the `app.component.ts` and add the below content to the `ngOnInit` -```ts +```js import { addSettingTab } from '@abp/ng.theme.shared'; // ... diff --git a/docs/en/Angular/Localization/Index.md b/docs/en/Angular/Localization/Index.md index ea6e9b7ea0..16d3837582 100644 --- a/docs/en/Angular/Localization/Index.md +++ b/docs/en/Angular/Localization/Index.md @@ -2,9 +2,9 @@ There are three ways to use localization in your project: -- Via [localization pipe](#using-the-localization-pipe) in your component's template -- Via [localization service](#using-the-localization-service) in your TypeScript files. -- Via [the Config State](#using-the-config-state) +- [Localization pipe](#using-the-localization-pipe) in your component's template +- [Localization service](#using-the-localization-service) in your TypeScript files. +- [Config State](#using-the-config-state) Before you read about _the Localization Pipe_ and _the Localization Service_, you should know about localization keys. @@ -13,7 +13,7 @@ The Localization key format consists of 2 sections which are **Resource Name** a > If you do not specify the resource name, it will be `defaultResourceName` which is declared in _environment.ts_ -```ts +```js const environment = { //... localization: { @@ -22,12 +22,12 @@ const environment = { }; ``` -So this two are the same: +So these two are the same: ```html -

{{ '::Key' | abpLocalization }}

+

{%{{ '::Key' | abpLocalization }}%}

-

{{ 'MyProjectName::Key' | abpLocalization }}

+

{%{{ 'MyProjectName::Key' | abpLocalization }}%}

``` ### Using the Localization Pipe @@ -35,7 +35,7 @@ So this two are the same: You can use the `abpLocalization` pipe to get localized text as in this example: ```html -

{{ 'Resource::Key' | abpLocalization }}

+

{%{{ 'Resource::Key' | abpLocalization }}%}

``` The pipe will replace the key with the localized text. @@ -43,7 +43,7 @@ The pipe will replace the key with the localized text. You can also specify a default value as shown below: ```html -

{{ { key: 'Resource::Key', defaultValue: 'Default Value' } | abpLocalization }}

+

{%{{ { key: 'Resource::Key', defaultValue: 'Default Value' } | abpLocalization }}%}

``` To use interpolation, you must give the values for interpolation as pipe parameters, for example: @@ -63,7 +63,7 @@ Localization data is stored in key-value pairs: So we can use this key like this: ```html -

{{ 'AbpAccount::PagerInfo' | abpLocalization:'20':'30':'50' }}

+

{%{{ 'AbpAccount::PagerInfo' | abpLocalization:'20':'30':'50' }}%}

``` @@ -72,7 +72,7 @@ So we can use this key like this: First of all you should import the `LocalizationService` from **@abp/ng.core** -```ts +```js import { LocalizationService } from '@abp/ng.core'; class MyClass { @@ -84,7 +84,7 @@ After that, you are able to use localization service. > You can add interpolation parameters as arguments to `instant()` and `get()` methods. -```ts +```js this.localizationService.instant('AbpIdentity::UserDeletionConfirmation', 'John'); // with fallback value @@ -99,7 +99,7 @@ this.localizationService.instant( To get a localized text as [_Observable_](https://rxjs.dev/guide/observable) use `get` method instead of `instant`: -```ts +```js this.localizationService.get('Resource::Key'); // with fallback value @@ -110,19 +110,19 @@ this.localizationService.get({ key: 'Resource::Key', defaultValue: 'Default Valu In order to you `getLocalization` method you should import ConfigState. -```ts +```js import { ConfigState } from '@abp/ng.core'; ``` Then you can use it as followed: -```ts +```js this.store.selectSnapshot(ConfigState.getLocalization('ResourceName::Key')); ``` `getLocalization` method can be used with both `localization key` and [`LocalizationWithDefault`](https://github.com/abpframework/abp/blob/dev/npm/ng-packs/packages/core/src/lib/models/config.ts#L34) interface. -```ts +```js this.store.selectSnapshot( ConfigState.getLocalization( { diff --git a/docs/en/Angular/PermissionManagement/index.md b/docs/en/Angular/PermissionManagement/index.md index bf46635be9..3fde81fafa 100644 --- a/docs/en/Angular/PermissionManagement/index.md +++ b/docs/en/Angular/PermissionManagement/index.md @@ -1,10 +1,12 @@ -## Permission Management in Angular Projects +## Permissions in Angular Projects + +A permission is a simple policy that is granted or prohibited for a particular user, role or client. You can read more about [authorization in ABP](Authorization.md) document. You can get permission of authenticated user using `getGrantedPolicy` selector of `ConfigState`. You can get permission as boolean value from store: -```ts +```js import { Store } from '@ngxs/store'; import { ConfigState } from '../states'; @@ -21,7 +23,7 @@ export class YourComponent { Or you can get it via `ConfigStateService`: -```ts +```js import { ConfigStateService } from '../services/config-state.service'; export class YourComponent { @@ -55,7 +57,7 @@ You can use `PermissionGuard` if you want to control authenticated user's permis Add `requiredPolicy` to the `routes` property in your routing module. -```ts +```js const routes: Routes = [ { path: 'path', diff --git a/docs/en/Angular/ReplaceableComponents/index.md b/docs/en/Angular/ReplaceableComponents/index.md index f0c99d44d2..48d1ee46c0 100644 --- a/docs/en/Angular/ReplaceableComponents/index.md +++ b/docs/en/Angular/ReplaceableComponents/index.md @@ -4,13 +4,13 @@ You can replace some ABP components with your custom components. The reason that you **can replace** but **cannot customize** default ABP components is disabling or changing a part of that component can cause problems. So we named those components as _Replaceable Components_. -## How to Use Replaceable Components +## How to Replace a Component Create a new component that you want to use instead of an ABP component. Add that component to `declarations` and `entryComponents` in the `AppModule`. Then, open the `app.component.ts` and dispatch the `AddReplaceableComponent` action to replace your component with an ABP component as shown below: -```ts +```js import { ..., AddReplaceableComponent } from '@abp/ng.core'; export class AppComponent { constructor(..., private store: Store) {} diff --git a/docs/en/Authorization.md b/docs/en/Authorization.md index 6cf6917ba6..f1f3e514cd 100644 --- a/docs/en/Authorization.md +++ b/docs/en/Authorization.md @@ -1,6 +1,6 @@ # Authorization -Authorization is used to check if a user is allowed to perform some specific operations in the application. +Authorization is used to check if a user is allowed to perform some specific operations in the application. ABP extends [ASP.NET Core Authorization](https://docs.microsoft.com/en-us/aspnet/core/security/authorization/introduction) by adding **permissions** as auto [policies](https://docs.microsoft.com/en-us/aspnet/core/security/authorization/policies) and allowing authorization system to be usable in the **[application services](Application-Services.md)** too. @@ -12,7 +12,7 @@ ASP.NET Core defines the [**Authorize**](https://docs.microsoft.com/en-us/aspnet Example: -````csharp +```csharp using System; using System.Collections.Generic; using System.Threading.Tasks; @@ -43,11 +43,11 @@ namespace Acme.BookStore } } -```` +``` -* `Authorize` attribute forces the user to login into the application in order to use the `AuthorAppService` methods. So, `GetListAsync` method is only available to the authenticated users. -* `AllowAnonymous` suppresses the authentication. So, `GetAsync` method is available to everyone including unauthorized users. -* `[Authorize("BookStore_Author_Create")]` defines a policy (see [policy based authorization](https://docs.microsoft.com/en-us/aspnet/core/security/authorization/policies)) that is checked to authorize the current user. +- `Authorize` attribute forces the user to login into the application in order to use the `AuthorAppService` methods. So, `GetListAsync` method is only available to the authenticated users. +- `AllowAnonymous` suppresses the authentication. So, `GetAsync` method is available to everyone including unauthorized users. +- `[Authorize("BookStore_Author_Create")]` defines a policy (see [policy based authorization](https://docs.microsoft.com/en-us/aspnet/core/security/authorization/policies)) that is checked to authorize the current user. "BookStore_Author_Create" is an arbitrary policy name. If you declare an attribute like that, ASP.NET Core authorization system expects a policy to be defined before. @@ -61,7 +61,7 @@ A permission is a simple policy that is granted or prohibited for a particular u To define permissions, create a class inheriting from the `PermissionDefinitionProvider` as shown below: -````csharp +```csharp using Volo.Abp.Authorization.Permissions; namespace Acme.BookStore.Permissions @@ -76,7 +76,7 @@ namespace Acme.BookStore.Permissions } } } -```` +``` > ABP automatically discovers this class. No additional configuration required! @@ -86,8 +86,8 @@ When you define a permission, it becomes usable in the ASP.NET Core authorizatio ![authorization-new-permission-ui](images/authorization-new-permission-ui.png) -* The "BookStore" group is shown as a new tab on the left side. -* "BookStore_Author_Create" on the right side is the permission name. You can grant or prohibit it for the role. +- The "BookStore" group is shown as a new tab on the left side. +- "BookStore_Author_Create" on the right side is the permission name. You can grant or prohibit it for the role. When you save the dialog, it is saved to the database and used in the authorization system. @@ -97,7 +97,7 @@ When you save the dialog, it is saved to the database and used in the authorizat "BookStore_Author_Create" is not a good permission name for the UI. Fortunately, `AddPermission` and `AddGroup` methods can take `LocalizableString` as second parameters: -````csharp +```csharp var myGroup = context.AddGroup( "BookStore", LocalizableString.Create("BookStore") @@ -107,14 +107,14 @@ myGroup.AddPermission( "BookStore_Author_Create", LocalizableString.Create("Permission:BookStore_Author_Create") ); -```` +``` Then you can define texts for "BookStore" and "Permission:BookStore_Author_Create" keys in the localization file: -````json +```json "BookStore": "Book Store", "Permission:BookStore_Author_Create": "Creating a new author" -```` +``` > For more information, see the [localization document](Localization.md) on the localization system. @@ -126,21 +126,21 @@ The localized UI will be as seen below: ABP supports [multi-tenancy](Multi-Tenancy.md) as a first class citizen. You can define multi-tenancy side option while defining a new permission. It gets one of the three values defined below: -* **Host**: The permission is available only for the host side. -* **Tenant**: The permission is available only for the tenant side. -* **Both** (default): The permission is available both for tenant and host sides. +- **Host**: The permission is available only for the host side. +- **Tenant**: The permission is available only for the tenant side. +- **Both** (default): The permission is available both for tenant and host sides. > If your application is not multi-tenant, you can ignore this option. To set the multi-tenancy side option, pass to the third parameter of the `AddPermission` method: -````csharp +```csharp myGroup.AddPermission( "BookStore_Author_Create", LocalizableString.Create("Permission:BookStore_Author_Create"), multiTenancySide: MultiTenancySides.Tenant //set multi-tenancy side! ); -```` +``` #### Child Permissions @@ -148,12 +148,12 @@ A permission may have child permissions. It is especially useful when you want t Example definition: -````csharp +```csharp var authorManagement = myGroup.AddPermission("Author_Management"); authorManagement.AddChild("Author_Management_Create_Books"); authorManagement.AddChild("Author_Management_Edit_Books"); authorManagement.AddChild("Author_Management_Delete_Books"); -```` +``` The result on the UI is shown below (you probably want to localize permissions for your application): @@ -161,7 +161,7 @@ The result on the UI is shown below (you probably want to localize permissions f For the example code, it is assumed that a role/user with "Author_Management" permission granted may have additional permissions. Then a typical application service that checks permissions can be defined as shown below: -````csharp +```csharp [Authorize("Author_Management")] public class AuthorAppService : ApplicationService, IAuthorAppService { @@ -193,10 +193,10 @@ public class AuthorAppService : ApplicationService, IAuthorAppService ... } } -```` +``` -* `GetListAsync` and `GetAsync` will be available to users if they have `Author_Management` permission is granted. -* Other methods require additional permissions. +- `GetListAsync` and `GetAsync` will be available to users if they have `Author_Management` permission is granted. +- Other methods require additional permissions. ### Overriding a Permission by a Custom Policy @@ -210,7 +210,7 @@ ASP.NET Core provides the `IAuthorizationService` that can be used to check for Example: -````csharp +```csharp public async Task CreateAsync(CreateAuthorDto input) { var result = await AuthorizationService @@ -223,7 +223,7 @@ public async Task CreateAsync(CreateAuthorDto input) //continue to the normal flow... } -```` +``` > `AuthorizationService` is available as a property when you derive from ABP's `ApplicationService` base class. Since it is widely used in application services, `ApplicationService` pre-injects it for you. Otherwise, you can directly [inject](Dependency-Injection.md) it into your class. @@ -231,14 +231,14 @@ Since this is a typical code block, ABP provides extension methods to simplify i Example: -````csharp +```csharp public async Task CreateAsync(CreateAuthorDto input) { await AuthorizationService.CheckAsync("Author_Management_Create_Books"); //continue to the normal flow... } -```` +``` `CheckAsync` extension method throws `AbpAuthorizationException` if the current user/client is not granted for the given permission. There is also `IsGrantedAsync` extension method that returns `true` or `false`. @@ -250,9 +250,9 @@ public async Task CreateAsync(CreateAuthorDto input) You may need to check a policy/permission on the client side. For ASP.NET Core MVC / Razor Pages applications, you can use the `abp.auth` API. Example: -````js +```js abp.auth.isGranted('MyPermissionName'); -```` +``` See [abp.auth](AspNetCore/JavaScript-API/Auth.md) API documentation for details. @@ -264,7 +264,7 @@ Permission management is normally done by an admin user using the permission man If you need to manage permissions by code, inject the `IPermissionManager` and use as shown below: -````csharp +```csharp public class MyService : ITransientDependency { private readonly IPermissionManager _permissionManager; @@ -284,7 +284,7 @@ public class MyService : ITransientDependency await _permissionManager.SetForUserAsync(userId, permissionName, false); } } -```` +``` `SetForUserAsync` sets the value (true/false) for a permission of a user. There are more extension methods like `SetForRoleAsync` and `SetForClientAsync`. @@ -296,15 +296,15 @@ public class MyService : ITransientDependency Permission checking system is extensible. Any class derived from `PermissionValueProvider` (or implements `IPermissionValueProvider`) can contribute to the permission check. There are three pre-defined value providers: -* `UserPermissionValueProvider` checks if the current user is granted for the given permission. It gets user id from the current claims. User claim name is defined with the `AbpClaimTypes.UserId` static property. -* `RolePermissionValueProvider` checks if any of the roles of the current user is granted for the given permission. It gets role names from the current claims. Role claims name is defined with the `AbpClaimTypes.Role` static property. -* `ClientPermissionValueProvider` checks if the current client is granted for the given permission. This is especially useful on a machine to machine interaction where there is no current user. It gets the client id from the current claims. Client claim name is defined with the `AbpClaimTypes.ClientId` static property. +- `UserPermissionValueProvider` checks if the current user is granted for the given permission. It gets user id from the current claims. User claim name is defined with the `AbpClaimTypes.UserId` static property. +- `RolePermissionValueProvider` checks if any of the roles of the current user is granted for the given permission. It gets role names from the current claims. Role claims name is defined with the `AbpClaimTypes.Role` static property. +- `ClientPermissionValueProvider` checks if the current client is granted for the given permission. This is especially useful on a machine to machine interaction where there is no current user. It gets the client id from the current claims. Client claim name is defined with the `AbpClaimTypes.ClientId` static property. You can extend the permission checking system by defining your own permission value provider. Example: -````csharp +```csharp public class SystemAdminPermissionValueProvider : PermissionValueProvider { public SystemAdminPermissionValueProvider(IPermissionStore permissionStore) @@ -314,7 +314,7 @@ public class SystemAdminPermissionValueProvider : PermissionValueProvider public override string Name => "SystemAdmin"; - public override async Task + public override async Task CheckAsync(PermissionValueCheckContext context) { if (context.Principal?.FindFirst("User_Type")?.Value == "SystemAdmin") @@ -325,24 +325,24 @@ public class SystemAdminPermissionValueProvider : PermissionValueProvider return PermissionGrantResult.Undefined; } } -```` +``` This provider allows for all permissions to a user with a `User_Type` claim that has `SystemAdmin` value. It is common to use current claims and `IPermissionStore` in a permission value provider. A permission value provider should return one of the following values from the `CheckAsync` method: -* `PermissionGrantResult.Granted` is returned to grant the user for the permission. If any of the providers return `Granted`, the result will be `Granted`, if no other provider returns `Prohibited`. -* `PermissionGrantResult.Prohibited` is returned to prohibit the user for the permission. If any of the providers return `Prohibited`, the result will always be `Prohibited`. Doesn't matter what other providers return. -* `PermissionGrantResult.Undefined` is returned if this value provider could not decide about the permission value. Return this to let other providers check the permission. +- `PermissionGrantResult.Granted` is returned to grant the user for the permission. If any of the providers return `Granted`, the result will be `Granted`, if no other provider returns `Prohibited`. +- `PermissionGrantResult.Prohibited` is returned to prohibit the user for the permission. If any of the providers return `Prohibited`, the result will always be `Prohibited`. Doesn't matter what other providers return. +- `PermissionGrantResult.Undefined` is returned if this value provider could not decide about the permission value. Return this to let other providers check the permission. Once a provider is defined, it should be added to the `PermissionOptions` as shown below: -````csharp +```csharp Configure(options => { options.ValueProviders.Add(); }); -```` +``` ### Permission Store @@ -354,16 +354,17 @@ Configure(options => Use `IServiceCollection.AddAlwaysAllowAuthorization()` extension method to register the `AlwaysAllowAuthorizationService` to the [dependency injection](Dependency-Injection.md) system: -````csharp +```csharp public override void ConfigureServices(ServiceConfigurationContext context) { context.Services.AddAlwaysAllowAuthorization(); } -```` +``` This is already done for the startup template integration tests. ## See Also -* [Permission Management Module](Modules/Permission-Management.md) -* [ASP.NET Core MVC / Razor Pages JavaScript Auth API](AspNetCore/JavaScript-API/Auth.md) +- [Permission Management Module](Modules/Permission-Management.md) +- [ASP.NET Core MVC / Razor Pages JavaScript Auth API](AspNetCore/JavaScript-API/Auth.md) +- [Permissions in Angular Projects](Angular/PermissionManagement/index) diff --git a/docs/en/docs-nav.json b/docs/en/docs-nav.json index 46a3b54406..15e2fef507 100644 --- a/docs/en/docs-nav.json +++ b/docs/en/docs-nav.json @@ -283,6 +283,32 @@ } ] }, + { + "text": "User Interface", + "items": [ + { + "text": "Angular", + "items": [ + { + "text": "Localization", + "path": "Angular/Localization/Index.md" + }, + { + "text": "Adding a Settings Tab", + "path": "Angular/AddingASettingsTab/index.md" + }, + { + "text": "Permission", + "path": "Angular/PermissionManagement/index.md" + }, + { + "text": "Component Replacement", + "path": "Angular/ReplaceableComponents/index.md" + } + ] + } + ] + }, { "text": "Data Access", "path": "Data-Access.md",