| + + + | +
+
+> What if I want Azure AD as my authorization server and not IdentityServer?
+
+This means your application will be using AzureAD user store for authentication. By registering both angular app and HttpApi to AzureAD, authentication might work but **authorization won't**. Users need to be registered to Abp identity system for auditing, permissions etc. So the flow should be 3rd party registration.
+
+## Setting up OpenId Connection
+
+Lets start with adding OpenId connection. Open the **HttpApiHostModule.cs** and update the **ConfigureAuthentication** method as below:
+
+```csharp
+JwtSecurityTokenHandler.DefaultInboundClaimTypeMap.Clear();
+JwtSecurityTokenHandler.DefaultInboundClaimTypeMap.Add("sub", ClaimTypes.NameIdentifier);
+
+context.Services.AddAuthentication()
+ .AddIdentityServerAuthentication(options =>
+ {
+ options.Authority = configuration["AuthServer:Authority"];
+ options.RequireHttpsMetadata = false;
+ options.ApiName = "NonTieredAngular";
+ options.JwtBackChannelHandler = new HttpClientHandler()
+ {
+ ServerCertificateCustomValidationCallback = HttpClientHandler.DangerousAcceptAnyServerCertificateValidator
+ };
+ })
+ .AddOpenIdConnect("AzureOpenId", "Azure AD OpenId", options =>
+ {
+ options.Authority = "https://login.microsoftonline.com/" + configuration["AzureAd:TenantId"] + "/v2.0/";
+ options.ClientId = configuration["AzureAd:ClientId"];
+ options.ResponseType = OpenIdConnectResponseType.CodeIdToken;
+ options.CallbackPath = configuration["AzureAd:CallbackPath"];
+ options.ClientSecret = configuration["AzureAd:ClientSecret"];
+ options.RequireHttpsMetadata = false;
+ options.SaveTokens = true;
+ options.GetClaimsFromUserInfoEndpoint = true;
+ options.Scope.Add("email");
+ });
+```
+
+> If you are using tiered (separate identity server) application, open **IdentityServerModule.cs** and add the OpenIdConnection manually to **ConfigureServices** method as following:
+
+```csharp
+public override void ConfigureServices(ServiceConfigurationContext context)
+{
+ var hostingEnvironment = context.Services.GetHostingEnvironment();
+ var configuration = context.Services.GetConfiguration();
+
+ JwtSecurityTokenHandler.DefaultInboundClaimTypeMap.Clear();
+ JwtSecurityTokenHandler.DefaultInboundClaimTypeMap.Add("sub", ClaimTypes.NameIdentifier);
+
+ context.Services.AddAuthentication()
+ .AddOpenIdConnect("AzureOpenId", "Azure AD OpenId", options =>
+ {
+ ... // Same configuration above
+ });
+```
+
+Now we can add AzureAD settings. Open the **appsettings.json** located in **HttpApi.Host** project (or **IdentityServer** project if you are using tiered application). Add the following;
+
+```csharp
+"AzureAd": {
+ "Instance": "https://login.microsoftonline.com/",
+ "TenantId": "
+
+Now navigate to **Authentication** on the left menu and enable **ID tokens**.
+
+
+
+We also need to set a client secret. Navigate to **Certificates & secrets** menu on the left and create a new client secret.
+
+
+
+**Copy** the secret and update your appsettings.json **AzureAd.ClientSecret** field.
+
+
+
+Also update your **AzureAd.TenantId** and **AzureAd.ClientId** fields with the information located under **Overview** menu. And that's all.
+
+Next time you hit login, you should be seeing login screen enabled Azure AD like below.
+
+
+
+# FAQ
+
+* I am getting errors when trying to login to AzureAD.
+ * You can check [this article FAQ](https://community.abp.io/articles/how-to-use-the-azure-active-directory-authentication-for-mvc-razor-page-applications-4603b9cf) which covers many errors.
+
+
+* But I don't want my users to see default login screen. I want my users to login **only** from AzureAD.
+ * You can **mimic** this behaviour by customizing the login page and instantly trigger Azure AD provider click. For more info, you can check [this article](https://community.abp.io/articles/how-to-customize-the-login-page-for-mvc-razor-page-applications-9a40f3cd).
diff --git a/docs/en/Community-Articles/2020-09-16-How-to-Setup-Azure-Active-Directory-and-Integrate-Abp-Angular-Application/app-login.JPG b/docs/en/Community-Articles/2020-09-16-How-to-Setup-Azure-Active-Directory-and-Integrate-Abp-Angular-Application/app-login.JPG
new file mode 100644
index 0000000000..94500a4f15
Binary files /dev/null and b/docs/en/Community-Articles/2020-09-16-How-to-Setup-Azure-Active-Directory-and-Integrate-Abp-Angular-Application/app-login.JPG differ
diff --git a/docs/en/Community-Articles/2020-09-16-How-to-Setup-Azure-Active-Directory-and-Integrate-Abp-Angular-Application/auth-diagram.jpeg b/docs/en/Community-Articles/2020-09-16-How-to-Setup-Azure-Active-Directory-and-Integrate-Abp-Angular-Application/auth-diagram.jpeg
new file mode 100644
index 0000000000..dec4a66a17
Binary files /dev/null and b/docs/en/Community-Articles/2020-09-16-How-to-Setup-Azure-Active-Directory-and-Integrate-Abp-Angular-Application/auth-diagram.jpeg differ
diff --git a/docs/en/Community-Articles/2020-09-16-How-to-Setup-Azure-Active-Directory-and-Integrate-Abp-Angular-Application/azure-app-authentication.jpg b/docs/en/Community-Articles/2020-09-16-How-to-Setup-Azure-Active-Directory-and-Integrate-Abp-Angular-Application/azure-app-authentication.jpg
new file mode 100644
index 0000000000..5061118aa3
Binary files /dev/null and b/docs/en/Community-Articles/2020-09-16-How-to-Setup-Azure-Active-Directory-and-Integrate-Abp-Angular-Application/azure-app-authentication.jpg differ
diff --git a/docs/en/Community-Articles/2020-09-16-How-to-Setup-Azure-Active-Directory-and-Integrate-Abp-Angular-Application/azure-app-overview.jpg b/docs/en/Community-Articles/2020-09-16-How-to-Setup-Azure-Active-Directory-and-Integrate-Abp-Angular-Application/azure-app-overview.jpg
new file mode 100644
index 0000000000..11053062e2
Binary files /dev/null and b/docs/en/Community-Articles/2020-09-16-How-to-Setup-Azure-Active-Directory-and-Integrate-Abp-Angular-Application/azure-app-overview.jpg differ
diff --git a/docs/en/Community-Articles/2020-09-16-How-to-Setup-Azure-Active-Directory-and-Integrate-Abp-Angular-Application/azure-app-register.JPG b/docs/en/Community-Articles/2020-09-16-How-to-Setup-Azure-Active-Directory-and-Integrate-Abp-Angular-Application/azure-app-register.JPG
new file mode 100644
index 0000000000..68c180cea0
Binary files /dev/null and b/docs/en/Community-Articles/2020-09-16-How-to-Setup-Azure-Active-Directory-and-Integrate-Abp-Angular-Application/azure-app-register.JPG differ
diff --git a/docs/en/Community-Articles/2020-09-16-How-to-Setup-Azure-Active-Directory-and-Integrate-Abp-Angular-Application/azure-app-registration.jpg b/docs/en/Community-Articles/2020-09-16-How-to-Setup-Azure-Active-Directory-and-Integrate-Abp-Angular-Application/azure-app-registration.jpg
new file mode 100644
index 0000000000..12f4eb36e2
Binary files /dev/null and b/docs/en/Community-Articles/2020-09-16-How-to-Setup-Azure-Active-Directory-and-Integrate-Abp-Angular-Application/azure-app-registration.jpg differ
diff --git a/docs/en/Community-Articles/2020-09-16-How-to-Setup-Azure-Active-Directory-and-Integrate-Abp-Angular-Application/azure-app-secret.jpg b/docs/en/Community-Articles/2020-09-16-How-to-Setup-Azure-Active-Directory-and-Integrate-Abp-Angular-Application/azure-app-secret.jpg
new file mode 100644
index 0000000000..9cf2009eda
Binary files /dev/null and b/docs/en/Community-Articles/2020-09-16-How-to-Setup-Azure-Active-Directory-and-Integrate-Abp-Angular-Application/azure-app-secret.jpg differ
diff --git a/docs/en/Community-Articles/2020-09-28-Using-DevExtremeAngularComponents-With-The-ABP-Framework/Using-DevExtremeAngularComponents-With-The-ABP-Framework.md b/docs/en/Community-Articles/2020-09-28-Using-DevExtremeAngularComponents-With-The-ABP-Framework/Using-DevExtremeAngularComponents-With-The-ABP-Framework.md
new file mode 100644
index 0000000000..c20b796073
--- /dev/null
+++ b/docs/en/Community-Articles/2020-09-28-Using-DevExtremeAngularComponents-With-The-ABP-Framework/Using-DevExtremeAngularComponents-With-The-ABP-Framework.md
@@ -0,0 +1,317 @@
+# Using DevExtreme Angular Components With the ABP Framework
+
+In this article, I will show you how to integrate the [DevExpress Angular components](https://js.devexpress.com/Documentation/Guide/Angular_Components/DevExtreme_Angular_Components/) to a project created using the ABP Framework startup templates. Then I will use the [DataGrid](https://js.devexpress.com/Documentation/Guide/Widgets/DataGrid/Overview/) component to show a list of users on the UI.
+
+## Create the Project
+
+Let's create a new web application with the Angular UI using [ABP CLI](https://docs.abp.io/en/abp/latest/CLI#new):
+
+```shell
+abp new DevExtremeAngular -u angular
+```
+
+> For detail information about how to generate and start up a project, please refer to the [official docs](https://docs.abp.io/en/abp/latest/Getting-Started?UI=NG&DB=EF&Tiered=No). For the scope of this post, we will not go into details of the backend applications.
+
+## Running the Solution
+
+### The Server Side
+
+Server side contains multiple projects in the solution:
+
+
+
+Run following projects in order;
+
+* Run `DevExtremeAngular.DbMigrator` to create the database and seed the initial data.
+* Run `DevExtremeAngular.HttpApi.Host` project to make the backend API up & running.
+
+### The Angular Application
+
+Open a command line terminal and navigate to `angular` folder then run `yarn` or `npm install` based on which package you are using.
+
+After installation process is done, you can start your angular project by running `yarn start` or `npm start`. This command should serve the application and open the application in your default browser. If it doesn't open, you can navigate to http://localhost:4200 in your browser:
+
+
+
+You can login to the application by using following credentials:
+
+> _Default admin username is **admin** and password is **1q2w3E\***_
+
+
+
+After successful login, you should be redirected to home page.
+
+## Install DevExtreme
+
+You can follow [the guide](https://js.devexpress.com/Documentation/Guide/Angular_Components/Getting_Started/Add_DevExtreme_to_an_Angular_CLI_Application/) provided by **DevExtreme** team or apply the following steps.
+
+* `npm install devextreme devextreme-angular` or `yarn add devextreme devextreme-angular`
+* Import given two following styles in `angular.json` file:
+
+```javascript
+ // ...
+ "styles": [
+ // ...
+ "src/styles.scss",
+
+ "node_modules/devextreme/dist/css/dx.common.css",
+ "node_modules/devextreme/dist/css/dx.light.css"
+ ]
+```
+
+* Add `dx-viewport` to classes of `body` in `index.html`
+
+```html
+
+ -
+
- + {{ user.name }} + +
@Localizer["HelloWorld"]
```` -Refer to the [Microsoft's localization documentation](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/localization) for details about using localization on the server side. - -### Client Side - -ABP provides JavaScript services to use the same localized texts in the client side. - -#### getResource - -`abp.localization.getResource` function is used to get a localization resource: - -````js -var testResource = abp.localization.getResource('Test'); -```` - -Then you can localize a string based on this resource: +### Special Base Classes -````js -var str = testResource('HelloWorld'); -```` +Some ABP Framework base classes provide a `L` property to use the localizer even easier. -#### localize +**Example: Localize a text in an application service method** -`abp.localization.localize` function is a shortcut where you can both specify the text name and the resource name: +```csharp +using System.Threading.Tasks; +using MyProject.Localization; +using Volo.Abp.Application.Services; -````js -var str = abp.localization.localize('HelloWorld', 'Test'); -```` +namespace MyProject +{ + public class TestAppService : ApplicationService + { + public TestAppService() + { + LocalizationResource = typeof(MyProjectResource); + } -`HelloWorld` is the text to localize, where `Test` is the localization resource name here. + public async Task DoIt() + { + var str = L["HelloWorld"]; + } + } +} +``` -If you don't specify the localization resource name, it uses the default localization resource defined on the `AbpLocalizationOptions` (see the *Default Resource* section above). Example: +When you set the `LocalizationResource` in the constructor, the `ApplicationService` class uses that resource type when you use the `L` property, just like in the `DoIt()` method. -````js -var str = abp.localization.localize('HelloWorld'); //uses the default resource -```` +Setting `LocalizationResource` in every application service can be tedious. You can create an abstract base application service class, set it there and derive your application services from that base class. This is already implemented when you create a new project with the [startup templates](Startup-Templates/Application.md). So, you can simply inherit from the base class directly use the `L` property: -##### Format Arguments +```csharp +using System.Threading.Tasks; -If your localized string contains arguments, like `Hello {0}, welcome!`, you can pass arguments to the localization methods. Examples: +namespace MyProject +{ + public class TestAppService : MyProjectAppService + { + public async Task DoIt() + { + var str = L["HelloWorld"]; + } + } +} +``` -````js -var str1 = abp.localization.getResource('Test')('HelloWelcomeMessage', 'John'); -var str2 = abp.localization.localize('HelloWorld', 'Test', 'John'); -```` +The `L` property is also available for some other base classes like `AbpController` and `AbpPageModel`. -Both of the samples above produce the output `Hello John, welcome!`. +## The Client Side -## See Also +See the following documents to learn how to reuse the same localization texts in the JavaScript side; -* [Localization in Angular UI](UI/Angular/Localization.md) \ No newline at end of file +* [Localization for the MVC / Razor Pages UI](UI/AspNetCore/JavaScript-API/Localization.md) +* [Localization for the Blazor UI](UI/Blazor/Localization.md) +* [Localization for the Angular UI](UI/Angular/Localization.md) \ No newline at end of file diff --git a/docs/en/Migration-Guides/Abp-4_0.md b/docs/en/Migration-Guides/Abp-4_0.md new file mode 100644 index 0000000000..0d193d476b --- /dev/null +++ b/docs/en/Migration-Guides/Abp-4_0.md @@ -0,0 +1,117 @@ +# ABP Framework 3.3 to 4.0 Migration Guide + +## Auto API Controller Route Changes + +The route calculation for the [Auto API Controllers](https://docs.abp.io/en/abp/latest/API/Auto-API-Controllers) is changing with the ABP Framework version 4.0 ([#5325](https://github.com/abpframework/abp/issues/5325)). Previously, **camelCase** route paths were being used. Beginning from the version 4.0, it uses **kebab-case** route paths where it is possible. + +**A typical auto API before v4.0** + + + +**camelCase route parts become kebab-case with 4.0** + + + +If it is hard to change it for your application, you can continue to use the version 3.x route strategy, by following one of the approaches; + +* Set `UseV3UrlStyle` to `true` in the options of the `options.ConventionalControllers.Create(...)` method. Example: + +````csharp +options.ConventionalControllers + .Create(typeof(BookStoreApplicationModule).Assembly, opts => + { + opts.UseV3UrlStyle = true; + }); +```` + +This approach effects only the controllers for the `BookStoreApplicationModule`. + +* Set `UseV3UrlStyle` to `true` for the `AbpConventionalControllerOptions` to set it globally. Example: + +```csharp +ConfigureBooks
+ +@code { + +} +```` + +### Add Books Page to the Main Menu + +Open the `BookStoreMenuContributor` class in the `Blazor` project add the following code to the end of the `ConfigureMainMenuAsync` method: + +````csharp +context.Menu.AddItem( + new ApplicationMenuItem( + "BooksStore", + l["Menu:BookStore"], + icon: "fa fa-book" + ).AddItem( + new ApplicationMenuItem( + "BooksStore.Books", + l["Menu:Books"], + url: "/books" + ) + ) +); +```` + +Run the project, login to the application with the username `admin` and the password `1q2w3E*` and see the new menu item has been added to the main menu: + + + +When you click to the Books menu item under the Book Store parent, you are being redirected to the new empty Books Page. + +### Book List + +We will use the [Blazorise library](https://blazorise.com/) as the UI component kit. It is a very powerful library that supports major HTML/CSS frameworks, including the Bootstrap. + +ABP Framework provides a generic base class, `AbpCrudPageBase<...>`, to create CRUD style pages. This base class is compatible to the `ICrudAppService` that was used to build the `IBookAppService`. So, we can inherit from the `AbpCrudPageBase` to automate the code behind for the standard CRUD stuff. + +Open the `Books.razor` and replace the content as the following: + +````xml +@page "/books" +@using Volo.Abp.Application.Dtos +@using Volo.Abp.BlazoriseUI +@using Acme.BookStore.Books +@using Acme.BookStore.Localization +@using Microsoft.Extensions.Localization +@inject IStringLocalizer@L["Books"]
+@L["Books"]
+@L["Books"]
+@L["Authors"]
+Tenants page
On the page above, you can; @@ -13,13 +13,12 @@ On the page above, you can; - Edit an existing tenant. - Delete a tenant. -  +Tenant Switching Component
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 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: @@ -32,10 +31,10 @@ Subdomain resolver: export const environment = { //... application: { - baseUrl: 'https://{0}.mydomain.com/' + baseUrl: "https://{0}.mydomain.com/", }, //... -} +}; ``` **{0}** is the placeholder to determine current tenant's unique name. @@ -44,7 +43,6 @@ After the configuration above, if your app runs on the `mytenant1.mydomain.com`, > **Important Note:** If you define the `baseUrl` with the placeholder (**{0}**), the tenant switching component in the child pages of the `AccountLayoutComponent` (like Login page) will be hidden. - Domain resolver: ```js @@ -53,10 +51,10 @@ Domain resolver: export const environment = { //... application: { - baseUrl: 'https://{0}.com/' + baseUrl: "https://{0}.com/", }, //... -} +}; ``` After the configuration above, if your app runs on the `mytenant.com`, the app will get the tenant name as **mytenant**. @@ -71,29 +69,28 @@ The **{0}** placeholder can be put to the API URLs in the environment to determi export const environment = { //... application: { - baseUrl: 'https://{0}.mydomain.com/', + baseUrl: "https://{0}.mydomain.com/", //... }, oAuthConfig: { - issuer: 'https://{0}.ids.mydomain.com', + issuer: "https://{0}.ids.mydomain.com", //... }, apis: { default: { - url: 'https://{0}.api.mydomain.com', + url: "https://{0}.api.mydomain.com", }, AbpIdentity: { - url: 'https://{0}.identity.mydomain.com', + url: "https://{0}.identity.mydomain.com", }, }, -} +}; ``` > **Important Note:** The `application.baseUrl` and the `{0}` placeholder in the value of the `baseUrl` property are required to be able to get tenant from running URL. Other placeholders in API URLs are optional. After the configuration above, if your app runs on the `mytenant1.mydomain.com`, the app will get tenant name as **mytenant1** and replace the environment object in `ConfigState` on app initialization as follows: - ```js // environment object in ConfigState @@ -128,8 +125,8 @@ The app sends the `__tenant` header that contains the current tenant id on each ## See Also -* [Multi Tenancy in ABP](../../Multi-Tenancy.md) +- [Multi Tenancy in ABP](../../Multi-Tenancy.md) ## What's Next? -- [Confirmation Popup](./Confirmation-Service.md) +- [Managing RxJS Subscriptions](./Subscription-Service.md) diff --git a/docs/en/UI/Angular/PWA-Configuration.md b/docs/en/UI/Angular/PWA-Configuration.md new file mode 100644 index 0000000000..a6aee244ba --- /dev/null +++ b/docs/en/UI/Angular/PWA-Configuration.md @@ -0,0 +1,346 @@ +# PWA Configuration + +[Progressive Web Apps](https://web.dev/progressive-web-apps/) are web applications which, although not as integrated to the OS as a native app, can take advantage of native features. They can be discovered via search engines, installed on devices with a single tap or click, and shared via a regular link. They also can work offline and get updates when new content is available. + +Converting your Angular application to a PWA is easy. + +## 1. Install Angular PWA + +Run the following command in the root folder of your Angular application: + +```shell +yarn ng add @angular/pwa +``` + +...or... + +```shell +npm run ng add @angular/pwa +``` + +This will install the `@angular/service-worker` package and make your default app a PWA. Alternatively, you may add `project` parameter to target a specific app in your workspace: + +```shell +yarn ng add @angular/pwa --project MyProjectName +``` + +Here is the output of the command: + +
+
+
+> Test projects slightly differs based on your UI and Database selection. For example, if you select MongoDB, then the `Acme.BookStore.EntityFrameworkCore.Tests` will be `Acme.BookStore.MongoDB.Tests`.
Each project is used to test the related project. Test projects use the following libraries for testing:
@@ -72,11 +58,11 @@ Each project is used to test the related project. Test projects use the followin
{{if DB==)
+
+So, Angular CLI updates some files and add a few others:
+
+- **ngsw-config.json** is where the [service worker configuration](https://angular.io/guide/service-worker-config) is placed. Not all PWAs have this file. It is specific to Angular.
+- **manifest.webmanifest** is a [web app manifest](https://developer.mozilla.org/en-US/docs/Web/Manifest) and provides information about your app in JSON format.
+- **icons** are placeholder icons that are referred to in your web app manifest. We will replace these in a minute.
+- **angular.json** has following modifications:
+ - `assets` include _manifest.webmanifest_.
+ - `serviceWorker` is `true` in production build.
+ - `ngswConfigPath` refers to _ngsw-config.json_.
+- **package.json** has _@angular/service-worker_ as a new dependency.
+- **app.module.ts** imports `ServiceWorkerModule` and registers a service worker filename.
+- **index.html** has following modifications:
+ - A `` element that refers to _manifest.webmanifest_.
+ - A `` tag that sets a theme color.
+
+## 2. Update the Web App Manifest
+
+### 2.1. Set the Name of Your App
+
+The `name` and the `short_name` properties in the generated manifest are derived from your project name. Let's change them.
+
+Open the _manifest.webmanifest_ file and update `name` and `short_name` props:
+
+```json
+{
+ /* rest of the manifest meta data */
+ "short_name": "My Project",
+ "name": "My Project: My Catch-Phrase"
+}
+```
+
+The short name must be really short because it will be displayed on anywhere with limited space, like the launcher and the home screen.
+
+### 2.2. Add a Description
+
+The `@angular/pwa` schematic we just added does not insert a description to your manifest file, but, according to [web app manifest standards](https://www.w3.org/TR/appmanifest/#description-member), you should.
+
+So, open the _manifest.webmanifest_ file and place the description as seen below:
+
+```json
+{
+ /* rest of the manifest meta data */
+ "description": "My short project description giving a slightly better idea about my app"
+}
+```
+
+As a bonus, providing a description [along with other criteria](https://docs.microsoft.com/en-us/microsoft-edge/progressive-web-apps-edgehtml/microsoft-store#criteria-for-automatic-submission) helps Bing web crawler to index your app and automatically submit your app to Microsoft Store in `.appx` format.
+
+### 2.3. Set App Colors
+
+Angular generates the manifest file with a default `theme_color` and `background_color`. Change these according to your brand identity:
+
+Open the _manifest.webmanifest_ file and update `theme_color` and `background_color` properties:
+
+```json
+{
+ /* rest of the manifest meta data */
+ "theme_color": "#000000",
+ "background_color": "#ffffff"
+}
+```
+
+Then open _index.html_ and change the theme color meta tag as below:
+
+```html
+
+```
+
+### 2.4. Replace App Icons & Add Splash Screens
+
+We need to update the icons and add some splash screens. This normally is time-consuming, but we will use the marvelous [pwa-asset-generator](https://github.com/onderceylan/pwa-asset-generator#readme) library.
+
+First, open the _manifest.webmanifest_ file and remove all elements in the `icons` property:
+
+```json
+{
+ /* rest of the manifest meta data */
+ "icons": []
+}
+```
+
+Then, run the following command in your terminal (changing the path of course):
+
+```shell
+npx pwa-asset-generator /path/to/your/logo.png ./src/assets/pwa -i ./src/index.html -m ./src/manifest.webmanifest
+```
+
+Open the _manifest.webmanifest_ file again. You will see this:
+
+```json
+{
+ /* rest of the manifest meta data */
+ "icons": [
+ {
+ "src": "../manifest-icon-192.png",
+ "sizes": "192x192",
+ "type": "image/png",
+ "purpose": "maskable any"
+ },
+ {
+ "src": "../manifest-icon-512.png",
+ "sizes": "512x512",
+ "type": "image/png",
+ "purpose": "maskable any"
+ }
+ ]
+}
+```
+
+In addition to updated icons, the library will generate splash screens. However, Apple requires all splash screens to be added in your _index.html_ and displays a blank screen at startup otherwise. So, the following tags will be inserted into the _index.html_ file:
+
+```html
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+## 3. Configure Service Worker
+
+### 3.1 Modify Asset Groups
+
+Angular has defined some static files to be cached by the service worker, but they are not 100% accurate. Let's change it.
+
+Open _ngsw-config.json_ file and replace its content with this:
+
+```json
+{
+ "$schema": "./node_modules/@angular/service-worker/config/schema.json",
+ "index": "/index.html",
+ "assetGroups": [
+ {
+ "name": "app",
+ "installMode": "prefetch",
+ "resources": {
+ "files": [
+ "/favicon.ico",
+ "/index.html",
+ "/manifest.webmanifest",
+ "/*.css",
+ "/common-es2015.*.js",
+ "/main-es2015.*.js",
+ "/polyfills-es2015.*.js",
+ "/runtime-es2015.*.js",
+ "/vendor-es2015.*.js"
+ ]
+ }
+ },
+ {
+ "name": "modules",
+ "installMode": "lazy",
+ "updateMode": "prefetch",
+ "resources": {
+ "files": [
+ "/*-es2015.*.js",
+ "!/common-es2015.*.js",
+ "!/main-es2015.*.js",
+ "!/polyfills-es2015.*.js",
+ "!/runtime-es2015.*.js",
+ "!/vendor-es2015.*.js"
+ ]
+ }
+ },
+ {
+ "name": "assets",
+ "installMode": "lazy",
+ "updateMode": "prefetch",
+ "resources": {
+ "files": [
+ "/assets/**",
+ "/*.(eot|svg|cur|jpg|png|webp|gif|otf|ttf|woff|woff2|ani)"
+ ]
+ }
+ }
+ ]
+}
+```
+
+In case you want to cache other static files, please refer to the [service worker configuration document](https://angular.io/guide/service-worker-config#assetgroups) on Angular.io.
+
+### 3.2 Set Data Groups
+
+This part is unique to your project. We recommend being very careful about which endpoints to cache. Please refer to [service worker configuration document](https://angular.io/guide/service-worker-config#datagroups) on Angular.io for details.
+
+## What's Next?
+
+- [Config State](./Config-State.md)
diff --git a/docs/en/UI/Angular/Quick-Start.md b/docs/en/UI/Angular/Quick-Start.md
new file mode 100644
index 0000000000..a58671156c
--- /dev/null
+++ b/docs/en/UI/Angular/Quick-Start.md
@@ -0,0 +1,212 @@
+# ABP Angular Quick Start
+
+## How to Prepare Development Environment
+
+Please follow the steps below to prepare your development environment for Angular.
+
+1. **Install Node.js:** Please visit [Node.js downloads page](https://nodejs.org/en/download/) and download proper Node.js v12 or v14 installer for your OS. An alternative is to install [NVM](https://github.com/nvm-sh/nvm) and use it to have multiple versions of Node.js in your operating system.
+2. **[Optional] Install Yarn:** You may install Yarn v1 (not v2) following the instructions on [the installation page](https://classic.yarnpkg.com/en/docs/install). Yarn v1 delivers an arguably better developer experience compared to npm v6 and below. You may skip this step and work with npm, which is built-in in Node.js, instead.
+3. **[Optional] Install VS Code:** [VS Code](https://code.visualstudio.com/) is a free, open-source IDE which works seamlessly with TypeScript. Although you can use any IDE including Visual Studio or Rider, VS Code will most likely deliver the best developer experience when it comes to Angular projects. ABP project templates even contain plugin recommendations for VS Code users, which VS Code will ask you to install when you open the Angular project folder. Here is a list of recommended extensions:
+ - [Angular Language Service](https://marketplace.visualstudio.com/items?itemName=angular.ng-template)
+ - [Prettier - Code formatter](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)
+ - [TSLint](https://marketplace.visualstudio.com/items?itemName=ms-vscode.vscode-typescript-tslint-plugin)
+ - [Visual Studio IntelliCode](https://marketplace.visualstudio.com/items?itemName=visualstudioexptteam.vscodeintellicode)
+ - [Path Intellisense](https://marketplace.visualstudio.com/items?itemName=christian-kohler.path-intellisense)
+ - [npm Intellisense](https://marketplace.visualstudio.com/items?itemName=christian-kohler.npm-intellisense)
+ - [Angular 10 Snippets - TypeScript, Html, Angular Material, ngRx, RxJS & Flex Layout](https://marketplace.visualstudio.com/items?itemName=Mikael.Angular-BeastCode)
+ - [JavaScript (ES6) code snippets](https://marketplace.visualstudio.com/items?itemName=xabikos.JavaScriptSnippets)
+ - [Debugger for Chrome](https://marketplace.visualstudio.com/items?itemName=msjsdiag.debugger-for-chrome)
+ - [Git History](https://marketplace.visualstudio.com/items?itemName=donjayamanne.githistory)
+ - [indent-rainbow](https://marketplace.visualstudio.com/items?itemName=oderwat.indent-rainbow)
+
+## How to Start a New Angular Project
+
+You have multiple options to initiate a new Angular project that works with ABP:
+
+### 1. Using ABP CLI
+
+ABP CLI is probably the most convenient and flexible way to initiate an ABP solution with an Angular frontend. Simply [install the ABP CLI](../../CLI.md) and run the following command in your terminal:
+
+```shell
+abp new MyCompanyName.MyProjectName -csf -u angular
+```
+
+> To see further options in the CLI, please visit the [CLI manual](../../CLI.md).
+
+This command will prepare a solution with an Angular and a .NET Core project in it. Please visit [Getting Started section](../../Getting-Started.md?UI=NG&DB=EF&Tiered=No#abp-cli-commands-options) for further instructions on how to set up the backend of your solution.
+
+To continue reading without checking other methods, visit [Angular project structure section](#angular-project-structure).
+
+### 2. Direct Download
+
+You may [download a solution scaffold directly on ABP.io](https://abp.io/get-started) if you are more comfortable with GUI or simply want to try ABP without installing the CLI.
+
+Please do the following:
+
+1. Click on the "DIRECT DOWNLOAD" tab.
+2. Fill out the short form about your project.
+3. Click on the "Create now" button.
+
+...and a customized download will start in a few seconds.
+
+To avoid IDE warnings, run `yarn` or `npm install` in the Angular root folder before you continue to the next section. It is not imperative but recommended.
+
+## Angular Project Structure
+
+After creating a solution, open its "angular" directory in your IDE. This is how the contents of the root folder looks like:
+
+
+
+Here is what these folders and files are for:
+
+- **.vscode** has extension recommendations in it.
+- **e2e** is a separate app for possible end-to-end tests.
+- **src** is where the source files for your application are placed. We will have a closer look in a minute.
+- **.browserlistrc** helps [configuring browser compatibility of your Angular app](https://angular.io/guide/build#configuring-browser-compatibility).
+- **.editorconfig** helps you have a shared coding style for separate editors and IDEs. Check [EditorConfig.org](https://editorconfig.org/) for details.
+- **.gitignore** defined which files and folders should not be tracked by git. Check [git documentation](https://git-scm.com/docs/gitignore) for details.
+- **.prettierrc** includes simple coding style choices for [Prettier](https://prettier.io/), an auto-formatter for TypeScript, HTML, CSS, and more. If you install recommended extensions to VS Code, you will never have to format your code anymore.
+- **angular.json** is where Angular workspace is defined. It holds project configurations and workspace preferences. Please refer to [Angular workspace configuration](https://angular.io/guide/workspace-config) for details.
+- **karma.conf.js** holds [Karma test runner](https://karma-runner.github.io/) configurations.
+- **package.json** is where your [package dependencies](https://angular.io/guide/npm-packages) are listed. It also includes some useful scripts for developing, testing, and building your application.
+- **README.md** includes some of Angular CLI command examples. You either have to install Angular CLI globally or run these commands starting with `yarn` or `npx` to make them work.
+- **start.ps1** is a simple PowerShell script to install dependencies and start a [development server via Angular CLI](https://angular.io/cli/serve), but you probably will not need that after reading this document.
+- **tsconfig.json** and all other [tsconfig files](https://angular.io/guide/typescript-configuration) in general, include some TypeScript and Angular compile options.
+- **yarn.lock** enables installing consistent package versions across different devices so that working application build will not break because of a package update. Please read [Yarn documentation](https://classic.yarnpkg.com/en/docs/yarn-lock/) if you are interested in more information on the topic. If you have decided to use npm, please remove this file and keep the [package-lock.json](https://docs.npmjs.com/files/package-lock.json) instead.
+
+Now let us take a look at the contents of the source folder.
+
+
+
+- **app** is the main directory you put your application files in. Any module, component, directive, service, pipe, guard, interceptor, etc. should be placed here. You are free to choose any folder structure, but [organizing Angular applications based on modules](https://angular.io/guide/module-types) is generally a fine practice.
+- **home** is a predefined module and acts as a welcome page. It also demonstrates how a feature-based folder structure may look like. More complex features will probably have sub-features, thus inner folders. You may change the home folder however you like.
+- **shared** is spared for reusable code that works for several modules. Some, including yours truly, may disagree with using a single module for all shared code, so consider adding standalone sub-modules inside this folder instead of adding everything into **shared.module.ts**.
+- **app-routing.module.ts** is where your top-level routes are defined. Angular is capable of [lazy loading feature modules](https://angular.io/guide/lazy-loading-ngmodules), so not all routes will be here. You may think of Angular routing as a tree and this file is the top of the tree.
+- **app.component.ts** is essentially the top component that holds the dynamic application layout.
+- **app.module.ts** is the [root module](https://angular.io/guide/bootstrapping) that includes information about how parts of your application are related and what to run at the initiation of your application.
+- **route.provider.ts** is used for [modifying the menu](https://docs.abp.io/en/abp/latest/UI/Angular/Modifying-the-Menu).
+- **assets** is for static files. A file (e.g. an image) placed in this folder will be available as is when the application is served.
+- **environments** includes one file per environment configuration. There are two configurations by default, but you may always introduce another one. These files are directly referred to in _angular.json_ and help you have different builds and application variables. Please refer to [configuring Angular application environments](https://angular.io/guide/build#configuring-application-environments) for details.
+- **index.html** is the HTML page served to visitors and will contain everything required to run your application. Servers should be configured to redirect every request to this page so that the Angular router can take over. Do not worry about how to add JavaScript and CSS files to it, because Angular CLI will do it automatically.
+- **main.ts** bootstraps and configures Angular application to run in the browser. It is production-ready, so forget about it.
+- **polyfill.ts** is where you can add polyfills if you want to [support legacy browsers](https://angular.io/guide/browser-support).
+- **style.scss** is the default entry point for application styles. You can change this or add new entry points in _angular.json_.
+- **test.ts** helps the unit test runner discover and bootstrap spec files.
+
+Phew! So many files, right? Yet, **most of them are typically not subject to change** or, even when they are so, the CLI tooling will do the job for you. The main focus should be on the app folder and its content.
+
+Next, we will take a look at the commands used to prepare, build, and serve our application.
+
+## How to Run the Angular Application
+
+Now that you know about the files and folders, we can get the application up and running.
+
+1. Make sure the [database migration is complete](../../Getting-Started?UI=NG&DB=EF&Tiered=No#create-the-database) and the [API is up and running](../../Getting-Started?UI=NG&DB=EF&Tiered=No#run-the-application).
+2. Run `yarn` or `npm install` if you have not already.
+3. Run `yarn start` or `npm start`. The first compilation may take a while. This will start a [live development server](#angular-live-development-server) and launch your default browser in the end.
+4. Visit the browser page that opens after the compilation [1](#f-certificate-error).
+
+
+
+You may modify the behavior of the **start script** (in the package.json file) by changing the parameters passed to the `ng serve` command. For instance, if you do not want a browser window to open next time you run the script, remove `--open` from the end of it. Please check [ng serve documentation](https://angular.io/cli/serve) for all available options.
+
+### Angular Live Development Server
+
+The development server of Angular is based on [Webpack DevServer](https://webpack.js.org/configuration/dev-server/). It tracks changes to source files and syncs the browser window after an incremental re-compilation every time [2](#f-dev-server) you make one. Your experience will be like this:
+
+
+
+Please keep in mind that you should not use this server in production. To provide the fastest experience, the compiler skips some heavy optimizations and the development server is simply not built for multiple clients. The next section will describe what to do.
+
+---
+
+
+
+1 _If you see the error above when you run the Angular app, your browser might be blocking access to the API because of the self-signed certificate. Visit that address and allow access to it (once). When you see the Swagger interface, you are good to go._ [↩](#a-certificate-error)
+
+2 _Sometimes, depending on the file changed, Webpack may miss the change and cannot reflect it in the browser. For example, tsconfig files are not being tracked. In such a case, please restart the development server._ [↩](#a-dev-server)
+
+---
+
+## How to Build the Angular Application
+
+An Angular application can have multiple [build targets](https://angular.io/guide/glossary#target), i.e. **configurations in angular.json** which define how [Architect](https://angular.io/guide/glossary#architect) will build applications and libraries. Usually, each build configuration has a separate environment variable file. Currently, the project has two: One for development and one for production.
+
+```js
+// this is what environment variables look like
+// can be found at /src/environments/environment.ts
+
+import { Config } from '@abp/ng.core';
+
+const baseUrl = 'http://localhost:4200';
+
+export const environment = {
+ production: false,
+ application: {
+ baseUrl,
+ name: 'MyProjectName',
+ logoUrl: '',
+ },
+ oAuthConfig: {
+ issuer: 'https://localhost:44381',
+ redirectUri: baseUrl,
+ clientId: 'MyProjectName_App',
+ responseType: 'code',
+ scope: 'offline_access MyProjectName',
+ },
+ apis: {
+ default: {
+ url: 'https://localhost:44381',
+ rootNamespace: 'MyCompanyName.MyProjectName',
+ },
+ },
+} as Config.Environment;
+```
+
+When you run the development server, variables defined in _environment.ts_ take effect. Similarly, in production mode, the default environment is replaced by _environment.prod.ts_ and completely different variables become effective. You may even [create a new build configuration](https://angular.io/guide/workspace-config#build-configs) and set [file replacements](https://angular.io/guide/build#configure-target-specific-file-replacements) to use a completely new environment. For now, we will start a production build:
+
+1. Open your terminal and navigate to the root Angular folder.
+2. Run `yarn` or `npm install` if you have not installed dependencies already.
+3. Run `yarn build:prod` or `npm run build:prod`.
+
+
+
+Depending on project size, the compilation may take a few minutes. When it is finished, the compiled output will be placed inside the _/dist_ folder. Voila! You have deployment-ready build artifacts.
+
+> The amount of optimization performed on the source is the main difference between a regular build and a production one. Production builds have a much smaller size and are more performant.
+
+## How to Deploy the Angular Application
+
+Angular web applications run on the browser and require no server except for a [static web server](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/What_is_a_web_server) to deliver files to the client. To see that it works, please make sure the backend application is up and then run the following command in your terminal:
+
+```shell
+# please replace MyProjectName with your project name
+
+npx servor dist/MyProjectName index.html 4200 --browse
+```
+
+This command will download and start a simple static server, a browser window at `http://localhost:4200` will open, and the compiled output of your project will be served.
+
+Of course, you need your application to run on an optimized web server and become available to everyone. This is quite straight-forward:
+
+1. Create a new static web server instance. You can use a service like [Azure App Service](https://azure.microsoft.com/tr-tr/services/app-service/web/), [Firebase](https://firebase.google.com/docs/hosting), [Netlify](https://www.netlify.com/), [Vercel](https://vercel.com/), or even [GitHub Pages](https://angular.io/guide/deployment#deploy-to-github-pages). Another option is maintaining own web server with [NGINX](https://www.nginx.com/), [IIS](https://www.iis.net/), [Apache HTTP Server](https://httpd.apache.org/), or equivalent.
+2. Copy the files from `dist/MyProjectName` [1](#f-dist-folder-name) to a publicly served destination on the server via CLI of the service provider, SSH, or FTP (whichever is available). This step would be defined as a job if you have a CI/CD flow.
+3. [Configure the server](https://angular.io/guide/deployment#server-configuration) to redirect all requests to the _index.html_ file. Some services do that automatically. Others require you [to add a file to the bundle via assets](https://angular.io/guide/workspace-config#assets-configuration) which describes the server how to do the redirections. Occasionally, you may need to do manual configuration.
+
+In addition, you can [deploy your application to certain targets using the Angular CLI](https://angular.io/guide/deployment#automatic-deployment-with-the-cli). Here are some deploy targets:
+
+- [Azure](https://github.com/Azure/ng-deploy-azure#readme)
+- [Firebase](https://github.com/angular/angularfire#readme)
+- [Netlify](https://github.com/ngx-builders/netlify-builder#readme)
+- [Vercel](https://github.com/vercel/ng-deploy-vercel#readme)
+- [GitHub Pages](https://github.com/angular-schule/angular-cli-ghpages/#readme)
+
+---
+
+1 _The compiled output will be placed under `/dist` in a folder by the project name._ [↩](#a-dist-folder-name)
+
+---
+
+## What's Next?
+
+- [Environment Variables](./Environment.md)
diff --git a/docs/en/UI/Angular/Service-Proxies.md b/docs/en/UI/Angular/Service-Proxies.md
index 7dfb2c052c..92c4b01871 100644
--- a/docs/en/UI/Angular/Service-Proxies.md
+++ b/docs/en/UI/Angular/Service-Proxies.md
@@ -1,16 +1,15 @@
## Service Proxies
-It is common to call a REST endpoint in the server from our Angular applications. In this case, we generally create **services** (those have methods for each service method on the server side) and **model objects** (matches to [DTOs](../../Data-Transfer-Objects) in the server side).
+Calling a REST endpoint from Angular applications is common. We usually create **services** matching server-side controllers and **interfaces** matching [DTOs](../../Data-Transfer-Objects) to interact with the server. This often results in manually transforming C# code into TypeScript equivalents and that is unfortunate, if not intolerable.
-In addition to manually creating such server-interacting services, we could use tools like [NSWAG](https://github.com/RicoSuter/NSwag) to generate service proxies for us. But NSWAG has the following problems we've experienced:
+To avoid manual effort, we might use a tool like [NSWAG](https://github.com/RicoSuter/NSwag) that generates service proxies. However, NSWAG has some disadvantages:
-- It generates a **big, single** .ts file which has some problems;
- - It get **too large** when your application grows.
- - It doesn't fit into the **[modular](../../Module-Development-Basics) approach** of the ABP framework.
-- It creates a bit **ugly code**. We want to have a clean code (just like if we write manually).
-- It can not generate the same **method signature** declared in the server side (because swagger.json doesn't exactly reflect the method signature of the backend service). We've created an endpoint that exposes server side method contacts to allow clients generate a better aligned client proxies.
+- It generates **a single .ts file** which gets **too large** as your application grows. Also, this single file does not fit the **[modular](../../Module-Development-Basics) approach** of ABP.
+- To be honest, the generated code is a bit **ugly**. We would like to produce code that looks as if someone wrote it.
+- Since swagger.json **does not reflect the exact method signature** of backend services, NSWAG cannot reflect them on the client-side as well.
+
+ABP introduces an endpoint that exposes server-side method contracts. When the `generate-proxy` command is run, ABP CLI makes an HTTP request to this endpoint and generates better-aligned client proxies in TypeScript. It organizes folders according to namespaces, adds barrel exports, and reflects method signatures in Angular services.
-ABP CLI changes that via the `generate-proxy` command. It automatically generates the client proxies in TypeScript. by creating folders which separated by module names in the `src/app` folder.
Run the following command in the **root folder** of the angular application:
```bash
@@ -19,13 +18,13 @@ abp generate-proxy
The command without any parameters creates proxies only for your own application's services and places them in your default Angular application. There are several parameters you may use to modify this behavior. See the [CLI documentation](../../CLI) for details.
-The generated files will be placed in a folder called `proxy` at the root of target project.
+The generated files will be placed in a folder called `proxy` at the root of the target project.
Each folder will have models, enums, and services defined at related namespace accompanied by a barrel export, i.e. an `index.ts` file for easier imports.
-> The cammand is able to find application/library roots by reading `angular.json` file. Make sure you have either defined your target project as the `defaultProject` or pass the `--target` parameter to the command. This also means that you may have a monorepo workspace.
+> The command can find application/library roots by reading the `angular.json` file. Make sure you have either defined your target project as the `defaultProject` or pass the `--target` parameter to the command. This also means that you may have a monorepo workspace.
### Angular Project Configuration
@@ -74,9 +73,9 @@ export const environment: Config.Environment = {
The `generate-proxy` command generates one service per back-end controller and a method (property with a function value actually) for each action in the controller. These methods call backend APIs via [RestService](./Http-Requests#restservice).
-A variable named `apiName` (available as of v2.4) is defined in each service. `apiName` matches the module's RemoteServiceName. This variable passes to the `RestService` as a parameter at each request. If there is no microservice API defined in the environment, `RestService` uses the default. See [getting a specific API endpoint from application config](./Http-Requests#how-to-get-a-specific-api-endpoint-from-application-config)
+A variable named `apiName` (available as of v2.4) is defined in each service. `apiName` matches the module's `RemoteServiceName`. This variable passes to the `RestService` as a parameter at each request. If there is no microservice API defined in the environment, `RestService` uses the default. See [getting a specific API endpoint from application config](./Http-Requests#how-to-get-a-specific-api-endpoint-from-application-config)
-The `providedIn` property of the services is defined as `'root'`. Therefore there is no need to provide them in a module. You can use them directly by injecting them into constructor as shown below:
+The `providedIn` property of the services is defined as `'root'`. Therefore there is no need to provide them in a module. You can use them directly by injecting them into the constructor as shown below:
```js
import { BookService } from '@proxy/books';
@@ -114,7 +113,7 @@ export class BookComponent implements OnInit {
### Enums
-Enums have always been difficult to populate in the frontend. The `generate-proxy` command genarates enums in a separate file and exports a ready-to-use options constant from the same file. So you can import them as follows:
+Enums have always been difficult to populate in the frontend. The `generate-proxy` command generates enums in a separate file and exports a ready-to-use "options constant" from the same file. So you can import them as follows:
```js
import { bookGenreOptions } from "@proxy/books";
@@ -132,7 +131,7 @@ export class BookComponent implements OnInit {
```
@@ -141,4 +140,4 @@ export class BookComponent implements OnInit {
## What's Next?
-- [HTTP Requests](./Http-Requests)
+- [PWA Configuration](./PWA-Configuration.md)
diff --git a/docs/en/UI/Angular/Settings.md b/docs/en/UI/Angular/Settings.md
new file mode 100644
index 0000000000..f3a5775838
--- /dev/null
+++ b/docs/en/UI/Angular/Settings.md
@@ -0,0 +1,59 @@
+# Settings
+
+You can get settings on the client-side using the [config state service](./Config-State.md) if they are allowed by their setting definition on the server-side.
+
+> This document only explains how settings work in the Angular UI projects. See the [settings document](../../../Settings.md) to understand the ABP setting system.
+
+## Before Use
+
+To use the `ConfigStateService`, you must inject it in your class as a dependency. You do not have to provide the service explicitly, because it is already **provided in root**.
+
+```js
+import { ConfigStateService } from '@abp/ng.core';
+
+@Component({
+ /* class metadata here */
+})
+class DemoComponent {
+ constructor(private config: ConfigStateService) {}
+}
+```
+
+## How to Get a Specific Setting
+
+You can use the `getSetting` method of `ConfigStateService` to get a specific setting from the configuration state. Here is an example:
+
+```js
+// this.config is instance of ConfigStateService
+
+const defaultLang = this.config.getSetting("Abp.Localization.DefaultLanguage");
+// 'en'
+```
+
+### How to Get All Settings From the Store
+
+You can use the `getSettings` method of `ConfigStateService` to obtain all settings as an object where the object properties are setting names and property values are setting values.
+
+```js
+// this.config is instance of ConfigStateService
+
+const settings = this.config.getSettings();
+// all settings as a key value pair
+```
+
+Additionally, the method lets you search settings by **passing a keyword** to it.
+
+```js
+const localizationSettings = this.config.getSettings("Localization");
+/*
+{
+ 'Abp.Localization.DefaultLanguage': 'en'
+}
+*/
+```
+
+Beware though, **settings search is case-sensitive**.
+
+## What's Next?
+
+- [Features](./Features.md)
diff --git a/docs/en/UI/Angular/Subscription-Service.md b/docs/en/UI/Angular/Subscription-Service.md
index 5d920df96e..dee77cbf1e 100644
--- a/docs/en/UI/Angular/Subscription-Service.md
+++ b/docs/en/UI/Angular/Subscription-Service.md
@@ -1,4 +1,4 @@
-# Easy Unsubscription for Your Observables
+# Managing RxJS Subscriptions
`SubscriptionService` is a utility service to provide an easy unsubscription from RxJS observables in Angular components and directives. Please see [why you should unsubscribe from observables on instance destruction](https://angular.io/guide/lifecycle-hooks#cleaning-up-on-instance-destruction).
@@ -200,4 +200,4 @@ class DemoComponent implements OnInit {
## What's Next?
-- [ListService](./List-Service.md)
+- [Working with Lists](./List-Service.md)
diff --git a/docs/en/UI/Angular/Toaster-Service.md b/docs/en/UI/Angular/Toaster-Service.md
index faa5632ab8..4d94b8cf6d 100644
--- a/docs/en/UI/Angular/Toaster-Service.md
+++ b/docs/en/UI/Angular/Toaster-Service.md
@@ -67,7 +67,7 @@ With the options above, the toast overlay looks like this:
-### How to Remove a Toast Overlay
+### How to Remove a Toast Overlay
The open toast overlay can be removed manually via the `remove` method by passing the `id` of toast:
@@ -85,7 +85,103 @@ The all open toasts can be removed manually via the `clear` method:
```js
this.toaster.clear();
```
+## Replacing ToasterService with 3rd party toaster libraries
+If you want the ABP Framework to utilize 3rd party libraries for the toasters instead of the built-in one, you can provide a service that implements `Toaster.Service` interface, and provide it as follows (ngx-toastr library used in example):
+
+> You can use *LocalizationService* for toaster messages translations.
+```js
+// your-custom-toaster.service.ts
+import { Injectable } from '@angular/core';
+import { Config, LocalizationService } from '@abp/ng.core';
+import { Toaster } from '@abp/ng.theme.shared';
+import { ToastrService } from 'ngx-toastr';
+
+@Injectable()
+export class CustomToasterService implements Toaster.Service {
+ constructor(private toastr: ToastrService, private localizationService: LocalizationService) {}
+
+ error(
+ message: Config.LocalizationParam,
+ title?: Config.LocalizationParam,
+ options?: Partial
+
+
+
+
+````
+
+You can continue to use this approach if you need or prefer it. However, ABP Form tag helpers can produce the same output with a minimal code.
+
+## ABP Dynamic Forms
+
+[abp-dynamic-form](Tag-Helpers/Dynamic-Forms.md) tag helper completely automates the form creation. Take this model class as an example:
+
+```csharp
+using System;
+using System.ComponentModel.DataAnnotations;
+using Volo.Abp.AspNetCore.Mvc.UI.Bootstrap.TagHelpers.Form;
+
+namespace MyProject.Web.Pages
+{
+ public class MovieViewModel
+ {
+ [Required]
+ [StringLength(256)]
+ public string Name { get; set; }
+
+ [Required]
+ [DataType(DataType.Date)]
+ public DateTime ReleaseDate { get; set; }
+
+ [Required]
+ [TextArea]
+ [StringLength(1000)]
+ public string Description { get; set; }
+
+ public Genre Genre { get; set; }
+
+ public float? Price { get; set; }
+
+ public bool PreOrder { get; set; }
+ }
+}
+```
+
+It uses the data annotation attributes to define validation rules and UI styles for the properties. `Genre`, is an `enum` in this example:
+
+````csharp
+namespace MyProject.Web.Pages
+{
+ public enum Genre
+ {
+ Classic,
+ Action,
+ Fiction,
+ Fantasy,
+ Animation
+ }
+}
+````
+
+In order to create the form in a razor page, create a property in your `PageModel` class:
+
+```csharp
+using System.Threading.Tasks;
+using Microsoft.AspNetCore.Mvc;
+using Microsoft.AspNetCore.Mvc.RazorPages;
+
+namespace MyProject.Web.Pages
+{
+ public class CreateMovieModel : PageModel
+ {
+ [BindProperty]
+ public MovieViewModel Movie { get; set; }
+
+ public void OnGet()
+ {
+ Movie = new MovieViewModel();
+ }
+
+ public async Task OnPostAsync()
+ {
+ if (ModelState.IsValid)
+ {
+ //TODO: Save the Movie
+ }
+ }
+ }
+}
+```
+
+Then you can render the form in the `.cshtml` file:
+
+```html
+@page
+@model MyProject.Web.Pages.CreateMovieModel
+
+Create a new Movie
+ +Create a new Movie
+ + +``` + +> See the [ABP Form Tag Helpers](Tag-Helpers/Form-elements.md) document for details of these tag helpers and their options. + +## Validation & Localization + +Both of the Dynamic Form and the Form Tag Helpers **automatically validate** the input based on the data annotation attributes and shows validation error messages on the user interface. Error messages are **automatically localized** based on the current culture. + +**Example: User leaves empty a required string property** + + + +The error message below is shown if the language is French: + + + +Validation errors are already [translated](https://github.com/abpframework/abp/tree/dev/framework/src/Volo.Abp.Validation/Volo/Abp/Validation/Localization) a lot of languages. You can [contribute](../../Contribution/Index.md) to the translation for your own language or override the texts for your own application by following the [localization](../../Localization.md) documentation. + +## Display Name Localization + +ABP Framework uses the property name as the field name on the user interface. You typically want to [localize](../../Localization.md) this name based on the current culture. + +ABP Framework can conventionally localize the fields on the UI when you add the localization keys to the localization JSON files. + +Example: French localization for the *Name* property (add into the `fr.json` in the application): + +````js +"Name": "Nom" +```` + +Then the UI will use the given name for French language: + + + +### Using the `DisplayName:` Prefix + +Directly using the property name as the localization key may be a problem if you need to use the property name for other purpose, which a different translation value. In this case, use the `DisplayName:` prefix for the localization key: + +````js +"DisplayName:Name": "Nom" +```` + +ABP prefers to use the `DisplayName:Name` key over the `Name` key if it does exists. + +### Using a Custom Localization Key + +If you need, you can use the `[DisplayName]` attribute to specify the localization key for a specific property: + +````csharp +[DisplayName("MyNameKey")] +public string Name { get; set; } +```` + +In this case, you can add an entry to the localization file using the key `MyNameKey`. + +> If you use the `[DisplayName]` but not add a corresponding entity to the localization file, then ABP Framework shows the given key as the field name, `MyNameKey` for this case. So, it provides a way to specify a hard coded display name even if you don't need to use the localization system. + +## See Also + +* [Server Side Validation](../../Validation.md) diff --git a/docs/en/UI/AspNetCore/JavaScript-API/Ajax.md b/docs/en/UI/AspNetCore/JavaScript-API/Ajax.md new file mode 100644 index 0000000000..dca3105b5c --- /dev/null +++ b/docs/en/UI/AspNetCore/JavaScript-API/Ajax.md @@ -0,0 +1,150 @@ +# ASP.NET Core MVC / Razor Pages UI JavaScript AJAX API + +`abp.ajax` API provides a convenient way of performing AJAX calls to the server. It internally uses JQuery's `$.ajax`, but automates some common tasks for you; + +* Automatically **handles & localize the errors** and informs the user (using the [abp.message](Message.md)). So you typically don't care about errors. +* Automatically adds **anti forgery** token to the HTTP header to satisfy CSRF protection validation on the server side. +* Automatically sets **default options** and allows to configure the defaults in a single place. +* Can **block** a UI part (or the full page) during the AJAX operation. +* Allows to fully customize any AJAX call, by using the standard `$.ajax` **options**. + +> While `abp.ajax` makes the AJAX call pretty easier, you typically will use the [Dynamic JavaScript Client Proxy](Dynamic-JavaScript-Client-Proxies.md) system to perform calls to your server side HTTP APIs. `abp.ajax` can be used when you need to perform low level AJAX operations. + +## Basic Usage + +`abp.ajax` accepts an options object that is accepted by the standard [$.ajax](https://api.jquery.com/jquery.ajax/#jQuery-ajax-settings). All the standard options are valid. It returns a [promise](https://api.jquery.com/category/deferred-object/) as the return value. + +**Example: Get the list of users** + +````js +abp.ajax({ + type: 'GET', + url: '/api/identity/users' +}).then(function(result){ + console.log(result); +}); +```` + +This command logs the list of users to the console, if you've **logged in** to the application and have [permission](../../../Authorization.md) for the user management page of the [Identity Module](../../../Modules/Identity.md). + +## Error Handling + +The example AJAX call above shows an **error message** if you haven't login to the application or you don't have the necessary permissions to perform this request: + + + +All kinds of errors are automatically handled by `abp.ajax`, unless you want to disable it. + +### Standard Error Response + +`abp.ajax` is compatible with the [exception handling system](../../../Exception-Handling.md) of the ABP Framework and it properly handles the standard error format returned from the server. A typical error message is a JSON as like below: + +````json +{ + "error": { + "code": "App:010042", + "message": "This topic is locked and can not add a new message", + "details": "A more detailed info about the error..." + } +} +```` + +The error message is directly shown to the user, using the `message` and `details` properties. + +### Non-Standard Error Response & HTTP Status Codes + +It also handles errors even if the standard error format was not sent by the server. This can be case if you bypass the ABP exception handling system and manually build the HTTP response on the server. In that case, **HTTP status codes** are considered. + +The following HTTP Status Codes are pre-defined; + +* **401**: Shows an error message like "*You should be authenticated (sign in) in order to perform this operation*". When the users click the OK button, they are redirected to the home page of the application to make them login again. +* **403**: Shows an error message like "*You are not allowed to perform this operation*". +* **404**: Shows an error message like "*The resource requested could not found on the server*". +* **Others**: Shows a generic error message like "*An error has occurred. Error detail not sent by server*". + +All these messages are localized based on the current user's language. + +### Manually Handling the Errors + +Since `abp.ajax` returns a promise, you can always chain a `.cactch(...)` call to register a callback that is executed if the AJAX request fails. + +**Example: Show an alert if the AJAX request fails** + +````js +abp.ajax({ + type: 'GET', + url: '/api/identity/users' +}).then(function(result){ + console.log(result); +}).catch(function(){ + alert("request failed :("); +}); +```` + +While your callback is fired, ABP still handles the error itself. If you want to disable automatic error handling, pass `abpHandleError: false` the the `abp.ajax` options. + +**Example: Disable the auto error handling** + +````js +abp.ajax({ + type: 'GET', + url: '/api/identity/users', + abpHandleError: false //DISABLE AUTO ERROR HANDLING +}).then(function(result){ + console.log(result); +}).catch(function(){ + alert("request failed :("); +}); +```` + +If you set `abpHandleError: false` and don't catch the error yourself, then the error will be hidden and the request silently fails. `abp.ajax` still logs the error to the browser console (see the *Configuration* section to override it). + +## Configuration + +`abp.ajax` has a **global configuration** that you can customize based on your requirements. + +### Default AJAX Options + +`abp.ajax.defaultOpts` object is used to configure default options used while performing an AJAX call, unless you override them. Default value of this object is shown below: + +````js +{ + dataType: 'json', + type: 'POST', + contentType: 'application/json', + headers: { + 'X-Requested-With': 'XMLHttpRequest' + } +} +```` + +So, if you want to change the default request type, you can do it as shown below: + +````js +abp.ajax.defaultOpts.type = 'GET'; +```` + +Write this code before all of your JavaScript code. You typically want to place such a configuration into a separate JavaScript file and add it to the layout using the global [bundle](../Bundling-Minification.md). + +### Log/Show Errors + +The following functions can be overridden to customize the logging and showing the error messages: + +* `abp.ajax.logError` function logs errors using the [abp.log.error(...)](Logging.md) by default. +* `abp.ajax.showError` function shows the error message using the [abp.message.error(...)](Message.md) by default. +* `abp.ajax.handleErrorStatusCode` handles different HTTP status codes and shows different messages based on the code. +* `abp.ajax.handleAbpErrorResponse` handles the errors sent with the standard ABP error format. +* `abp.ajax.handleNonAbpErrorResponse` handles the non-standard error responses. +* `abp.ajax.handleUnAuthorizedRequest` handles responses with `401` status code and redirect users to the home page of the application. + +**Example: Override the `logError` function** + +````js +abp.ajax.logError = function(error) { + //... +} +```` + +### Other Options + +* `abp.ajax.ajaxSendHandler` function is used to intercept the AJAX requests and add antiforgery token to the HTTP header. Note that this works for all AJAX requests, even if you don't use the `abp.ajax`. \ No newline at end of file diff --git a/docs/en/UI/AspNetCore/JavaScript-API/Auth.md b/docs/en/UI/AspNetCore/JavaScript-API/Auth.md new file mode 100644 index 0000000000..45af8c4b3e --- /dev/null +++ b/docs/en/UI/AspNetCore/JavaScript-API/Auth.md @@ -0,0 +1,24 @@ +# ASP.NET Core MVC / Razor Pages UI: JavaScript Auth API + +Auth API allows you to check permissions (policies) for the current user in the client side. In this way, you can conditionally show/hide UI parts or perform your client side logic based on the current permissions. + +> This document only explains the JavaScript API. See the [authorization document](../../../Authorization.md) to understand the ABP authorization & permission system. + +## Basic Usage + +`abp.auth.isGranted(...)` function is used to check if a permission/policy has granted or not: + +````js +if (abp.auth.isGranted('DeleteUsers')) { + //TODO: Delete the user +} else { + alert("You don't have permission to delete a user!"); +} +```` + +## Other Fields & Functions + +* ` abp.auth.isAnyGranted(...)`: Gets one or more permission/policy names and returns `true` if at least one of them has granted. +* `abp.auth.areAllGranted(...)`: Gets one or more permission/policy names and returns `true` if all of them of them have granted. +* `abp.auth.policies`: This is an object where its keys are the permission/policy names. You can find all permission/policy names here. +* `abp.auth.grantedPolicies`: This is an object where its keys are the permission/policy names. You can find the granted permission/policy names here. \ No newline at end of file diff --git a/docs/en/UI/AspNetCore/JavaScript-API/Block-Busy.md b/docs/en/UI/AspNetCore/JavaScript-API/Block-Busy.md new file mode 100644 index 0000000000..943a651432 --- /dev/null +++ b/docs/en/UI/AspNetCore/JavaScript-API/Block-Busy.md @@ -0,0 +1,56 @@ +# ASP.NET Core MVC / Razor Pages UI: JavaScript UI Block/Busy API + +UI Block API disables (blocks) the page or a part of the page. + +## Basic Usage + +**Example: Block (disable) the complete page** + +````js +abp.ui.block(); +```` + +**Example: Block (disable) an HTML element** + +````js +abp.ui.block('#MyContainer'); +```` + +**Example: Enables the previously blocked element or page:** + +````js +abp.ui.unblock(); +```` + +## Options + +`abp.ui.block()` method can get an options object which may contain the following fields: + +* `elm`: An optional selector to find the element to be blocked (e.g. `#MyContainerId`). If not provided, the entire page is blocked. The selector can also be directly passed to the `block()` method as shown above. +* `busy`: Set to `true` to show a progress indicator on the blocked area. +* `promise`: A promise object with `always` or `finally` callbacks. This can be helpful if you want to automatically unblock the blocked area when a deferred operation completes. + +**Example: Block an element with busy indicator** + +````js +abp.ui.block({ + elm: '#MySection', + busy: true +}); +```` + +The resulting UI will look like below: + + + +## setBusy + +`abp.ui.setBusy(...)` and `abp.ui.clearBusy()` are shortcut functions if you want to use the block with `busy` option. + +**Example: Block with busy** + +````js +abp.ui.setBusy('#MySection'); +```` + +Then you can use `abp.ui.clearBusy();` to re-enable the busy area/page. \ No newline at end of file diff --git a/docs/en/UI/AspNetCore/JavaScript-API/CurrentUser.md b/docs/en/UI/AspNetCore/JavaScript-API/CurrentUser.md new file mode 100644 index 0000000000..038bb9dff1 --- /dev/null +++ b/docs/en/UI/AspNetCore/JavaScript-API/CurrentUser.md @@ -0,0 +1,49 @@ +# ASP.NET Core MVC / Razor Pages UI: JavaScript CurrentUser API + +`abp.currentUser` is an object that contains information about the current user of the application. + +> This document only explains the JavaScript API. See the [CurrentUser document](../../../CurrentUser.md) to get information about the current user in the server side. + +## Authenticated User + +If the user was authenticated, this object will be something like below: + +````js +{ + isAuthenticated: true, + id: "34f1f4a7-13cc-4b91-84d1-b91c87afa95f", + tenantId: null, + userName: "john", + name: "John", + surName: "Nash", + email: "john.nash@abp.io", + emailVerified: true, + phoneNumber: null, + phoneNumberVerified: false, + roles: ["moderator","supporter"] +} +```` + +So, `abp.currentUser.userName` returns `john` in this case. + +## Anonymous User + +If the user was not authenticated, this object will be something like below: + +````js +{ + isAuthenticated: false, + id: null, + tenantId: null, + userName: null, + name: null, + surName: null, + email: null, + emailVerified: false, + phoneNumber: null, + phoneNumberVerified: false, + roles: [] +} +```` + +You can check `abp.currentUser.isAuthenticated` to understand if the use was authenticated or not. \ No newline at end of file diff --git a/docs/en/UI/AspNetCore/JavaScript-API/DOM.md b/docs/en/UI/AspNetCore/JavaScript-API/DOM.md new file mode 100644 index 0000000000..cdd4cef9db --- /dev/null +++ b/docs/en/UI/AspNetCore/JavaScript-API/DOM.md @@ -0,0 +1,117 @@ +# ASP.NET Core MVC / Razor Pages UI: JavaScript DOM API + +`abp.dom` (Document Object Model) provides events that you can subscribe to get notified when elements dynamically added to and removed from the page (DOM). + +It is especially helpful if you want to initialize the new loaded elements. This is generally needed when you dynamically add elements to DOM (for example, get some HTML elements via AJAX) after page initialization. + +> ABP uses the [MutationObserver](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver) to observe the changes made on the DOM. + +## Node Events + +### onNodeAdded + +This event is triggered when an element is added to the DOM. Example: + +````js +abp.dom.onNodeAdded(function(args){ + console.log(args.$el); +}); +```` + +`args` object has the following fields; + +* `$el`: The JQuery selection to get the new element inserted to the DOM. + +### onNodeRemoved + +This event is triggered when an element is removed from the DOM. Example: + +````js +abp.dom.onNodeRemoved(function(args){ + console.log(args.$el); +}); +```` + +`args` object has the following fields; + +* `$el`: The JQuery selection to get the element removed from the DOM. + +## Pre-Build Initializers + +ABP Framework is using the DOM events to initialize some kind of HTML elements when they are added to the DOM after than the page was already initialized. + +> Note that the same initializers also work if these elements were already included in the initial DOM. So, whether they are initially or lazy loaded, they work as expected. + +### Form Initializer + +The Form initializer (defined as `abp.dom.initializers.initializeForms`) initializes the lazy loaded forms; + +* Automatically enabled the `unobtrusive` validation on the form. +* Can automatically show a confirmation message when you submit the form. To enable this feature, just add `data-confirm` attribute with a message (like `data-confirm="Are you sure?"`) to the `form` element. +* If the `form` element has `data-ajaxForm="true"` attribute, then automatically calls the `.abpAjaxForm()` on the `form` element, to make the form posted via AJAX. + +See the [Forms & Validation](../Forms-Validation.md) document for more. + +### Script Initializer + +Script initializer (`abp.dom.initializers.initializeScript`) can execute a JavaScript code for a DOM element. + +**Example: Lazy load a component and execute some code when the element has loaded** + +Assume that you've a container to load the element inside: + +````html + +```` + +And this is the component that will be loaded via AJAX from the server and inserted into the container: + +````html +
+
+````
+
+`data-script-class="MyCustomClass"` indicates the JavaScript class that will be used to perform some logic on this element:
+
+`MyCustomClass` is a global object defined as shown below:
+
+````js
+MyCustomClass = function(){
+
+ function initDom($el){
+ $el.css('color', 'red');
+ }
+
+ return {
+ initDom: initDom
+ }
+};
+````
+
+`initDom` is the function that is called by the ABP Framework. The `$el` argument is the loaded HTML element as a JQuery selection.
+
+Finally, you can load the component inside the container after an AJAX call:
+
+````js
+$(function () {
+ setTimeout(function(){
+ $.get('/get-my-element').then(function(response){
+ $('#LazyComponent').html(response);
+ });
+ }, 2000);
+});
+````
+
+Script Initialization system is especially helpful if you don't know how and when the component will be loaded into the DOM. This can be possible if you've developed a reusable UI component in a library and you want the application developer shouldn't care how to initialize the component in different use cases.
+
+> Script initialization doesn't work if the component was loaded in the initial DOM. In this case, you are responsible to initialize it.
+
+### Other Initializers
+
+The following Bootstrap components and libraries are automatically initialized when they are added to the DOM:
+
+* Tooltip
+* Popover
+* Timeage
+
diff --git a/docs/en/UI/AspNetCore/JavaScript-API/Dynamic-JavaScript-Client-Proxies.md b/docs/en/UI/AspNetCore/JavaScript-API/Dynamic-JavaScript-Client-Proxies.md
new file mode 100644
index 0000000000..5270852b60
--- /dev/null
+++ b/docs/en/UI/AspNetCore/JavaScript-API/Dynamic-JavaScript-Client-Proxies.md
@@ -0,0 +1,3 @@
+# ASP.NET Core MVC / Razor Pages UI: Dynamic JavaScript Client Proxies
+
+TODO
\ No newline at end of file
diff --git a/docs/en/UI/AspNetCore/JavaScript-API/Events.md b/docs/en/UI/AspNetCore/JavaScript-API/Events.md
new file mode 100644
index 0000000000..3425355f44
--- /dev/null
+++ b/docs/en/UI/AspNetCore/JavaScript-API/Events.md
@@ -0,0 +1,88 @@
+# ASP.NET Core MVC / Razor Pages UI: JavaScript Events API
+
+`abp.event` object is a simple service that is used to publish and subscribe to global events **in the browser**.
+
+> This API is not related to server side local or distributed events. It works in the browser boundaries to make the UI components (code parts) communicate in a loosely coupled way.
+
+## Basic Usage
+
+### Publishing Events
+
+Use `abp.event.trigger` to publish events.
+
+**Example: Publish a *Basket Updated* event**
+
+````js
+abp.event.trigger('basketUpdated');
+````
+
+This will trigger all the subscribed callbacks.
+
+### Subscribing to the Events
+
+Use `abp.event.on` to subscribe to events.
+
+**Example: Consume the *Basket Updated* event**
+
+````js
+abp.event.on('basketUpdated', function() {
+ console.log('Handled the basketUpdated event...');
+});
+````
+
+You start to get events after you subscribe to the event.
+
+### Unsubscribing from the Events
+
+If you need to unsubscribe from a pre-subscribed event, you can use the `abp.event.off(eventName, callback)` function. In this case, you have the callback as a separate function declaration.
+
+**Example: Subscribe & Unsubscribe**
+
+````js
+function onBasketUpdated() {
+ console.log('Handled the basketUpdated event...');
+}
+
+//Subscribe
+abp.event.on('basketUpdated', onBasketUpdated);
+
+//Unsubscribe
+abp.event.off('basketUpdated', onBasketUpdated);
+````
+
+You don't get events after you unsubscribe from the event.
+
+## Event Arguments
+
+You can pass arguments (of any count) to the `trigger` method and get them in the subscription callback.
+
+**Example: Add the basket as the event argument**
+
+````js
+//Subscribe to the event
+abp.event.on('basketUpdated', function(basket) {
+ console.log('The new basket object: ');
+ console.log(basket);
+});
+
+//Trigger the event
+abp.event.trigger('basketUpdated', {
+ items: [
+ {
+ "productId": "123",
+ "count": 2
+ },
+ {
+ "productId": "832",
+ "count": 1
+ }
+ ]
+});
+````
+
+### Multiple Arguments
+
+If you want to pass multiple arguments, you can pass like `abp.event.on('basketUpdated', arg0, arg1, agr2)`. Then you can add the same argument list to the callback function on the subscriber side.
+
+> **Tip:** Alternatively, you can send a single object that has a separate field for each argument. This makes easier to extend/change the event arguments in the future without breaking the subscribers.
+
diff --git a/docs/en/UI/AspNetCore/JavaScript-API/Features.md b/docs/en/UI/AspNetCore/JavaScript-API/Features.md
new file mode 100644
index 0000000000..8d58347f49
--- /dev/null
+++ b/docs/en/UI/AspNetCore/JavaScript-API/Features.md
@@ -0,0 +1,29 @@
+# ASP.NET Core MVC / Razor Pages UI: JavaScript Features API
+
+`abp.features` API allows you to check features or get the values of the features on the client side. You can read the current value of a feature in the client side only if it is allowed by the feature definition (on the server side).
+
+> This document only explains the JavaScript API. See the [Features](../../../Features.md) document to understand the ABP Features system.
+
+## Basic Usage
+
+````js
+//Gets a value as string.
+var value = abp.features.get('ExportingToExcel');
+
+//Check the feature is enabled
+var enabled = abp.features.isEnabled('ExportingToExcel.Enabled');
+````
+
+## All Values
+
+`abp.features.values` can be used to access to the all feature values.
+
+An example value of this object is shown below:
+
+````js
+{
+ Identity.TwoFactor: "Optional",
+ ExportingToExcel.Enabled: "true",
+ ...
+}
+````
\ No newline at end of file
diff --git a/docs/en/UI/AspNetCore/JavaScript-API/Index.md b/docs/en/UI/AspNetCore/JavaScript-API/Index.md
index 9f584eacfb..3473140392 100644
--- a/docs/en/UI/AspNetCore/JavaScript-API/Index.md
+++ b/docs/en/UI/AspNetCore/JavaScript-API/Index.md
@@ -1,23 +1,19 @@
# JavaScript API
-ABP provides some JavaScript APIs for ASP.NET Core MVC / Razor Pages applications. They can be used to perform some common application requirements in the client side.
+ABP provides a set of JavaScript APIs for ASP.NET Core MVC / Razor Pages applications. They can be used to perform common application requirements easily in the client side and integrate to the server side.
## APIs
-* abp.ajax
-* abp.auth
-* abp.currentUser
-* abp.dom
-* abp.event
-* abp.features
-* abp.localization
-* abp.log
-* abp.ModalManager
-* abp.notify
-* abp.security
-* abp.setting
-* abp.ui
-* abp.utils
-* abp.ResourceLoader
-* abp.WidgetManager
-* Other APIs
\ No newline at end of file
+* [AJAX](Ajax.md)
+* [Auth](Auth.md)
+* [CurrentUser](CurrentUser.md)
+* [DOM](DOM.md)
+* [Events](Events.md)
+* [Features](Features.md)
+* [Localization](Localization.md)
+* [Logging](Logging.md)
+* [ResourceLoader](ResourceLoader.md)
+* [Settings](Settings.md)
+* [UI Block/Busy](Block-Busy.md)
+* [UI Message](Message.md)
+* [UI Notification](Notify.md)
\ No newline at end of file
diff --git a/docs/en/UI/AspNetCore/JavaScript-API/Localization.md b/docs/en/UI/AspNetCore/JavaScript-API/Localization.md
new file mode 100644
index 0000000000..0897b99268
--- /dev/null
+++ b/docs/en/UI/AspNetCore/JavaScript-API/Localization.md
@@ -0,0 +1,143 @@
+# ASP.NET Core MVC / Razor Pages UI: JavaScript Localization API
+
+Localization API allows you to reuse the server side localization resources in the client side.
+
+> This document only explains the JavaScript API. See the [localization document](../../../Localization.md) to understand the ABP localization system.
+
+## Basic Usage
+
+`abp.localization.getResource(...)` function is used to get a localization resource:
+
+````js
+var testResource = abp.localization.getResource('Test');
+````
+
+Then you can localize a string based on this resource:
+
+````js
+var str = testResource('HelloWorld');
+````
+
+`abp.localization.localize(...)` function is a shortcut where you can both specify the text name and the resource name:
+
+````js
+var str = abp.localization.localize('HelloWorld', 'Test');
+````
+
+`HelloWorld` is the text to localize, where `Test` is the localization resource name here.
+
+### Fallback Logic
+
+If given texts was not localized, localization method returns the given key as the localization result.
+
+### Default Localization Resource
+
+If you don't specify the localization resource name, it uses the **default localization resource** defined on the `AbpLocalizationOptions` (see the [localization document](../../../Localization.md)).
+
+**Example: Using the default localization resource**
+
+````js
+var str = abp.localization.localize('HelloWorld'); //uses the default resource
+````
+
+### Format Arguments
+
+If your localized string contains arguments, like `Hello {0}, welcome!`, you can pass arguments to the localization methods. Examples:
+
+````js
+var testSource = abp.localization.getResource('Test');
+var str1 = testSource('HelloWelcomeMessage', 'John');
+var str2 = abp.localization.localize('HelloWelcomeMessage', 'Test', 'John');
+````
+
+Assuming the `HelloWelcomeMessage` is localized as `Hello {0}, welcome!`, both of the samples above produce the output `Hello John, welcome!`.
+
+## Other Properties & Methods
+
+### abp.localization.values
+
+`abp.localization.values` property stores all the localization resources, keys and their values.
+
+### abp.localization.isLocalized
+
+Returns a boolean indicating that if the given text was localized or not.
+
+**Example**
+
+````js
+abp.localization.isLocalized('ProductName', 'MyResource');
+````
+
+Returns `true` if the `ProductName` text was localized for the `MyResource` resource. Otherwise, returns `false`. You can leave the resource name empty to use the default localization resource.
+
+### abp.localization.defaultResourceName
+
+`abp.localization.defaultResourceName` can be set to change the default localization resource. You normally don't set this since the ABP Framework automatically sets is based on the server side configuration.
+
+### abp.localization.currentCulture
+
+`abp.localization.currentCulture` returns an object to get information about the **currently selected language**.
+
+An example value of this object is shown below:
+
+````js
+{
+ "displayName": "English",
+ "englishName": "English",
+ "threeLetterIsoLanguageName": "eng",
+ "twoLetterIsoLanguageName": "en",
+ "isRightToLeft": false,
+ "cultureName": "en",
+ "name": "en",
+ "nativeName": "English",
+ "dateTimeFormat": {
+ "calendarAlgorithmType": "SolarCalendar",
+ "dateTimeFormatLong": "dddd, MMMM d, yyyy",
+ "shortDatePattern": "M/d/yyyy",
+ "fullDateTimePattern": "dddd, MMMM d, yyyy h:mm:ss tt",
+ "dateSeparator": "/",
+ "shortTimePattern": "h:mm tt",
+ "longTimePattern": "h:mm:ss tt"
+ }
+}
+````
+
+### abp.localization.languages
+
+Used to get list of all **available languages** in the application. An example value of this object is shown below:
+
+````js
+[
+ {
+ "cultureName": "en",
+ "uiCultureName": "en",
+ "displayName": "English",
+ "flagIcon": null
+ },
+ {
+ "cultureName": "fr",
+ "uiCultureName": "fr",
+ "displayName": "Français",
+ "flagIcon": null
+ },
+ {
+ "cultureName": "pt-BR",
+ "uiCultureName": "pt-BR",
+ "displayName": "Português",
+ "flagIcon": null
+ },
+ {
+ "cultureName": "tr",
+ "uiCultureName": "tr",
+ "displayName": "Türkçe",
+ "flagIcon": null
+ },
+ {
+ "cultureName": "zh-Hans",
+ "uiCultureName": "zh-Hans",
+ "displayName": "简体中文",
+ "flagIcon": null
+ }
+]
+````
+
diff --git a/docs/en/UI/AspNetCore/JavaScript-API/Logging.md b/docs/en/UI/AspNetCore/JavaScript-API/Logging.md
new file mode 100644
index 0000000000..a46203b019
--- /dev/null
+++ b/docs/en/UI/AspNetCore/JavaScript-API/Logging.md
@@ -0,0 +1,50 @@
+# ASP.NET Core MVC / Razor Pages UI: JavaScript Logging API
+
+`abp.log` API is used to write simple logs in the client side.
+
+> The logs are written to console, using the `console.log`, by default.
+
+> This document is for simple client side logging. See the [Logging](../../../Logging.md) document for server side logging system.
+
+## Basic Usage
+
+Use one of the `abp.log.xxx(...)` methods based on the severity of your log message.
+
+````js
+abp.log.debug("Some debug log here..."); //Logging a simple debug message
+abp.log.info({ name: "john", age: 42 }); //Logging an object as an information log
+abp.log.warn("A warning message"); //Logging a warning message
+abp.log.error('An error happens...'); //Error message
+abp.log.fatal('Network connection has gone away!'); //Fatal error
+````
+
+## Log Levels
+
+There are 5 levels for a log message:
+
+* DEBUG = 1
+* INFO = 2
+* WARN = 3
+* ERROR = 4
+* FATAL = 5
+
+These are defined in the `abp.log.levels` object (like `abp.log.levels.WARN`).
+
+### Changing the Current Log Level
+
+You can control the log level as shown below:
+
+````js
+abp.log.level = abp.log.levels.WARN;
+````
+
+Default log level is `DEBUG`.
+
+### Logging with Specifying the Level
+
+Instead of calling `abp.log.info(...)` function, you can use the `abp.log.log` by specifying the log level as a parameter:
+
+````js
+abp.log.log("log message...", abp.log.levels.INFO);
+````
+
diff --git a/docs/en/UI/AspNetCore/JavaScript-API/Message.md b/docs/en/UI/AspNetCore/JavaScript-API/Message.md
new file mode 100644
index 0000000000..68c74914c6
--- /dev/null
+++ b/docs/en/UI/AspNetCore/JavaScript-API/Message.md
@@ -0,0 +1,128 @@
+# ASP.NET Core MVC / Razor Pages UI: JavaScript Message API
+
+Message API is used to show nice looking messages to the user as a blocking dialog. Message API is an abstraction provided by the ABP Framework and implemented using the [SweetAlert2](https://sweetalert2.github.io/) library by default.
+
+## Quick Example
+
+Use `abp.message.success(...)` function to show a success message:
+
+````js
+abp.message.success('Your changes have been successfully saved!', 'Congratulations');
+````
+
+It will show a dialog on the UI:
+
+
+
+## Informative Messages
+
+There are four types of informative message functions:
+
+* `abp.message.info(...)`
+* `abp.message.success(...)`
+* `abp.message.warn(...)`
+* `abp.message.error(...)`
+
+All these methods get two parameters:
+
+* `message`: The message (`string`) to be shown.
+* `title`: An optional (`string`) title.
+
+**Example: Show an error message**
+
+````js
+abp.message.error('Your credit card number is not valid!');
+````
+
+
+
+## Confirmation Message
+
+`abp.message.confirm(...)` function can be used to get a confirmation from the user.
+
+**Example**
+
+Use the following code to get a confirmation result from the user:
+
+````js
+abp.message.confirm('Are you sure to delete the "admin" role?')
+.then(function(confirmed){
+ if(confirmed){
+ console.log('TODO: deleting the role...');
+ }
+});
+````
+
+The resulting UI will be like shown below:
+
+
+
+If user has clicked the `Yes` button, the `confirmed` argument in the `then` callback function will be `true`.
+
+> "*Are you sure?*" is the default title (localized based on the current language) and you can override it.
+
+### The Return Value
+
+The return value of the `abp.message.confirm(...)` function is a promise, so you can chain a `then` callback as shown above.
+
+### Parameters
+
+`abp.message.confirm(...)` function has the following parameters:
+
+* `message`: A message (string) to show to the user.
+* `titleOrCallback` (optional): A title or a callback function. If you supply a string, it is shown as the title. If you supply a callback function (that gets a `bool` parameter) then it's called with the result.
+* `callback` (optional): If you've passes a title to the second parameter, you can pass your callback function as the 3rd parameter.
+
+Passing a callback function is an alternative to the `then` callback shown above.
+
+**Example: Providing all the parameters and getting result with the callback function**
+
+````js
+abp.message.confirm(
+ 'Are you sure to delete the "admin" role?',
+ 'Be careful!',
+ function(confirmed){
+ if(confirmed){
+ console.log('TODO: deleting the role...');
+ }
+ });
+````
+
+## SweetAlert Configuration
+
+The Message API is implemented using the [SweetAlert2](https://sweetalert2.github.io/) library by default. If you want to change its configuration, you can set the options in the `abp.libs.sweetAlert.config` object. The default configuration object is shown below:
+
+````js
+{
+ 'default': {
+ },
+ info: {
+ icon: 'info'
+ },
+ success: {
+ icon: 'success'
+ },
+ warn: {
+ icon: 'warning'
+ },
+ error: {
+ icon: 'error'
+ },
+ confirm: {
+ icon: 'warning',
+ title: 'Are you sure?',
+ buttons: ['Cancel', 'Yes']
+ }
+}
+````
+
+> "Are you sure?", "Cancel" and "Yes" texts are automatically localized based on the current language.
+
+So, if you want to set the `warn` icon, you can set it like:
+
+````js
+abp.libs.sweetAlert.config.warn.icon = 'error';
+````
+
+See the [SweetAlert document](https://sweetalert2.github.io/) for all the configuration options.
+
diff --git a/docs/en/UI/AspNetCore/JavaScript-API/Notify.md b/docs/en/UI/AspNetCore/JavaScript-API/Notify.md
new file mode 100644
index 0000000000..371aa8d4b9
--- /dev/null
+++ b/docs/en/UI/AspNetCore/JavaScript-API/Notify.md
@@ -0,0 +1,45 @@
+# ASP.NET Core MVC / Razor Pages UI: JavaScript Notify API
+
+Notify API is used to show toast style, auto disappearing UI notifications to the end user. It is implemented by the [Toastr](https://github.com/CodeSeven/toastr) library by default.
+
+## Quick Example
+
+Use `abp.notify.success(...)` function to show a success message:
+
+````js
+abp.notify.success(
+ 'The product "Acme Atom Re-Arranger" has been successfully deleted.',
+ 'Deleted the Product'
+);
+````
+
+A notification message is shown at the bottom right of the page:
+
+
+
+## Notification Types
+
+There are four types of pre-defined notifications;
+
+* `abp.notify.success(...)`
+* `abp.notify.info(...)`
+* `abp.notify.warn(...)`
+* `abp.notify.error(...)`
+
+All of the methods above gets the following parameters;
+
+* `message`: A message (`string`) to show to the user.
+* `title`: An optional title (`string`).
+* `options`: Additional options to be passed to the underlying library, to the Toastr by default.
+
+## Toastr Configuration
+
+The notification API is implemented by the [Toastr](https://github.com/CodeSeven/toastr) library by default. You can see its own configuration options.
+
+**Example: Show toast messages on the top right of the page**
+
+````js
+toastr.options.positionClass = 'toast-top-right';
+````
+
+> ABP sets this option to `toast-bottom-right` by default. You can override it just as shown above.
\ No newline at end of file
diff --git a/docs/en/UI/AspNetCore/JavaScript-API/ResourceLoader.md b/docs/en/UI/AspNetCore/JavaScript-API/ResourceLoader.md
new file mode 100644
index 0000000000..10b8c36f59
--- /dev/null
+++ b/docs/en/UI/AspNetCore/JavaScript-API/ResourceLoader.md
@@ -0,0 +1,40 @@
+# ASP.NET Core MVC / Razor Pages UI: JavaScript Resource Loader API
+
+`abp.ResourceLoader` is a service that can load a JavaScript or CSS file on demand. It guarantees to load the file only once even if you request multiple times.
+
+## Loading Script Files
+
+`abp.ResourceLoader.loadScript(...)` function **loads** a JavaScript file from the server and **executes** it.
+
+**Example: Load a JavaScript file**
+
+````js
+abp.ResourceLoader.loadScript('/Pages/my-script.js');
+````
+
+### Parameters
+
+`loadScript` function can get three parameters;
+
+* `url` (required, `string`): The URL of the script file to be loaded.
+* `loadCallback` (optional, `function`): A callback function that is called once the script is loaded & executed. In this callback you can safely use the code in the script file. This callback is called even if the file was loaded before.
+* `failCallback` (optional, `function`): A callback function that is called if loading the script fails.
+
+**Example: Provide the `loadCallback` argument**
+
+````js
+abp.ResourceLoader.loadScript('/Pages/my-script.js', function() {
+ console.log('successfully loaded :)');
+});
+````
+
+## Loading Style Files
+
+`abp.ResourceLoader.loadStyle(...)` function adds a `link` element to the `head` of the document for the given URL, so the CSS file is automatically loaded by the browser.
+
+**Example: Load a CSS file**
+
+````js
+abp.ResourceLoader.loadStyle('/Pages/my-styles.css');
+````
+
diff --git a/docs/en/UI/AspNetCore/JavaScript-API/Settings.md b/docs/en/UI/AspNetCore/JavaScript-API/Settings.md
new file mode 100644
index 0000000000..cf96cecdd0
--- /dev/null
+++ b/docs/en/UI/AspNetCore/JavaScript-API/Settings.md
@@ -0,0 +1,33 @@
+# ASP.NET Core MVC / Razor Pages UI: JavaScript Setting API
+
+Localization API allows you to get the values of the settings on the client side. You can read the current value of a setting in the client side only if it is allowed by the setting definition (on the server side).
+
+> This document only explains the JavaScript API. See the [settings document](../../../Settings.md) to understand the ABP setting system.
+
+## Basic Usage
+
+````js
+//Gets a value as string.
+var language = abp.setting.get('Abp.Localization.DefaultLanguage');
+
+//Gets an integer value.
+var requiredLength = abp.setting.getInt('Abp.Identity.Password.RequiredLength');
+
+//Gets a boolean value.
+var requireDigit = abp.setting.getBoolean('Abp.Identity.Password.RequireDigit');
+````
+
+## All Values
+
+`abp.setting.values` can be used to obtain all the setting values as an object where the object properties are setting names and property values are the setting values.
+
+An example value of this object is shown below:
+
+````js
+{
+ Abp.Localization.DefaultLanguage: "en",
+ Abp.Timing.TimeZone: "UTC",
+ ...
+}
+````
+
diff --git a/docs/en/UI/AspNetCore/Layout-Hooks.md b/docs/en/UI/AspNetCore/Layout-Hooks.md
index 49b334c6c0..7039749142 100644
--- a/docs/en/UI/AspNetCore/Layout-Hooks.md
+++ b/docs/en/UI/AspNetCore/Layout-Hooks.md
@@ -1,3 +1,105 @@
-# Layout Hooks
+# ASP.NET Core MVC / Razor Pages Layout Hooks
-TODO
\ No newline at end of file
+ABP Framework theming system places the page layout into the [theme](Theming.md) NuGet packages. That means the final application doesn't include a `Layout.cshtml`, so you can't directly change the layout code to customize it.
+
+You copy the theme code into your solution. In this case you are completely free to customize it. However, then you won't be able to get automatic updates of the theme (by upgrading the theme NuGet package).
+
+ABP Framework provides different ways of [customizing the UI](Customization-User-Interface.md).
+
+The **Layout Hook System** allows you to **add code** at some specific parts of the layout. All layouts of all themes should implement these hooks. Finally, you can add a **view component** into a hook point.
+
+## Example: Add Google Analytics Script
+
+Assume that you need to add the Google Analytics script to the layout (that will be available for all the pages). First, **create a view component** in your project:
+
+
+
+**NotificationViewComponent.cs**
+
+````csharp
+public class GoogleAnalyticsViewComponent : AbpViewComponent
+{
+ public IViewComponentResult Invoke()
+ {
+ return View("/Pages/Shared/Components/GoogleAnalytics/Default.cshtml");
+ }
+}
+````
+
+**Default.cshtml**
+
+````html
+
+````
+
+Change `UA-xxxxxx-1` with your own code.
+
+You can then add this component to any of the hook points in the `ConfigureServices` of your module:
+
+````csharp
+ConfigureSample message
+@Model.ProductName
+
+ 
+
+
+ + @Model.ProductDescription +
++ Reference: https://acme.com/catalog/ +
+