diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml new file mode 100644 index 0000000000..e33a07a197 --- /dev/null +++ b/.github/workflows/main.yml @@ -0,0 +1,30 @@ +name: "Main" +on: + pull_request: + paths: + - "framework/**" + - "modules/**" + - "templates/**" + push: + paths: + - "framework/**" + - "modules/**" + - "templates/**" +jobs: + build-test: + runs-on: windows-latest + steps: + - uses: actions/checkout@v2 + - uses: actions/setup-dotnet@master + with: + dotnet-version: 3.1.100 + + - name: Build All + run: .\build-all.ps1 + working-directory: .\build + shell: powershell + + - name: Test All + run: .\test-all.ps1 + working-directory: .\build + shell: powershell diff --git a/abp_io/AbpIoLocalization/AbpIoLocalization/Account/Localization/Resources/ru.json b/abp_io/AbpIoLocalization/AbpIoLocalization/Account/Localization/Resources/ru.json new file mode 100644 index 0000000000..a39240b02e --- /dev/null +++ b/abp_io/AbpIoLocalization/AbpIoLocalization/Account/Localization/Resources/ru.json @@ -0,0 +1,13 @@ +{ + "culture": "ru", + "texts": { + "Account": "Аккаунт", + "Welcome": "Добро пожаловать", + "UseOneOfTheFollowingLinksToContinue": "Для продолжения используйте одну из следующих ссылок", + "FrameworkHomePage": "Главная страница фреймворка", + "FrameworkDocumentation": "Документация фреймворка", + "OfficialBlog": "Официальный блог", + "CommercialHomePage": "Главная страница коммерческой версии", + "CommercialSupportWebSite": "Сайт коммерческой поддержки" + } +} diff --git a/abp_io/AbpIoLocalization/AbpIoLocalization/Admin/Localization/Resources/en.json b/abp_io/AbpIoLocalization/AbpIoLocalization/Admin/Localization/Resources/en.json index 2a27cce735..9e90c427d1 100644 --- a/abp_io/AbpIoLocalization/AbpIoLocalization/Admin/Localization/Resources/en.json +++ b/abp_io/AbpIoLocalization/AbpIoLocalization/Admin/Localization/Resources/en.json @@ -75,7 +75,8 @@ "AddDeveloper": "Add developer", "Create": "Create", "UserNotFound": "User not found", - "{0}WillBeRemovedFromMembers": "{0} Will be removed from members", + "{0}WillBeRemovedFromDevelopers": "{0} Will be removed from developers, do you confirm?", + "{0}WillBeRemovedFromOwners": "{0} Will be removed from owners, do you confirm?", "Computers": "Computers", "UniqueComputerId": "Unique computer id", "LastSeenDate": "Last seen date", diff --git a/abp_io/AbpIoLocalization/AbpIoLocalization/Admin/Localization/Resources/ru.json b/abp_io/AbpIoLocalization/AbpIoLocalization/Admin/Localization/Resources/ru.json new file mode 100644 index 0000000000..38b4e728f8 --- /dev/null +++ b/abp_io/AbpIoLocalization/AbpIoLocalization/Admin/Localization/Resources/ru.json @@ -0,0 +1,90 @@ +{ + "culture": "ru", + "texts": { + "Permission:Organizations": "Организации", + "Permission:Manage": "Управление организациями", + "Permission:NpmPackages": "Пакеты NPM", + "Permission:NugetPackages": "Пакеты NuGet", + "Permission:Maintenance": "Обслуживание", + "Permission:Maintain": "Обслуживать", + "Permission:ClearCaches": "Очистить кэш", + "Permission:Modules": "Модули", + "Permission:Packages": "Пакеты", + "Permission:Edit": "Редактировать", + "Permission:Delete": "Удалить", + "Permission:Create": "Создать", + "Menu:Organizations": "Организации", + "Menu:Packages": "Пакеты", + "NpmPackageDeletionWarningMessage": "Этот пакет NPM будет удален. Вы подтверждаете это?", + "NugetPackageDeletionWarningMessage": "Этот пакет NuGet будет удален. Вы подтверждаете это?", + "ModuleDeletionWarningMessage": "Этот модуль будет удален. Вы подтверждаете это?", + "Name": "Имя", + "DisplayName": "Отображаемое имя", + "ShortDescription": "Краткое описание", + "NameFilter": "Имя", + "CreationTime": "Время создания", + "IsPro": "Is pro", + "EfCoreConfigureMethodName": "Настроить имя метода", + "IsProFilter": "Is pro", + "ApplicationType": "Тип приложения", + "Target": "Цель", + "TargetFilter": "Цель", + "ModuleClass": "Класс модуля", + "NugetPackageTarget.DomainShared": "Domain Shared", + "NugetPackageTarget.Domain": "Domain", + "NugetPackageTarget.Application": "Application", + "NugetPackageTarget.ApplicationContracts": "Application Contracts", + "NugetPackageTarget.HttpApi": "Http Api", + "NugetPackageTarget.HttpApiClient": "Http Api Client", + "NugetPackageTarget.Web": "Web", + "NugetPackageTarget.EntityFrameworkCore": "DeleteAllEntityFramework Core", + "NugetPackageTarget.MongoDB": "MongoDB", + "Edit": "Редактировать", + "Delete": "Удалить", + "Refresh": "Обновить", + "NpmPackages": "NPM пакеты", + "NugetPackages": "NuGet пакеты", + "NpmPackageCount": "Количество пакетов NPM", + "NugetPackageCount": "Количество пакетов NuGet", + "Module": "Модули", + "ModuleInfo": "Информация о модуле", + "CreateANpmPackage": "Создать пакет NPM", + "CreateAModule": "Создать модуль", + "CreateANugetPackage": "Создать пакет NuGet", + "AddNew": "Добавить новый", + "PackageAlreadyExist{0}": "\"{0}\" пакет уже существует.", + "ModuleAlreadyExist{0}": "\"{0}\" модуль уже добавлен.", + "ClearCache": "Очистить кэш", + "SuccessfullyCleared": "Успешно очищено", + "Menu:NpmPackages": "Пакеты NPM", + "Menu:Modules": "Модули", + "Menu:Maintenance": "Поддержка", + "Menu:NugetPackages": "Пакеты NuGet", + "CreateAnOrganization": "Создать организацию", + "Organizations": "Организации", + "LongName": "Полное название", + "LicenseType": "Тип лицензии", + "LicenseStartTime": "Время начала действия лицензии", + "LicenseEndTime": "Время окончания действия лицензии", + "AllowedDeveloperCount": "Разрешенное количество разработчиков", + "UserNameOrEmailAddress": "Имя пользователя или адрес электронной почты", + "AddOwner": "Добавить владельца", + "UserName": "Имя пользователя", + "Email": "Электронная почта", + "Developers": "Разработчики", + "AddDeveloper": "Добавить разработчика", + "Create": "Создать", + "UserNotFound": "Пользователь не обнаружен", + "{0}WillBeRemovedFromMembers": "{0} будет удален из членов", + "Computers": "Компьютеры", + "UniqueComputerId": "Уникальный id компьютера", + "LastSeenDate": "Дата последнего визита", + "{0}Computer{1}WillBeRemovedFromRecords": "Компьютер {0} ({1}) будет удален из записей", + "OrganizationDeletionWarningMessage": "Организация будет удалена", + "This{0}AlreadyExistInThisOrganization": "{0} уже существует в данной организации", + "AreYouSureYouWantToDeleteAllComputers": "Вы уверены, что хотите удалить все компьютеры?", + "DeleteAll": "Удалить все", + "DoYouWantToCreateNewUser": "Вы хотите создать нового пользователя?", + "MasterModules": "Мастер модулей" + } +} diff --git a/common.props b/common.props index a6d559c52c..19b6f81fe6 100644 --- a/common.props +++ b/common.props @@ -1,7 +1,7 @@ latest - 2.6.0 + 2.7.0 $(NoWarn);CS1591 https://abp.io/assets/abp_nupkg.png https://abp.io diff --git a/docs/en/Customizing-Application-Modules-Extending-Entities.md b/docs/en/Customizing-Application-Modules-Extending-Entities.md index dcfe30c019..a7c3f4e7cd 100644 --- a/docs/en/Customizing-Application-Modules-Extending-Entities.md +++ b/docs/en/Customizing-Application-Modules-Extending-Entities.md @@ -50,7 +50,7 @@ ObjectExtensionManager.Instance * You provide the `IdentityUser` as the entity name, `string` as the type of the new property, `SocialSecurityNumber` as the property name (also, the field name in the database table). * You also need to provide an action that defines the database mapping properties using the [EF Core Fluent API](https://docs.microsoft.com/en-us/ef/core/modeling/entity-properties). -> This code part must be executed before the related `DbContext` used. The [application startup template](Startup-Templates/Application.md) defines a static class named `YourProjectNameEntityExtensions`. You can define your extensions in this class to ensure that it is executed in the proper time. Otherwise, you should handle it yourself. +> This code part must be executed before the related `DbContext` used. The [application startup template](Startup-Templates/Application.md) defines a static class named `YourProjectNameEfCoreEntityExtensionMappings`. You can define your extensions in this class to ensure that it is executed in the proper time. Otherwise, you should handle it yourself. Once you define an entity extension, you then need to use the standard [Add-Migration](https://docs.microsoft.com/en-us/ef/core/miscellaneous/cli/powershell#add-migration) and [Update-Database](https://docs.microsoft.com/en-us/ef/core/miscellaneous/cli/powershell#update-database) commands of the EF Core to create a code first migration class and update your database. @@ -174,4 +174,4 @@ public class MyDistributedIdentityUserCreatedEventHandler : ## See Also * [Migration System for the EF Core](Entity-Framework-Core-Migrations.md) -* [Customizing the Existing Modules](Customizing-Application-Modules-Guide.md) \ No newline at end of file +* [Customizing the Existing Modules](Customizing-Application-Modules-Guide.md) diff --git a/docs/en/Customizing-Application-Modules-Overriding-Services.md b/docs/en/Customizing-Application-Modules-Overriding-Services.md index d58f0f8565..7f0c0502ea 100644 --- a/docs/en/Customizing-Application-Modules-Overriding-Services.md +++ b/docs/en/Customizing-Application-Modules-Overriding-Services.md @@ -60,6 +60,7 @@ In most cases, you will want to change one or a few methods of the current imple ````csharp [Dependency(ReplaceServices = true)] +[ExposeServices(typeof(IIdentityUserAppService), typeof(IdentityUserAppService))] public class MyIdentityUserAppService : IdentityUserAppService { //... @@ -262,4 +263,4 @@ See [Overriding the User Interface](Customizing-Application-Modules-Overriding-U ## How to Find the Services? -[Module documents](Modules/Index.md) includes the list of the major services they define. In addition, you can investigate [their source code](https://github.com/abpframework/abp/tree/dev/modules) to explore all the services. \ No newline at end of file +[Module documents](Modules/Index.md) includes the list of the major services they define. In addition, you can investigate [their source code](https://github.com/abpframework/abp/tree/dev/modules) to explore all the services. diff --git a/docs/en/Exception-Handling.md b/docs/en/Exception-Handling.md index 6dc4ccbd9f..3ccade9767 100644 --- a/docs/en/Exception-Handling.md +++ b/docs/en/Exception-Handling.md @@ -315,8 +315,8 @@ The `context` object contains necessary information about the exception occurred Some exception types are automatically thrown by the framework: -- `AbpAuthorizationException` is thrown if the current user has no permission to perform the requested operation. See authorization document (TODO: link) for more. -- `AbpValidationException` is thrown if the input of the current request is not valid. See validation document (TODO: link) for more. +- `AbpAuthorizationException` is thrown if the current user has no permission to perform the requested operation. See [authorization](Authorization.md) for more. +- `AbpValidationException` is thrown if the input of the current request is not valid. See [validation](Validation.md) for more. - `EntityNotFoundException` is thrown if the requested entity is not available. This is mostly thrown by [repositories](Repositories.md). You can also throw these type of exceptions in your code (although it's rarely needed). diff --git a/docs/en/Getting-Started-Angular-Template.md b/docs/en/Getting-Started-Angular-Template.md index 22d672d97a..9beb84bcef 100644 --- a/docs/en/Getting-Started-Angular-Template.md +++ b/docs/en/Getting-Started-Angular-Template.md @@ -1,126 +1,8 @@ -## Getting Started With the Angular Application Template +# Getting Started with the Startup Templates -This tutorial explains how to create a new Angular application using the startup template, configure and run it. +See the following tutorials to learn how to get started with the ABP Framework using the pre-built application startup templates: -### Creating a New Project +* [Getting Started With the ASP.NET Core MVC / Razor Pages UI](Getting-Started?UI=MVC&DB=EF&Tiered=No) +* [Getting Started with the Angular UI](Getting-Started?UI=NG&DB=EF&Tiered=No) -This tutorial uses **ABP CLI** to create a new project. See the [Get Started](https://abp.io/get-started) page for other options. - -Install the ABP CLI using a command line window, if you've not installed before: - -````bash -dotnet tool install -g Volo.Abp.Cli -```` - -Use `abp new` command in an empty folder to create your project: - -````bash -abp new Acme.BookStore -u angular -```` - -> You can use different level of namespaces; e.g. BookStore, Acme.BookStore or Acme.Retail.BookStore. - -`-u angular` option specifies the UI framework to be Angular. Default database provider is EF Core. See the [CLI documentation](CLI.md) for all available options. - -#### Pre Requirements - -The created solution requires; - -* [Visual Studio 2019 (v16.4+)](https://visualstudio.microsoft.com/vs/) -* [.NET Core 3.0+](https://www.microsoft.com/net/download/dotnet-core/) -* [Node v12+](https://nodejs.org) -* [Yarn v1.19+](https://classic.yarnpkg.com/) - -### The Solution Structure - -Open the solution in **Visual Studio**: - -![bookstore-visual-studio-solution](images/bookstore-visual-studio-solution-for-spa.png) - -The solution has a layered structure (based on [Domain Driven Design](Domain-Driven-Design.md)) and contains unit & integration test projects properly configured to work with **EF Core** & **SQLite in-memory** database. - -> See the [Application Template Document](Startup-Templates/Application.md) to understand the solution structure in details. - -### Database Connection String - -Check the **connection string** in the `appsettings.json` file under the `.HttpApi.Host` project: - -````json -{ - "ConnectionStrings": { - "Default": "Server=localhost;Database=BookStore;Trusted_Connection=True" - } -} -```` - -The solution is configured to use **Entity Framework Core** with **MS SQL Server**. EF Core supports [various](https://docs.microsoft.com/en-us/ef/core/providers/) database providers, so you can use another DBMS if you want. Change the connection string if you need. - -### Create Database & Apply Database Migrations - -You have two options to create the database. - -#### Using the DbMigrator Application - -The solution contains a console application (named `Acme.BookStore.DbMigrator` in this sample) that can create database, apply migrations and seed initial data. It is useful on development as well as on production environment. - -> `.DbMigrator` project has its own `appsettings.json`. So, if you have changed the connection string above, you should also change this one. - -Right click to the `.DbMigrator` project and select **Set as StartUp Project**: - -![set-as-startup-project](images/set-as-startup-project.png) - -Hit F5 (or Ctrl+F5) to run the application. It will have an output like shown below: - -![set-as-startup-project](images/db-migrator-app.png) - -#### Using EF Core Update-Database Command - -Ef Core has `Update-Database` command which creates database if necessary and applies pending migrations. Right click to the `.HttpApi.Host` project and select **Set as StartUp Project**: - -![set-as-startup-project](images/set-as-startup-project.png) - -Open the **Package Manager Console**, select `.EntityFrameworkCore.DbMigrations` project as the **Default Project** and run the `Update-Database` command: - -![pcm-update-database](images/pcm-update-database-v2.png) - -This will create a new database based on the configured connection string. - -> Using the `.DbMigrator` tool is the suggested way, because it also seeds the initial data to be able to properly run the web application. - -### Running the Application - -#### Run the API Host (Server Side) - -Ensure that the `.HttpApi.Host` project is the startup project and run the application which will open a Swagger UI: - -![bookstore-homepage](images/bookstore-swagger-ui-host.png) - -You can see the application APIs and test them here. Get [more info](https://swagger.io/tools/swagger-ui/) about the Swagger UI. - -##### Authorization for the Swagger UI - -Most of the application APIs require authentication & authorization. If you want to test authorized APIs, manually go to the `/Account/Login` page, enter `admin` as the username and `1q2w3E*` as the password to login to the application. Then you will be able to execute authorized APIs too. - -#### Run the Angular Application (Client Side) - -Go to the `angular` folder, open a command line terminal, type the `yarn` command (we suggest the [yarn](https://yarnpkg.com) package manager while `npm install` will also work in most cases) - -````bash -yarn -```` - -Once all node modules are loaded, execute `yarn start` or `npm start` command: - -````bash -yarn start -```` - -Open your favorite browser and go to `localhost:4200` URL. Initial username is `admin` and password is `1q2w3E*`. - -The startup template includes the **identity management** and **tenant management** modules. Once you login, the Administration menu will be available where you can manage **tenants**, **roles**, **users** and their **permissions**. - -> We recommend [Visual Studio Code](https://code.visualstudio.com/) as the editor for the Angular project, but you are free to use your favorite editor. - -### What's Next? - -* [Application development tutorial](Tutorials/Part-1) + \ No newline at end of file diff --git a/docs/en/Getting-Started-AspNetCore-MVC-Template.md b/docs/en/Getting-Started-AspNetCore-MVC-Template.md index d074e8aaef..9beb84bcef 100644 --- a/docs/en/Getting-Started-AspNetCore-MVC-Template.md +++ b/docs/en/Getting-Started-AspNetCore-MVC-Template.md @@ -1,104 +1,8 @@ -## Getting Started With the ASP.NET Core MVC Template +# Getting Started with the Startup Templates -This tutorial explains how to create a new ASP.NET Core MVC web application using the startup template, configure and run it. +See the following tutorials to learn how to get started with the ABP Framework using the pre-built application startup templates: -### Creating a New Project +* [Getting Started With the ASP.NET Core MVC / Razor Pages UI](Getting-Started?UI=MVC&DB=EF&Tiered=No) +* [Getting Started with the Angular UI](Getting-Started?UI=NG&DB=EF&Tiered=No) -This tutorial uses **ABP CLI** to create a new project. See the [Get Started](https://abp.io/get-started) page for other options. - -Install the ABP CLI using a command line window, if you've not installed before: - -````bash -dotnet tool install -g Volo.Abp.Cli -```` - -Use `abp new` command in an empty folder to create your project: - -````bash -abp new Acme.BookStore -```` - -> You can use different level of namespaces; e.g. BookStore, Acme.BookStore or Acme.Retail.BookStore. - -`new` command creates a **layered MVC application** with **Entity Framework Core** as the database provider. However, it has additional options. See the [CLI documentation](CLI.md) for all available options. - -#### Pre Requirements - -The created solution requires; - -* [Visual Studio 2019 (v16.4+)](https://visualstudio.microsoft.com/vs/) -* [.NET Core 3.0+](https://www.microsoft.com/net/download/dotnet-core/) -* [Node v12+](https://nodejs.org) -* [Yarn v1.19+](https://classic.yarnpkg.com/) - -### The Solution Structure - -Open the solution in **Visual Studio**: - -![bookstore-visual-studio-solution](images/bookstore-visual-studio-solution-v3.png) - -The solution has a layered structure (based on [Domain Driven Design](Domain-Driven-Design.md)) and contains unit & integration test projects properly configured to work with **EF Core** & **SQLite in-memory** database. - -> See [Application template document](Startup-Templates/Application.md) to understand the solution structure in details. - -### Database Connection String - -Check the **connection string** in the `appsettings.json` file under the `.Web` project: - -````json -{ - "ConnectionStrings": { - "Default": "Server=localhost;Database=BookStore;Trusted_Connection=True" - } -} -```` - -The solution is configured to use **Entity Framework Core** with **MS SQL Server**. EF Core supports [various](https://docs.microsoft.com/en-us/ef/core/providers/) database providers, so you can use another DBMS if you want. Change the connection string if you need. - -### Create Database & Apply Database Migrations - -You have two options to create the database. - -#### Using the DbMigrator Application - -The solution contains a console application (named `Acme.BookStore.DbMigrator` in this sample) that can create database, apply migrations and seed initial data. It is useful on development as well as on production environment. - -> `.DbMigrator` project has its own `appsettings.json`. So, if you have changed the connection string above, you should also change this one. - -Right click to the `.DbMigrator` project and select **Set as StartUp Project**: - -![set-as-startup-project](images/set-as-startup-project.png) - -Hit F5 (or Ctrl+F5) to run the application. It will have an output like shown below: - -![set-as-startup-project](images/db-migrator-app.png) - -#### Using EF Core Update-Database Command - -Ef Core has `Update-Database` command which creates database if necessary and applies pending migrations. Right click to the `.Web` project and select **Set as StartUp Project**: - -![set-as-startup-project](images/set-as-startup-project.png) - -Open the **Package Manager Console**, select `.EntityFrameworkCore.DbMigrations` project as the **Default Project** and run the `Update-Database` command: - -![pcm-update-database](images/pcm-update-database-v2.png) - -This will create a new database based on the configured connection string. - -> Using the `.Migrator` tool is the suggested way, because it also seeds the initial data to be able to properly run the web application. - -### Running the Application - -Ensure that the `.Web` project is the startup project. Run the application which will open the **home** page in your browser: - -![bookstore-homepage](images/bookstore-homepage.png) - -Click the **Login** button, enter `admin` as the username and `1q2w3E*` as the password to login to the application. - -The startup template includes the **identity management** and **tenant management** modules. Once you login, the Administration menu will be available where you can manage **tenants**, **roles**, **users** and their **permissions**. User management page is shown below: - -![bookstore-user-management](images/bookstore-user-management-v2.png) - -### What's Next? - -* [Application development tutorial](Tutorials/Part-1.md) + \ No newline at end of file diff --git a/docs/en/Getting-Started-With-Startup-Templates.md b/docs/en/Getting-Started-With-Startup-Templates.md index 19442ec81e..be2bb201b8 100644 --- a/docs/en/Getting-Started-With-Startup-Templates.md +++ b/docs/en/Getting-Started-With-Startup-Templates.md @@ -2,5 +2,7 @@ See the following tutorials to learn how to get started with the ABP Framework using the pre-built application startup templates: -* [Getting Started With the ASP.NET Core MVC / Razor Pages UI](Getting-Started-AspNetCore-MVC-Template.md) -* [Getting Started with the Angular UI](Getting-Started-Angular-Template.md) \ No newline at end of file +* [Getting Started With the ASP.NET Core MVC / Razor Pages UI](Getting-Started?UI=MVC&DB=EF&Tiered=No) +* [Getting Started with the Angular UI](Getting-Started?UI=NG&DB=EF&Tiered=No) + + \ No newline at end of file diff --git a/docs/en/Getting-Started.md b/docs/en/Getting-Started.md new file mode 100644 index 0000000000..07e55f553e --- /dev/null +++ b/docs/en/Getting-Started.md @@ -0,0 +1,407 @@ +# Getting started + +````json +//[doc-params] +{ + "UI": ["MVC","NG"], + "DB": ["EF", "Mongo"], + "Tiered": ["Yes", "No"] +} +```` + +This tutorial explains how to create a new {{if UI == "MVC"}} ASP.NET Core MVC web {{else if UI == "NG"}} Angular {{end}} application using the startup template, configure and run it. + + +## Setup your development environment + +First things first! Let's setup your development environment before creating the first project. + +### Pre-requirements + +The following tools should be installed on your development machine: + +* [Visual Studio 2019 (v16.4+)](https://visualstudio.microsoft.com/vs/) for Windows / [Visual Studio for Mac](https://visualstudio.microsoft.com/vs/mac/). +* [.NET Core 3.0+](https://www.microsoft.com/net/download/dotnet-core/) + +* [Node v12+](https://nodejs.org) +* [Yarn v1.19+](https://classic.yarnpkg.com/) + +> You can use another editor instead of Visual Studio as long as it supports .NET Core and ASP.NET Core. + +### Install the ABP CLI + +[ABP CLI](./CLI.md) is a command line interface that is used to authenticate and automate some tasks for ABP based applications. + +> ABP CLI is a free & open source tool for [the ABP framework](https://abp.io/). + +First, you need to install the ABP CLI using the following command: + +````shell +dotnet tool install -g Volo.Abp.Cli +```` + +If you've already installed, you can update it using the following command: + +````shell +dotnet tool update -g Volo.Abp.Cli +```` + +## Create a new project + +> This document assumes that you prefer to use **{{ UI_Value }}** as the UI framework and **{{ DB_Value }}** as the database provider. For other options, please change the preference on top of this document. + +### Using the ABP CLI to create a new project + +Use the `new` command of the ABP CLI to create a new project: + +````shell +abp new Acme.BookStore -t app{{if UI == "NG"}} -u angular {{end}}{{if DB == "Mongo"}} -d mongodb{{end}}{{if Tiered == "Yes" && UI != "NG"}} --tiered {{else if Tiered == "Yes" && UI == "NG"}}--separate-identity-server{{end}} +```` + +* `-t` argument specifies the [startup template](Startup-Templates/Application.md) name. `app` is the startup template that contains the essential [ABP Modules](Modules/Index.md) pre-installed and configured for you. + +{{ if UI == "NG" }} + +* `-u` argument specifies the UI framework, `angular` in this case. + +{{ if Tiered == "Yes" }} + +* `--separate-identity-server` argument is used to separate the identity server application from the API host application. If not specified, you will have a single endpoint. + +{{ end }} + +{{ end }} + +{{ if DB == "Mongo" }} + +* `-d` argument specifies the database provider, `mongodb` in this case. + +{{ end }} + +{{ if Tiered == "Yes" && UI != "NG" }} + +* `--tiered` argument is used to create N-tiered solution where authentication server, UI and API layers are physically separated. + +{{ end }} + +> You can use different level of namespaces; e.g. BookStore, Acme.BookStore or Acme.Retail.BookStore. + +#### ABP CLI commands & options + +[ABP CLI document](./CLI.md) covers all of the available commands and options for the ABP CLI. See the [ABP Startup Templates](Startup-Templates/Index.md) document for other templates. + +## The solution structure + +{{ if UI == "MVC" }} + +After creating your project, you will have the following solution folders & files: + +![](images/solution-files-mvc.png) + +You will see the following solution structure when you open the `.sln` file in the Visual Studio: + +{{if DB == "Mongo"}} + +![vs-default-app-solution-structure](images/vs-app-solution-structure-mongodb.png) + +{{else}} + +![vs-default-app-solution-structure](images/vs-app-solution-structure{{if Tiered == "Yes"}}-tiered{{end}}.png) + +{{end}} + +{{ else if UI == "NG" }} +There are three folders in the created solution: + +![](images/solution-files-non-mvc.png) + +* `angular` folder contains the Angular UI application. +* `aspnet-core` folder contains the backend solution. +* `react-native` folder contains the React Native UI application. + +Open the `.sln` (Visual Studio solution) file under the `aspnet-core` folder: + +![vs-angular-app-backend-solution-structure](images/vs-spa-app-backend-structure{{if DB == "Mongo"}}-mongodb{{end}}.png) + +{{ end }} + +> ###### About the projects in your solution +> +> Your solution may have slightly different structure based on your **UI**, **database** and other preferences. + +The solution has a layered structure (based on [Domain Driven Design](./Domain-Driven-Design.md)) and also contains unit & integration test projects. + +{{ if DB == "EF" }} + +Integration tests projects are properly configured to work with **EF Core** & **SQLite in-memory** database. + +{{ else if DB == "Mongo" }} + +Integration tests projects are properly configured to work with in-memory **MongoDB** database created per test (used [Mongo2Go](https://github.com/Mongo2Go/Mongo2Go) library). + +{{ end }} + +> See the [application template document](Startup-Templates/Application.md) to understand the solution structure in details. + +## Create the database + +### Database connection string + +Check the **connection string** in the `appsettings.json` file under the {{if UI == "MVC"}}{{if Tiered == "Yes"}}`.IdentityServer` and `.HttpApi.Host` projects{{else}}`.Web` project{{end}}{{else if UI == "NG" }}`.HttpApi.Host` project{{end}}: + +{{ if DB == "EF" }} + +````json +"ConnectionStrings": { + "Default": "Server=localhost;Database=BookStore;Trusted_Connection=True" +} +```` + +The solution is configured to use **Entity Framework Core** with **MS SQL Server**. EF Core supports [various](https://docs.microsoft.com/en-us/ef/core/providers/) database providers, so you can use any supported DBMS. See [the Entity Framework integration document](https://docs.abp.io/en/abp/latest/Entity-Framework-Core) to learn how to switch to another DBMS. + +### Apply the migrations + +The solution uses the [Entity Framework Core Code First Migrations](https://docs.microsoft.com/en-us/ef/core/managing-schemas/migrations/?tabs=dotnet-core-cli). So, you need to apply migrations to create the database. There are two ways of applying the database migrations. + +#### Apply migrations using the DbMigrator + +The solution comes with a `.DbMigrator` console application which applies migrations and also seed the initial data. It is useful on development as well as on production environment. + +> `.DbMigrator` project has its own `appsettings.json`. So, if you have changed the connection string above, you should also change this one. + +Right click to the `.DbMigrator` project and select **Set as StartUp Project** + +![set-as-startup-project](images/set-as-startup-project.png) + + Hit F5 (or Ctrl+F5) to run the application. It will have an output like shown below: + + ![db-migrator-output](images/db-migrator-output.png) + +> Initial seed data creates the `admin` user in the database which is then used to login to the application. So, you need to use `.DbMigrator` at least once for a new database. + +#### Using EF Core Update-Database command + +Ef Core has `Update-Database` command which creates database if necessary and applies pending migrations. + +{{ if UI == "MVC" }} + +Right click to the {{if Tiered == "Yes"}}`.IdentityServer`{{else}}`.Web`{{end}} project and select **Set as StartUp project**: + +{{ else if UI != "MVC" }} + +Right click to the `.HttpApi.Host` project and select **Set as StartUp Project**: + +{{ end }} + +![set-as-startup-project](images/set-as-startup-project.png) + +Open the **Package Manager Console**, select `.EntityFrameworkCore.DbMigrations` project as the **Default Project** and run the `Update-Database` command: + +![package-manager-console-update-database](images/package-manager-console-update-database.png) + +This will create a new database based on the configured connection string. + +> Using the `.Migrator` tool is the suggested way, because it also seeds the initial data to be able to properly run the web application. + +{{ else if DB == "Mongo" }} + +````json +"ConnectionStrings": { + "Default": "mongodb://localhost:27017/BookStore" +} +```` + +The solution is configured to use **MongoDB** in your local computer, so you need to have a MongoDB server instance up and running or change the connection string to another MongoDB server. + +### Seed initial data + +The solution comes with a `.DbMigrator` console application which seeds the initial data. It is useful on development as well as on production environment. + +> `.DbMigrator` project has its own `appsettings.json`. So, if you have changed the connection string above, you should also change this one. + +Right click to the `.DbMigrator` project and select **Set as StartUp Project** + +![set-as-startup-project](images/set-as-startup-project.png) + + Hit F5 (or Ctrl+F5) to run the application. It will have an output like shown below: + + ![db-migrator-output](images/db-migrator-output.png) + +> Initial seed data creates the `admin` user in the database which is then used to login to the application. So, you need to use `.DbMigrator` at least once for a new database. + +{{ end }} + +## Run the application + +{{ if UI == "MVC" }} + +{{ if Tiered == "Yes" }} + +Ensure that the `.IdentityServer` project is the startup project. Run the application which will open a **login** page in your browser. + +> Use Ctrl+F5 in Visual Studio (instead of F5) to run the application without debugging. If you don't have a debug purpose, this will be faster. + +You can login, but you cannot enter to the main application here. This is just the authentication server. + +Ensure that the `.HttpApi.Host` project is the startup project and run the application which will open a **Swagger UI** in your browser. + +![swagger-ui](images/swagger-ui.png) + +This is the API application that is used by the web application. + +Lastly, ensure that the `.Web` project is the startup project and run the application which will open a **welcome** page in your browser + +![mvc-tiered-app-home](images/bookstore-home.png) + +Click to the **login** button which will redirect you to the `Identity Server` to login to the application: + +![bookstore-login](images/bookstore-login.png) + +{{ else }} + +Ensure that the `.Web` project is the startup project. Run the application which will open the **login** page in your browser: + +> Use Ctrl+F5 in Visual Studio (instead of F5) to run the application without debugging. If you don't have a debug purpose, this will be faster. + +![bookstore-login](images/bookstore-login.png) + +{{ end }} + +{{ else if UI != "MVC" }} + +#### Running the HTTP API Host (server-side) + +{{ if Tiered == "Yes" }} + +Ensure that the `.IdentityServer` project is the startup project. Run the application which will open a **login** page in your browser. + +> Use Ctrl+F5 in Visual Studio (instead of F5) to run the application without debugging. If you don't have a debug purpose, this will be faster. + +You can login, but you cannot enter to the main application here. This is just the authentication server. + +{{ end }} + +Ensure that the `.HttpApi.Host` project is the startup project and run the application which will open a Swagger UI: + +{{ if Tiered == "No" }} + +> Use Ctrl+F5 in Visual Studio (instead of F5) to run the application without debugging. If you don't have a debug purpose, this will be faster. + +{{ end }} + +![swagger-ui](images/swagger-ui.png) + +You can see the application APIs and test them here. Get [more info](https://swagger.io/tools/swagger-ui/) about the Swagger UI. + +> ##### Authorization for the Swagger UI +> +> Most of the HTTP APIs require authentication & authorization. If you want to test authorized APIs, manually go to the `/Account/Login` page, enter `admin` as the username and `1q2w3E*` as the password to login to the application. Then you will be able to execute authorized APIs too. + +{{ end }} + +{{ if UI == "NG" }} +#### Running the Angular application (client-side) + +Go to the `angular` folder, open a command line terminal, type the `yarn` command (we suggest to the [yarn](https://yarnpkg.com/) package manager while `npm install` will also work in most cases) + +```bash +yarn +``` + +Once all node modules are loaded, execute `yarn start` (or `npm start`) command: + +```bash +yarn start +``` + +Wait `Angular CLI` to launch `Webpack` dev-server with `BrowserSync`. +This will take care of compiling your `TypeScript` code, and automatically reloading your browser. +After it finishes, `Angular Live Development Server` will be listening on localhost:4200, +open your web browser and navigate to [localhost:4200](http://localhost:4200/) + + + +![bookstore-login](images/bookstore-login.png) + +{{ end }} + +Enter **admin** as the username and **1q2w3E*** as the password to login to the application: + +![bookstore-home](images/bookstore-home.png) + +The application is up and running. You can start developing your application based on this startup template. + +#### Mobile Development + +ABP platform provide [React Native](https://reactnative.dev/) template to develop mobile applications. + +>The solution includes the React Native application in the `react-native` folder as default. If you don't plan to develop a mobile application with React Native, you can ignore this step and delete the `react-native` folder. + +The React Native application running on an Android emulator or a physical phone cannot connect to the backend on `localhost`. To fix this problem, it is necessary to run backend on the local IP. + +{{ if Tiered == "No"}} +![React Native host project local IP entry](images/rn-host-local-ip.png) + +* Open the `appsettings.json` in the `.HttpApi.Host` folder. Replace the `localhost` address on the `SelfUrl` and `Authority` properties with your local IP address. +* Open the `launchSettings.json` in the `.HttpApi.Host/Properties` folder. Replace the `localhost` address on the `applicationUrl` properties with your local IP address. + +{{ else if Tiered == "Yes" }} + +![React Native tiered project local IP entry](images/rn-tiered-local-ip.png) + +* Open the `appsettings.json` in the `.IdentityServer` folder. Replace the `localhost` address on the `SelfUrl` property with your local IP address. +* Open the `launchSettings.json` in the `.IdentityServer/Properties` folder. Replace the `localhost` address on the `applicationUrl` properties with your local IP address. +* Open the `appsettings.json` in the `.HttpApi.Host` folder. Replace the `localhost` address on the `Authority` property with your local IP address. +* Open the `launchSettings.json` in the `.HttpApi.Host/Properties` folder. Replace the `localhost` address on the `applicationUrl` properties with your local IP address. + +{{ end }} + +Run the backend as described in the [**Running the HTTP API Host (server-side)**](#running-the-http-api-host-server-side) section. + +> React Native application does not trust the auto-generated .NET HTTPS certificate, you should use the HTTP during development. + +Go to the `react-native` folder, open a command line terminal, type the `yarn` command (we suggest to the [yarn](https://yarnpkg.com/) package manager while `npm install` will also work in most cases): + +```bash +yarn +``` + +* Open the `Environment.js` in the `react-native` folder and replace the `localhost` address on the `apiUrl` and `issuer` properties with your local IP address as shown below: + +![react native environment local IP](images/rn-environment-local-ip.png) + +{{ if Tiered == "Yes" }} + +> Make sure that `issuer` matches the running address of the `.IdentityServer` project, `apiUrl` matches the running address of the `.HttpApi.Host` project. + +{{else}} + +> Make sure that `issuer` and `apiUrl` matches the running address of the `.HttpApi.Host` project. + +{{ end }} + +Once all node modules are loaded, execute `yarn start` (or `npm start`) command: + +```bash +yarn start +``` + +Wait Expo CLI to start. Expo CLI opens the management interface on the `http://localhost:19002/` address. + +![expo-interface](images/rn-expo-interface.png) + +In the above management interface, you can start the application with an Android emulator, an iOS simulator or a physical phone by the scan the QR code with the [Expo Client](https://expo.io/tools#client). + +> See the [Android Studio Emulator](https://docs.expo.io/versions/v36.0.0/workflow/android-studio-emulator/), [iOS Simulator](https://docs.expo.io/versions/v36.0.0/workflow/ios-simulator/) documents on expo.io. + +![React Native login screen on iPhone 11](images/rn-login-iphone.png) + +Enter **admin** as the username and **1q2w3E*** as the password to login to the application. + +The application is up and running. You can continue to develop your application based on this startup template. + +> The [application startup template](startup-templates/application/index.md) includes the TenantManagement and Identity modules. + +## What's next? + +[Application development tutorial](tutorials/book-store/part-1.md) diff --git a/docs/en/How-To/Customize-SignIn-Manager.md b/docs/en/How-To/Customize-SignIn-Manager.md index 61b6c3b7b5..03c1f06dd8 100644 --- a/docs/en/How-To/Customize-SignIn-Manager.md +++ b/docs/en/How-To/Customize-SignIn-Manager.md @@ -42,14 +42,14 @@ public override async Task GetE { var auth = await Context.AuthenticateAsync(Microsoft.AspNetCore.Identity.IdentityConstants.ExternalScheme); var items = auth?.Properties?.Items; - if (auth?.Principal == null || items == null || !items.ContainsKey("LoginProviderKey")) + if (auth?.Principal == null || items == null || !items.ContainsKey(LoginProviderKey)) { return null; } if (expectedXsrf != null) { - if (!items.ContainsKey("XsrfKey")) + if (!items.ContainsKey(XsrfKey)) { return null; } diff --git a/docs/en/Nightly-Builds.md b/docs/en/Nightly-Builds.md index e7ebe0f33b..1a66af32e1 100644 --- a/docs/en/Nightly-Builds.md +++ b/docs/en/Nightly-Builds.md @@ -24,3 +24,18 @@ Now, you can install preview / nightly packages to your project from Nuget Brows 3. Search a package. You will see prereleases of the package formatted as `(VERSION)-preview(DATE)` (like *v0.16.0-preview20190401* in this sample). 4. You can click to the `Install` button to add package to your project. +## Install & Uninstall Preview NPM Packages + +The latest version of preview NPM packages can be installed by the running below command in the root folder of application: + +```bash +abp switch-to-preview +``` + +If you're using the ABP Framework preview packages, you can switch back to stable version using this command: + +```bash +abp switch-to-stable +``` + +See the [ABP CLI documentation](./CLI.md) for more information. \ No newline at end of file diff --git a/docs/en/Object-Extensions.md b/docs/en/Object-Extensions.md index bbcb96374c..6eff328c85 100644 --- a/docs/en/Object-Extensions.md +++ b/docs/en/Object-Extensions.md @@ -156,11 +156,9 @@ ObjectExtensionManager.Instance ); ```` -#### Property Configuration +### Property Configuration -`AddOrUpdateProperty` can also get an action that can perform additional configuration on the property definition. - -Example: +`AddOrUpdateProperty` can also get an action that can perform additional configuration on the property definition: ````csharp ObjectExtensionManager.Instance @@ -168,13 +166,113 @@ ObjectExtensionManager.Instance "SocialSecurityNumber", options => { - options.CheckPairDefinitionOnMapping = false; + //Configure options... + }); +```` + +> `options` has a dictionary, named `Configuration` which makes the object extension definitions even extensible. It is used by the EF Core to map extra properties to table fields in the database. See the [extending entities](Customizing-Application-Modules-Extending-Entities.md) document. + +The following sections explain the fundamental property configuration options. + +#### CheckPairDefinitionOnMapping + +Controls how to check property definitions while mapping two extensible objects. See the "Object to Object Mapping" section to understand the `CheckPairDefinitionOnMapping` option better. + +## Validation + +You may want to add some **validation rules** for the extra properties you've defined. `AddOrUpdateProperty` method options allows two ways of performing validation: + +1. You can add **data annotation attributes** for a property. +2. You can write an action (code block) to perform a **custom validation**. + +Validation works when you use the object in a method that is **automatically validated** (e.g. controller actions, page handler methods, application service methods...). So, all extra properties are validated whenever the extended object is being validated. + +### Data Annotation Attributes + +All of the standard data annotation attributes are valid for extra properties. Example: + +````csharp +ObjectExtensionManager.Instance + .AddOrUpdateProperty( + "SocialSecurityNumber", + options => + { + options.ValidationAttributes.Add(new RequiredAttribute()); + options.ValidationAttributes.Add( + new StringLengthAttribute(32) { + MinimumLength = 6 + } + ); + }); +```` + +With this configuration, `IdentityUserCreateDto` objects will be invalid without a valid `SocialSecurityNumber` value provided. + +### Custom Validation + +If you need, you can add a custom action that is executed to validate the extra properties. Example: + +````csharp +ObjectExtensionManager.Instance + .AddOrUpdateProperty( + "SocialSecurityNumber", + options => + { + options.Validators.Add(context => + { + var socialSecurityNumber = context.Value as string; + + if (socialSecurityNumber == null || + socialSecurityNumber.StartsWith("X")) + { + context.ValidationErrors.Add( + new ValidationResult( + "Invalid social security number: " + socialSecurityNumber, + new[] { "SocialSecurityNumber" } + ) + ); + } + }); }); ```` -> See the "Object to Object Mapping" section to understand the `CheckPairDefinitionOnMapping` option. +`context.ServiceProvider` can be used to resolve a service dependency for advanced scenarios. + +In addition to add custom validation logic for a single property, you can add a custom validation logic that is executed in object level. Example: -`options` has a dictionary, named `Configuration` which makes the object extension definitions even extensible. It is used by the EF Core to map extra properties to table fields in the database. See the [extending entities](Customizing-Application-Modules-Extending-Entities.md) document. +````csharp +ObjectExtensionManager.Instance +.AddOrUpdate(objConfig => +{ + //Define two properties with their own validation rules + + objConfig.AddOrUpdateProperty("Password", propertyConfig => + { + propertyConfig.ValidationAttributes.Add(new RequiredAttribute()); + }); + + objConfig.AddOrUpdateProperty("PasswordRepeat", propertyConfig => + { + propertyConfig.ValidationAttributes.Add(new RequiredAttribute()); + }); + + //Write a common validation logic works on multiple properties + + objConfig.Validators.Add(context => + { + if (context.ValidatingObject.GetProperty("Password") != + context.ValidatingObject.GetProperty("PasswordRepeat")) + { + context.ValidationErrors.Add( + new ValidationResult( + "Please repeat the same password!", + new[] { "Password", "PasswordRepeat" } + ) + ); + } + }); +}); +```` ## Object to Object Mapping diff --git a/docs/en/Tutorials/Angular/Part-I.md b/docs/en/Tutorials/Angular/Part-I.md index 65a7dc5714..2867a3159f 100644 --- a/docs/en/Tutorials/Angular/Part-I.md +++ b/docs/en/Tutorials/Angular/Part-I.md @@ -4,3 +4,5 @@ * [With ASP.NET Core MVC / Razor Pages UI](../Part-1?UI=MVC) * [With Angular UI](../Part-1?UI=NG) + + \ No newline at end of file diff --git a/docs/en/Tutorials/Angular/Part-II.md b/docs/en/Tutorials/Angular/Part-II.md index 65a7dc5714..2867a3159f 100644 --- a/docs/en/Tutorials/Angular/Part-II.md +++ b/docs/en/Tutorials/Angular/Part-II.md @@ -4,3 +4,5 @@ * [With ASP.NET Core MVC / Razor Pages UI](../Part-1?UI=MVC) * [With Angular UI](../Part-1?UI=NG) + + \ No newline at end of file diff --git a/docs/en/Tutorials/Angular/Part-III.md b/docs/en/Tutorials/Angular/Part-III.md index 65a7dc5714..2867a3159f 100644 --- a/docs/en/Tutorials/Angular/Part-III.md +++ b/docs/en/Tutorials/Angular/Part-III.md @@ -4,3 +4,5 @@ * [With ASP.NET Core MVC / Razor Pages UI](../Part-1?UI=MVC) * [With Angular UI](../Part-1?UI=NG) + + \ No newline at end of file diff --git a/docs/en/Tutorials/AspNetCore-Mvc/Part-I.md b/docs/en/Tutorials/AspNetCore-Mvc/Part-I.md index 65a7dc5714..2867a3159f 100644 --- a/docs/en/Tutorials/AspNetCore-Mvc/Part-I.md +++ b/docs/en/Tutorials/AspNetCore-Mvc/Part-I.md @@ -4,3 +4,5 @@ * [With ASP.NET Core MVC / Razor Pages UI](../Part-1?UI=MVC) * [With Angular UI](../Part-1?UI=NG) + + \ No newline at end of file diff --git a/docs/en/Tutorials/AspNetCore-Mvc/Part-II.md b/docs/en/Tutorials/AspNetCore-Mvc/Part-II.md index 65a7dc5714..2867a3159f 100644 --- a/docs/en/Tutorials/AspNetCore-Mvc/Part-II.md +++ b/docs/en/Tutorials/AspNetCore-Mvc/Part-II.md @@ -4,3 +4,5 @@ * [With ASP.NET Core MVC / Razor Pages UI](../Part-1?UI=MVC) * [With Angular UI](../Part-1?UI=NG) + + \ No newline at end of file diff --git a/docs/en/Tutorials/AspNetCore-Mvc/Part-III.md b/docs/en/Tutorials/AspNetCore-Mvc/Part-III.md index 65a7dc5714..2867a3159f 100644 --- a/docs/en/Tutorials/AspNetCore-Mvc/Part-III.md +++ b/docs/en/Tutorials/AspNetCore-Mvc/Part-III.md @@ -4,3 +4,5 @@ * [With ASP.NET Core MVC / Razor Pages UI](../Part-1?UI=MVC) * [With Angular UI](../Part-1?UI=NG) + + \ No newline at end of file diff --git a/docs/en/Tutorials/Part-1.md b/docs/en/Tutorials/Part-1.md index 20b64f3189..a0aa6612e9 100644 --- a/docs/en/Tutorials/Part-1.md +++ b/docs/en/Tutorials/Part-1.md @@ -22,7 +22,7 @@ end ### About this tutorial: -In this tutorial series, you will build an ABP Commercial application named `Acme.BookStore`. In this sample project, we will manage a list of books and authors. **{{DB_Text}}** will be used as the ORM provider. And on the front-end side {{UI_Value}} and JavaScript will be used. +In this tutorial series, you will build an ABP application named `Acme.BookStore`. In this sample project, we will manage a list of books and authors. **{{DB_Text}}** will be used as the ORM provider. And on the front-end side {{UI_Value}} and JavaScript will be used. The ASP.NET Core {{UI_Value}} tutorial series consists of 3 parts: @@ -34,14 +34,14 @@ The ASP.NET Core {{UI_Value}} tutorial series consists of 3 parts: ### Creating the project -Create a new project named `Acme.BookStore` where `Acme` is the company name and `BookStore` is the project name. You can check out [creating a new project](../Getting-Started-{{if UI == 'NG'}}Angular{{else}}AspNetCore-MVC{{end}}-Template#creating-a-new-project) document to see how you can create a new project. We will create the project with ABP CLI. But first of all, we need to login to the ABP Platform to create a commercial project. +Create a new project named `Acme.BookStore` where `Acme` is the company name and `BookStore` is the project name. You can check out [creating a new project](../Getting-Started-{{if UI == 'NG'}}Angular{{else}}AspNetCore-MVC{{end}}-Template#creating-a-new-project) document to see how you can create a new project. We will create the project with ABP CLI. #### Create the project -By running the below command, it creates a new ABP Commercial project with the database provider `{{DB_Text}}` and UI option `MVC`. To see the other CLI options, check out [ABP CLI](https://docs.abp.io/en/abp/latest/CLI) document. +By running the below command, it creates a new ABP project with the database provider `{{DB_Text}}` and UI option `MVC`. To see the other CLI options, check out [ABP CLI](https://docs.abp.io/en/abp/latest/CLI) document. ```bash -abp new Acme.BookStore --template app --database-provider {{DB}} --ui {{UI_Text}} +abp new Acme.BookStore --template app --database-provider {{DB}} --ui {{UI_Text}} --mobile none ``` ![Creating project](./images/bookstore-create-project-{{UI_Text}}.png) @@ -982,11 +982,13 @@ import { GetBooks } from '../actions/books.actions'; import { Books } from '../models/books'; import { BooksService } from '../../books/shared/books.service'; import { tap } from 'rxjs/operators'; +import { Injectable } from '@angular/core'; @State({ name: 'BooksState', defaults: { books: {} } as Books.State, }) +@Injectable() export class BooksState { @Selector() static getBooks(state: Books.State) { diff --git a/docs/en/Tutorials/Part-2.md b/docs/en/Tutorials/Part-2.md index 08e17e0e3f..9565724cb8 100644 --- a/docs/en/Tutorials/Part-2.md +++ b/docs/en/Tutorials/Part-2.md @@ -574,11 +574,13 @@ import { GetBooks, CreateUpdateBook } from '../actions/books.actions'; //<== add import { Books } from '../models/books'; import { BooksService } from '../../books/shared/books.service'; import { tap } from 'rxjs/operators'; +import { Injectable } from '@angular/core'; @State({ name: 'BooksState', defaults: { books: {} } as Books.State, }) +@Injectable() export class BooksState { @Selector() static getBooks(state: Books.State) { @@ -688,7 +690,7 @@ Open `book-list.component.html` file in `books\book-list` folder and replace the * `abp-modal` is a pre-built component to show modals. While you could use another approach to show a modal, `abp-modal` provides additional benefits. * We added `New book` button to the `AbpContentToolbar`. -Open `book-list.component.` file in `books\book-list` folder and replace the content as below: +Open `book-list.component.ts` file in `books\book-list` folder and replace the content as below: ```js import { Component, OnInit } from '@angular/core'; @@ -1330,11 +1332,13 @@ import { GetBooks, CreateUpdateBook, DeleteBook } from '../actions/books.actions import { Books } from '../models/books'; import { BooksService } from '../../books/shared/books.service'; import { tap } from 'rxjs/operators'; +import { Injectable } from '@angular/core'; @State({ name: 'BooksState', defaults: { books: {} } as Books.State, }) +@Injectable() export class BooksState { @Selector() static getBooks(state: Books.State) { diff --git a/docs/en/UI/Angular/Dom-Insertion-Service.md b/docs/en/UI/Angular/Dom-Insertion-Service.md index d5ea9fe3a2..489a7a4e1f 100644 --- a/docs/en/UI/Angular/Dom-Insertion-Service.md +++ b/docs/en/UI/Angular/Dom-Insertion-Service.md @@ -35,17 +35,19 @@ class DemoComponent { constructor(private domInsertionService: DomInsertionService) {} ngOnInit() { - this.domInsertionService.insertContent( + const scriptElement = this.domInsertionService.insertContent( CONTENT_STRATEGY.AppendScriptToBody('alert()') ); } } ``` -In the example above, `` element will place at the **end** of ``. +In the example above, `` element will place at the **end** of `` and `scriptElement` will be an `HTMLScriptElement`. Please refer to [ContentStrategy](./Content-Strategy.md) to see all available content strategies and how you can build your own content strategy. +> Important Note: `DomInsertionService` does not insert the same content twice. In order to add a content again, you first should remove the old content using `removeContent` method. + ### How to Insert Styles If you pass a `StyleContentStrategy` instance as the first parameter of `insertContent` method, the `DomInsertionService` will create a `` element will place at the **end** of ``. +In the example above, `` element will place at the **end** of `` and `styleElement` will be an `HTMLStyleElement`. Please refer to [ContentStrategy](./Content-Strategy.md) to see all available content strategies and how you can build your own content strategy. +> Important Note: `DomInsertionService` does not insert the same content twice. In order to add a content again, you first should remove the old content using `removeContent` method. + +### How to Remove Inserted Scripts & Styles + +If you pass the inserted `HTMLScriptElement` or `HTMLStyleElement` element as the first parameter of `removeContent` method, the `DomInsertionService` will remove the given element. + +```js +import { DomInsertionService, CONTENT_STRATEGY } from '@abp/ng.core'; + +@Component({ + /* class metadata here */ +}) +class DemoComponent { + private styleElement: HTMLStyleElement; + + constructor(private domInsertionService: DomInsertionService) {} + + ngOnInit() { + this.styleElement = this.domInsertionService.insertContent( + CONTENT_STRATEGY.AppendStyleToHead('body {margin: 0;}') + ); + } + + ngOnDestroy() { + this.domInsertionService.removeContent(this.styleElement); + } +} +``` + +In the example above, `` element **will be removed** from `` when the component is destroyed. + ## API ### insertContent ```js -insertContent(contentStrategy: ContentStrategy): void +insertContent( + contentStrategy: ContentStrategy, +): T ``` - `contentStrategy` parameter is the primary focus here and is explained above. +- returns `HTMLScriptElement` or `HTMLStyleElement` based on given strategy. + +### removeContent + +```js +removeContent(element: HTMLScriptElement | HTMLStyleElement): void +``` +- `element` parameter is the inserted `HTMLScriptElement` or `HTMLStyleElement` element, which was returned by `insertContent` method. ## What's Next? diff --git a/docs/en/UI/AspNetCore/Tag-Helpers/Dynamic-Forms.md b/docs/en/UI/AspNetCore/Tag-Helpers/Dynamic-Forms.md index 6d700f030d..5b4b766a27 100644 --- a/docs/en/UI/AspNetCore/Tag-Helpers/Dynamic-Forms.md +++ b/docs/en/UI/AspNetCore/Tag-Helpers/Dynamic-Forms.md @@ -1,3 +1,277 @@ -## Dynamic Forms +# Dynamic Forms + +`Warning:` Before getting into this document, be sure that you have clearly understood [abp form elements](Form-elements.md) document. + +## Introduction + +`abp-dynamic-form` creates a bootstrap form for a given c# model. + +Basic usage: + +````xml + +```` +Model: +````csharp +public class DynamicFormsModel : PageModel + { + [BindProperty] + public DetailedModel MyDetailedModel { get; set; } + + public List CountryList { get; set; } = new List + { + new SelectListItem { Value = "CA", Text = "Canada"}, + new SelectListItem { Value = "US", Text = "USA"}, + new SelectListItem { Value = "UK", Text = "United Kingdom"}, + new SelectListItem { Value = "RU", Text = "Russia"} + }; + + public void OnGet() + { + MyDetailedModel = new DetailedModel + { + Name = "", + Description = "Lorem ipsum dolor sit amet.", + IsActive = true, + Age = 65, + Day = DateTime.Now, + MyCarType = CarType.Coupe, + YourCarType = CarType.Sedan, + Country = "RU", + NeighborCountries = new List() { "UK", "CA" } + }; + } + + public class DetailedModel + { + [Required] + [Placeholder("Enter your name...")] + [Display(Name = "Name")] + public string Name { get; set; } + + [TextArea(Rows = 4)] + [Display(Name = "Description")] + [InputInfoText("Describe Yourself")] + public string Description { get; set; } + + [Required] + [DataType(DataType.Password)] + [Display(Name = "Password")] + public string Password { get; set; } + + [Display(Name = "Is Active")] + public bool IsActive { get; set; } + + [Required] + [Display(Name = "Age")] + public int Age { get; set; } + + [Required] + [Display(Name = "My Car Type")] + public CarType MyCarType { get; set; } + + [Required] + [AbpRadioButton(Inline = true)] + [Display(Name = "Your Car Type")] + public CarType YourCarType { get; set; } + + [DataType(DataType.Date)] + [Display(Name = "Day")] + public DateTime Day { get; set; } + + [SelectItems(nameof(CountryList))] + [Display(Name = "Country")] + public string Country { get; set; } + + [SelectItems(nameof(CountryList))] + [Display(Name = "Neighbor Countries")] + public List NeighborCountries { get; set; } + } + + public enum CarType + { + Sedan, + Hatchback, + StationWagon, + Coupe + } + } +```` +## Demo + +See the [dynamic forms demo page](https://bootstrap-taghelpers.abp.io/Components/DynamicForms) to see it in action. + +## Attributes + +### abp-model + +Sets the c# model for dynamic form. Properties of this modal are turned into inputs in the form. + +### submit-button + +Can be `True` or `False`. + +If `True`, a submit button will be generated at the bottom of the form. + +Default value is `False`. + +### required-symbols + +Can be `True` or `False`. + +If `True`, required inputs will have a symbol (*) that indicates they are required. + +Default value is `True`. + +## Form Content Placement + +By default, `abp-dynamicform` clears the inner html and places the inputs into itself. If you want to add additional content to dynamic form or place the inputs to some specific area, you can use ` ` tag. This tag will be replaced by form content and rest of the inner html of `abp-dynamic-form` tag will be unchanged. + +Usage: + +````xml + +
+ Some content.... +
+
+ +
+
+ Some more content.... +
+ +```` + +## Input Order + +`abp-dynamic-form` orders the properties by their `DisplayOrder` attribute and then their property order in model class. + +Default `DisplayOrder` attribute number is 10000 for every property. + +See example below: + +````csharp + public class OrderExampleModel + { + [DisplayOrder(10004)] + public string Name{ get; set; } + + [DisplayOrder(10005)] + public string Surname{ get; set; } + + //Default 10000 + public string EmailAddress { get; set; } + + [DisplayOrder(10003)] + public string PhoneNumber { get; set; } + + [DisplayOrder(9999)] + public string City { get; set; } + } +```` + +In this example, input fields will be displayed with this order: `City` > `EmailAddress` > `PhoneNumber` > `Name` > `Surname`. + +## Ignoring a property + +By default, `abp-dynamic-form` generates input for every property in model class. If you want to ignore a property, use `DynamicFormIgnore` attribute. + +See example below: + +````csharp + public class MyModel + { + public string Name { get; set; } + + [DynamicFormIgnore] + public string Surname { get; set; } + } +```` + +In this example, no input will be generated for `Surname` property. + +## Indicating Text box, Radio Group and Combobox + +If you have read the [Form elements document](Form-elements.md), you noticed that `abp-radio` and `abp-select` tags are very similar on c# model. So we have to use `[AbpRadioButton()]` attribute to tell `abp-dynamic-form` which of your properties will be radio group and which will be combobox. See example below: + +````xml + +```` +Model: +````csharp +public class DynamicFormsModel : PageModel + { + [BindProperty] + public DetailedModel MyDetailedModel { get; set; } + + public List CountryList { get; set; } = new List + { + new SelectListItem { Value = "CA", Text = "Canada"}, + new SelectListItem { Value = "US", Text = "USA"}, + new SelectListItem { Value = "UK", Text = "United Kingdom"}, + new SelectListItem { Value = "RU", Text = "Russia"} + }; + + public void OnGet() + { + MyDetailedModel = new DetailedModel + { + ComboCarType = CarType.Coupe, + RadioCarType = CarType.Sedan, + ComboCountry = "RU", + RadioCountry = "UK" + }; + } + + public class DetailedModel + { + public CarType ComboCarType { get; set; } + + [AbpRadioButton(Inline = true)] + public CarType RadioCarType { get; set; } + + [SelectItems(nameof(CountryList))] + public string ComboCountry { get; set; } + + [AbpRadioButton()] + [SelectItems(nameof(CountryList))] + public string RadioCountry { get; set; } + } + + public enum CarType + { + Sedan, + Hatchback, + StationWagon, + Coupe + } + } +```` + +As you see in example above: + +* If `[AbpRadioButton()]` are used on a **Enum** property, it will be a radio group. Otherwise, combobox. +* If `[SelectItems()]` and `[AbpRadioButton()]` are used on a property, it will be a radio group. +* If just `[SelectItems()]` is used on a property, it will be a combobox. +* If none of these attributes are used on a property, it will be a text box. + +## Localization + +`abp-dynamic-form` handles localization as well. + +By default, it will try to find "DisplayName:{PropertyName}" or "{PropertyName}" localization keys and set the localization value as input label. + +You can set it yourself by using `[Display()]` attribute of Asp.Net Core. You can use a localization key in this attribute. See example below: + +````csharp + [Display(Name = "Name")] + public string Name { get; set; } +```` + + + + + + -This is not documented yet. You can see a [demo](http://bootstrap-taghelpers.abp.io/Components/DynamicForms) for now. \ No newline at end of file diff --git a/docs/en/UI/AspNetCore/Tag-Helpers/Form-elements.md b/docs/en/UI/AspNetCore/Tag-Helpers/Form-elements.md new file mode 100644 index 0000000000..df23fd649c --- /dev/null +++ b/docs/en/UI/AspNetCore/Tag-Helpers/Form-elements.md @@ -0,0 +1,261 @@ +# Form Elements + +## Introduction + +Abp provides form input tag helpers to make building forms easier. + +## Demo + +See the [form elements demo page](https://bootstrap-taghelpers.abp.io/Components/FormElements) to see it in action. + +## abp-input + +`abp-input` tag creates a Bootstrap form input for a given c# property. It uses [Asp.Net Core Input Tag Helper](https://docs.microsoft.com/tr-tr/aspnet/core/mvc/views/working-with-forms?view=aspnetcore-3.1#the-input-tag-helper) in background, so every data annotation attribute of `input` tag helper of Asp.Net Core is also valid for `abp-input`. + +Usage: + +````xml + + + + +```` + +Model: + +````csharp + public class FormElementsModel : PageModel + { + public SampleModel MyModel { get; set; } + + public void OnGet() + { + MyModel = new SampleModel(); + } + + public class SampleModel + { + [Required] + [Placeholder("Enter your name...")] + [InputInfoText("What is your name?")] + public string Name { get; set; } + + [Required] + [FormControlSize(AbpFormControlSize.Large)] + public string SurName { get; set; } + + [TextArea(Rows = 4)] + public string Description { get; set; } + + [Required] + [DataType(DataType.Password)] + public string Password { get; set; } + + public bool IsActive { get; set; } + } + } +```` + +### Attributes + +You can set some of the attributes on your c# property, or directly on html tag. If you are going to use this property in a [abp-dynamic-form](Dynamic-forms.md), then you can only set these properties via property attributes. + +#### Property Attributes + +- `[TextArea()]`: Converts the input into a text area. + +* `[Placeholder()]`: Sets placeholder for input. You can use a localization key directly. +* `[InputInfoText()]`: Sets a small info text for input. You can use a localization key directly. +* `[FormControlSize()]`: Sets size of form-control wrapper element. Available values are + - `AbpFormControlSize.Default` + - `AbpFormControlSize.Small` + - `AbpFormControlSize.Medium` + - `AbpFormControlSize.Large` +* `[DisabledInput]` : Input is disabled. +* `[ReadOnlyInput]`: Input is read-only. + +#### Tag Attributes + +* `info`: Sets a small info text for input. You can use a localization key directly. +* `auto-focus`: If true, browser auto focuses on the element. +* `size`: Sets size of form-control wrapper element. Available values are + - `AbpFormControlSize.Default` + - `AbpFormControlSize.Small` + - `AbpFormControlSize.Medium` + - `AbpFormControlSize.Large` +* `disabled`: Input is disabled. +* `readonly`: Input is read-only. +* `label`: Sets the label for input. +* `display-required-symbol`: Adds the required symbol (*) to label if input is required. Default `True`. + +### Label & Localization + +You can set label of your input in different ways: + +- You can use `Label` attribute and directly set the label. But it doesn't auto localize your localization key. So use it as `label="@L["{LocalizationKey}"].Value"`. +- You can set it using `[Display(name="{LocalizationKey}")]` attribute of Asp.Net Core. +- You can just let **abp** find the localization key for the property. It will try to find "DisplayName:{PropertyName}" or "{PropertyName}" localization keys, if `label` or `[DisplayName]` attributes are not set. + +## abp-select + +`abp-select` tag creates a Bootstrap form select for a given c# property. It uses [Asp.Net Core Select Tag Helper](https://docs.microsoft.com/tr-tr/aspnet/core/mvc/views/working-with-forms?view=aspnetcore-3.1#the-select-tag-helper) in background, so every data annotation attribute of `select` tag helper of Asp.Net Core is also valid for `abp-select`. + +`abp-select` tag needs a list of `Microsoft.AspNetCore.Mvc.Rendering.SelectListItem ` to work. It can be provided by `asp-items` attriube on the tag or `[SelectItems()]` attribute on c# property. (if you are using [abp-dynamic-form](Dynamic-forms.md), c# attribute is the only way.) + +`abp-select` supports multiple selection. + +`abp-select` auto-creates a select list for **Enum** properties. No extra data is needed. If property is nullable, an empty key and value is added to top of the auto-generated list. + +Usage: + +````xml + + + + + + + + + +```` + +Model: + +````csharp + public class FormElementsModel : PageModel + { + public SampleModel MyModel { get; set; } + + public List CityList { get; set; } + + public void OnGet() + { + MyModel = new SampleModel(); + + CityList = new List + { + new SelectListItem { Value = "NY", Text = "New York"}, + new SelectListItem { Value = "LDN", Text = "London"}, + new SelectListItem { Value = "IST", Text = "Istanbul"}, + new SelectListItem { Value = "MOS", Text = "Moscow"} + }; + } + + public class SampleModel + { + public string City { get; set; } + + [SelectItems(nameof(CityList))] + public string AnotherCity { get; set; } + + public List MultipleCities { get; set; } + + public CarType MyCarType { get; set; } + + public CarType? MyNullableCarType { get; set; } + } + + public enum CarType + { + Sedan, + Hatchback, + StationWagon, + Coupe + } + } +```` + +### Attributes + +You can set some of the attributes on your c# property, or directly on html tag. If you are going to use this property in a [abp-dynamic-form](Dynamic-forms.md), then you can only set these properties via property attributes. + +#### Property Attributes + +* `[SelectItems()]`: Sets the select data. Parameter should be the name of the data list. (see example above) + +- `[InputInfoText()]`: Sets a small info text for input. You can use a localization key directly. +- `[FormControlSize()]`: Sets size of form-control wrapper element. Available values are + - `AbpFormControlSize.Default` + - `AbpFormControlSize.Small` + - `AbpFormControlSize.Medium` + - `AbpFormControlSize.Large` + +#### Tag Attributes + +- `asp-items`: Sets the select data. This Should be a list of SelectListItem. +- `info`: Sets a small info text for input. You can use a localization key directly. +- `size`: Sets size of form-control wrapper element. Available values are + - `AbpFormControlSize.Default` + - `AbpFormControlSize.Small` + - `AbpFormControlSize.Medium` + - `AbpFormControlSize.Large` +- `label`: Sets the label for input. +- `display-required-symbol`: Adds the required symbol (*) to label if input is required. Default `True`. + +### Label & Localization + +You can set label of your input in different ways: + +- You can use `Label` attribute and directly set the label. But it doesn't auto localize your localization key. So use it as `label="@L["{LocalizationKey}"].Value".` +- You can set it using `[Display(name="{LocalizationKey}")]` attribute of Asp.Net Core. +- You can just let **abp** find the localization key for the property. It will try to find "DisplayName:{PropertyName}" or "{PropertyName}" localization keys. + +Localizations of combobox values are set by `abp-select` for **Enum** property. It searches for "{EnumTypeName}.{EnumPropertyName}" or "{EnumPropertyName}" localization keys. For instance, in the example above, it will use "CarType.StationWagon" or "StationWagon" keys for localization when it localizes combobox values. + +## abp-radio + +`abp-radio` tag creates a Bootstrap form radio group for a given c# property. Usage is very similar to `abp-select` tag. + +Usage: + +````xml + + + +```` + +Model: + +````csharp + public class FormElementsModel : PageModel + { + public SampleModel MyModel { get; set; } + + public List CityList { get; set; } = new List + { + new SelectListItem { Value = "NY", Text = "New York"}, + new SelectListItem { Value = "LDN", Text = "London"}, + new SelectListItem { Value = "IST", Text = "Istanbul"}, + new SelectListItem { Value = "MOS", Text = "Moscow"} + }; + + public void OnGet() + { + MyModel = new SampleModel(); + MyModel.CityRadio = "IST"; + MyModel.CityRadio2 = "MOS"; + } + + public class SampleModel + { + public string CityRadio { get; set; } + + [SelectItems(nameof(CityList))] + public string CityRadio2 { get; set; } + } + } +```` + +### Attributes + +You can set some of the attributes on your c# property, or directly on html tag. If you are going to use this property in a [abp-dynamic-form](Dynamic-forms.md), then you can only set these properties via property attributes. + +#### Property Attributes + +- `[SelectItems()]`: Sets the select data. Parameter should be the name of the data list. (see example above) + +#### Tag Attributes + +- `asp-items`: Sets the select data. This Should be a list of SelectListItem. +- `Inline`: If true, radio buttons will be in single line, next to each other. If false, they will be under each other. \ No newline at end of file diff --git a/docs/en/UI/AspNetCore/Tag-Helpers/Index.md b/docs/en/UI/AspNetCore/Tag-Helpers/Index.md index a7aa0b65d2..229460de92 100644 --- a/docs/en/UI/AspNetCore/Tag-Helpers/Index.md +++ b/docs/en/UI/AspNetCore/Tag-Helpers/Index.md @@ -12,18 +12,18 @@ ABP Framework also adds some **useful features** to the standard bootstrap compo Here, the list of components those are wrapped by the ABP Framework: +* [Alerts](Alerts.md) * [Buttons](Buttons.md) * [Cards](Cards.md) -* [Alerts](Alerts.md) -* [Tabs](Tabs.md) -* [Grids](Grids.md) -* [Modals](Modals.md) * [Collapse](Collapse.md) * [Dropdowns](Dropdowns.md) +* [Grids](Grids.md) * [List Groups](List-Groups.md) +* [Modals](Modals.md) * [Paginator](Paginator.md) * [Popovers](Popovers.md) * [Progress Bars](Progress-Bars.md) +* [Tabs](Tabs.md) * [Tooltips](Tooltips.md) * ... @@ -31,8 +31,8 @@ Here, the list of components those are wrapped by the ABP Framework: ## Form Elements -See [demo](https://bootstrap-taghelpers.abp.io/Components/FormElements). +**Abp Tag Helpers** add new features to standard **Asp.Net Core MVC input & select Tag Helpers** and wrap them with **Bootstrap** form controls. See [Form Elements documentation](Form-elements.md) . -## Dynamic Inputs +## Dynamic Forms -See [demo](https://bootstrap-taghelpers.abp.io/Components/DynamicForms). \ No newline at end of file +**Abp Tag helpers** offer an easy way to build complete **Bootstrap forms**. See [Dynamic Forms documentation](Dynamic-Forms.md). \ No newline at end of file diff --git a/docs/en/UI/AspNetCore/Tag-Helpers/List-Groups.md b/docs/en/UI/AspNetCore/Tag-Helpers/List-Groups.md index b1e6e7f499..08b942bd09 100644 --- a/docs/en/UI/AspNetCore/Tag-Helpers/List-Groups.md +++ b/docs/en/UI/AspNetCore/Tag-Helpers/List-Groups.md @@ -19,7 +19,7 @@ Basic usage: ## Demo -See the [list groups demo page](https://bootstrap-taghelpers.abp.io/Components/ListGroups) to see it in action. +See the [list groups demo page](https://bootstrap-taghelpers.abp.io/Components/ListGroup) to see it in action. ## Attributes diff --git a/docs/en/UI/AspNetCore/Tag-Helpers/Progress-Bars.md b/docs/en/UI/AspNetCore/Tag-Helpers/Progress-Bars.md index dc69f7e47e..1f723f80ae 100644 --- a/docs/en/UI/AspNetCore/Tag-Helpers/Progress-Bars.md +++ b/docs/en/UI/AspNetCore/Tag-Helpers/Progress-Bars.md @@ -26,7 +26,7 @@ Basic usage: ## Demo -See the [progress bars demo page](https://bootstrap-taghelpers.abp.io/Components/Progress-Bars) to see it in action. +See the [progress bars demo page](https://bootstrap-taghelpers.abp.io/Components/Progressbars) to see it in action. ## Attributes @@ -67,4 +67,4 @@ A value indicates if the background style of the progress bar is stripped. Shoul A value indicates if the stripped background style of the progress bar is animated. Should be one of the following values: * `false` (default value) -* `true` \ No newline at end of file +* `true` diff --git a/docs/en/UI/Common/Utils/Linked-List.md b/docs/en/UI/Common/Utils/Linked-List.md index 5da9cc10e9..0d6b259603 100644 --- a/docs/en/UI/Common/Utils/Linked-List.md +++ b/docs/en/UI/Common/Utils/Linked-List.md @@ -2,20 +2,29 @@ -The core module provides a useful data structure known as a [doubly linked list](https://en.wikipedia.org/wiki/Doubly_linked_list). Briefly, a doubly linked list is a series of records (a.k.a. nodes) which has information on the previous node, the next node, and its own value (or data). +The @abp/utils package provides a useful data structure known as a [doubly linked list](https://en.wikipedia.org/wiki/Doubly_linked_list). It is availabe in both Angular (via an import) and MVC (via `abp.utils.common` global object). + +Briefly, a doubly linked list is a series of records (a.k.a. nodes) which has information on the previous node, the next node, and its own value (or data). ## Getting Started -To create a doubly linked list, all you have to do is to import and create a new instance of it: +To create a doubly linked list, all you have to do is to create a new instance of it: + +In Angular: ```js -import { LinkedList } from '@abp/ng.core'; +import { LinkedList } from '@abp/utils'; const list = new LinkedList(); ``` +In MVC: + +```js +var list = new abp.utils.common.LinkedList(); +``` The constructor does not get any parameters. @@ -33,7 +42,7 @@ There are several methods to create new nodes in a linked list and all of them a #### addHead(value) ```js -addHead(value: T): ListNode\ +addHead(value: T): ListNode ``` Adds a node with given value as the first node in list: @@ -57,7 +66,7 @@ list.addHead('c'); #### addManyHead(values) ```js -addManyHead(values: T\[\]): ListNode\\[\] +addManyHead(values: T[]): ListNode[] ``` Adds multiple nodes with given values as the first nodes in list: @@ -77,7 +86,7 @@ list.addManyHead(['x', 'y', 'z']); #### addTail(value) ```js -addTail(value: T): ListNode\ +addTail(value: T): ListNode ``` Adds a node with given value as the last node in list: @@ -101,7 +110,7 @@ list.addTail('c'); #### addManyTail(values) ```js -addManyTail(values: T\[\]): ListNode\\[\] +addManyTail(values: T[]): ListNode[] ``` Adds multiple nodes with given values as the last nodes in list: @@ -118,10 +127,10 @@ list.addManyTail(['x', 'y', 'z']); -#### addAfter(value, previousValue, compareFn) +#### addAfter(value, previousValue [, compareFn]) ```js -addAfter(value: T, previousValue: T, compareFn = compare): ListNode\ +addAfter(value: T, previousValue: T, compareFn?: ListComparisonFn): ListNode ``` Adds a node with given value after the first node that has the previous value: @@ -165,10 +174,10 @@ list.addAfter( -#### addManyAfter(values, previousValue, compareFn) +#### addManyAfter(values, previousValue [, compareFn]) ```js -addManyAfter(values: T\[\], previousValue: T, compareFn = compare): ListNode\\[\] +addManyAfter(values: T[], previousValue: T, compareFn?: ListComparisonFn): ListNode[] ``` Adds multiple nodes with given values after the first node that has the previous value: @@ -207,10 +216,10 @@ list.addManyAfter( -#### addBefore(value, nextValue, compareFn) +#### addBefore(value, nextValue [, compareFn]) ```js -addBefore(value: T, nextValue: T, compareFn = compare): ListNode\ +addBefore(value: T, nextValue: T, compareFn?: ListComparisonFn): ListNode ``` Adds a node with given value before the first node that has the next value: @@ -254,10 +263,10 @@ list.addBefore( -#### addManyBefore(values, nextValue, compareFn) +#### addManyBefore(values, nextValue [, compareFn]) ```js -addManyBefore(values: T\[\], nextValue: T, compareFn = compare): ListNode\\[\] +addManyBefore(values: T[], nextValue: T, compareFn?: ListComparisonFn): ListNode[] ``` Adds multiple nodes with given values before the first node that has the next value: @@ -299,7 +308,7 @@ list.addManyBefore( #### addByIndex(value, position) ```js -addByIndex(value: T, position: number): ListNode\ +addByIndex(value: T, position: number): ListNode ``` Adds a node with given value at the specified position in the list: @@ -337,7 +346,7 @@ list.addByIndex('x', -1); #### addManyByIndex(values, position) ```js -addManyByIndex(values: T\[\], position: number): ListNode\\[\] +addManyByIndex(values: T[], position: number): ListNode[] ``` Adds multiple nodes with given values at the specified position in the list: @@ -371,7 +380,7 @@ list.addManyByIndex(['x', 'y'], -1); #### add(value).head() ```js -add(value: T).head(): ListNode\ +add(value: T).head(): ListNode ``` Adds a node with given value as the first node in list: @@ -399,7 +408,7 @@ list.add('c').head(); #### add(value).tail() ```js -add(value: T).tail(): ListNode\ +add(value: T).tail(): ListNode ``` Adds a node with given value as the last node in list: @@ -424,10 +433,10 @@ list.add('c').tail(); -#### add(value).after(previousValue, compareFn) +#### add(value).after(previousValue [, compareFn]) ```js -add(value: T).after(previousValue: T, compareFn = compare): ListNode\ +add(value: T).after(previousValue: T, compareFn?: ListComparisonFn): ListNode ``` Adds a node with given value after the first node that has the previous value: @@ -471,10 +480,10 @@ list -#### add(value).before(nextValue, compareFn) +#### add(value).before(nextValue [, compareFn]) ```js -add(value: T).before(nextValue: T, compareFn = compare): ListNode\ +add(value: T).before(nextValue: T, compareFn?: ListComparisonFn): ListNode ``` Adds a node with given value before the first node that has the next value: @@ -521,7 +530,7 @@ list #### add(value).byIndex(position) ```js -add(value: T).byIndex(position: number): ListNode\ +add(value: T).byIndex(position: number): ListNode ``` Adds a node with given value at the specified position in the list: @@ -563,7 +572,7 @@ list.add('x').byIndex(-1); #### addMany(values).head() ```js -addMany(values: T\[\]).head(): ListNode\\[\] +addMany(values: T[]).head(): ListNode[] ``` Adds multiple nodes with given values as the first nodes in list: @@ -587,7 +596,7 @@ list.addMany(['x', 'y', 'z']).head(); #### addMany(values).tail() ```js -addMany(values: T\[\]).tail(): ListNode\\[\] +addMany(values: T[]).tail(): ListNode[] ``` Adds multiple nodes with given values as the last nodes in list: @@ -608,10 +617,10 @@ list.addMany(['x', 'y', 'z']).tail(); -#### addMany(values).after(previousValue, compareFn) +#### addMany(values).after(previousValue [, compareFn]) ```js -addMany(values: T\[\]).after(previousValue: T, compareFn = compare): ListNode\\[\] +addMany(values: T[]).after(previousValue: T, compareFn?: ListComparisonFn): ListNode[] ``` Adds multiple nodes with given values after the first node that has the previous value: @@ -650,10 +659,10 @@ list -#### addMany(values).before(nextValue, compareFn) +#### addMany(values).before(nextValue [, compareFn]) ```js -addMany(values: T\[\]).before(nextValue: T, compareFn = compare): ListNode\\[\] +addMany(values: T[]).before(nextValue: T, compareFn?: ListComparisonFn): ListNode[] ``` Adds multiple nodes with given values before the first node that has the next value: @@ -695,7 +704,7 @@ list #### addMany(values).byIndex(position) ```js -addMany(values: T\[\]).byIndex(position: number): ListNode\\[\] +addMany(values: T[]).byIndex(position: number): ListNode[] ``` Adds multiple nodes with given values at the specified position in the list: @@ -739,7 +748,7 @@ There are a few methods to remove nodes from a linked list and all of them are s #### dropHead() ```js -dropHead(): ListNode\ | undefined +dropHead(): ListNode | undefined ``` Removes the first node from the list: @@ -759,7 +768,7 @@ list.dropHead(); #### dropManyHead(count) ```js -dropManyHead(count: number): ListNode\\[\] +dropManyHead(count: number): ListNode[] ``` Removes the first nodes from the list based on given count: @@ -779,7 +788,7 @@ list.dropManyHead(2); #### dropTail() ```js -dropTail(): ListNode\ | undefined +dropTail(): ListNode | undefined ``` Removes the last node from the list: @@ -799,7 +808,7 @@ list.dropTail(); #### dropManyTail(count) ```js -dropManyTail(count: number): ListNode\\[\] +dropManyTail(count: number): ListNode[] ``` Removes the last nodes from the list based on given count: @@ -819,7 +828,7 @@ list.dropManyTail(2); #### dropByIndex(position) ```js -dropByIndex(position: number): ListNode\ | undefined +dropByIndex(position: number): ListNode | undefined ``` Removes the node with the specified position from the list: @@ -853,7 +862,7 @@ list.dropByIndex(-2); #### dropManyByIndex(count, position) ```js -dropManyByIndex(count: number, position: number): ListNode\\[\] +dropManyByIndex(count: number, position: number): ListNode[] ``` Removes the nodes starting from the specified position from the list based on given count: @@ -884,10 +893,10 @@ list.dropManyByIndex(2, -2); -#### dropByValue(value, compareFn) +#### dropByValue(value [, compareFn]) ```js -dropByValue(value: T, compareFn = compare): ListNode\ | undefined +dropByValue(value: T, compareFn?: ListComparisonFn): ListNode | undefined ``` Removes the first node with given value from the list: @@ -922,10 +931,10 @@ list.dropByValue(0, (value, searchedValue) => value.x === searchedValue); -#### dropByValueAll(value, compareFn) +#### dropByValueAll(value [, compareFn]) ```js -dropByValueAll(value: T, compareFn = compare): ListNode\\[\] +dropByValueAll(value: T, compareFn?: ListComparisonFn): ListNode[] ``` Removes all nodes with given value from the list: @@ -963,7 +972,7 @@ list.dropByValue(0, (value, searchedValue) => value.x === searchedValue); #### drop().head() ```js -drop().head(): ListNode\ | undefined +drop().head(): ListNode | undefined ``` Removes the first node in list: @@ -987,7 +996,7 @@ list.drop().head(); #### drop().tail() ```js -drop().tail(): ListNode\ | undefined +drop().tail(): ListNode | undefined ``` Removes the last node in list: @@ -1011,7 +1020,7 @@ list.drop().tail(); #### drop().byIndex(position) ```js -drop().byIndex(position: number): ListNode\ | undefined +drop().byIndex(position: number): ListNode | undefined ``` Removes the node with the specified position from the list: @@ -1046,10 +1055,10 @@ list.drop().byIndex(-2); -#### drop().byValue(value, compareFn) +#### drop().byValue(value [, compareFn]) ```js -drop().byValue(value: T, compareFn = compare): ListNode\ | undefined +drop().byValue(value: T, compareFn?: ListComparisonFn): ListNode | undefined ``` Removes the first node with given value from the list: @@ -1088,10 +1097,10 @@ list -#### drop().byValueAll(value, compareFn) +#### drop().byValueAll(value [, compareFn]) ```js -drop().byValueAll(value: T, compareFn = compare): ListNode\\[\] +drop().byValueAll(value: T, compareFn?: ListComparisonFn): ListNode[] ``` Removes all nodes with given value from the list: @@ -1133,7 +1142,7 @@ list #### dropMany(count).head() ```js -dropMany(count: number).head(): ListNode\\[\] +dropMany(count: number).head(): ListNode[] ``` Removes the first nodes from the list based on given count: @@ -1157,7 +1166,7 @@ list.dropMany(2).head(); #### dropMany(count).tail() ```js -dropMany(count: number).tail(): ListNode\\[\] +dropMany(count: number).tail(): ListNode[] ``` Removes the last nodes from the list based on given count: @@ -1181,7 +1190,7 @@ list.dropMany(2).tail(); #### dropMany(count).byIndex(position) ```js -dropMany(count: number).byIndex(position: number): ListNode\\[\] +dropMany(count: number).byIndex(position: number): ListNode[] ``` Removes the nodes starting from the specified position from the list based on given count: @@ -1222,10 +1231,40 @@ There are a few methods to find specific nodes in a linked list. +#### head + +```js +head: ListNode | undefined; +``` + +Refers to the first node in the list. + + + +#### tail + +```js +tail: ListNode | undefined; +``` + +Refers to the last node in the list. + + + +#### length + +```js +length: number; +``` + +Is the total number of nodes in the list. + + + #### find(predicate) ```js -find(predicate: ListIteratorFunction\): ListNode\ | undefined +find(predicate: ListIteratorFn): ListNode | undefined ``` Finds the first node from the list that matches the given predicate: @@ -1235,7 +1274,7 @@ list.addTailMany(['a', 'b', 'b', 'c']); // "a" <-> "b" <-> "b" <-> "c" -const found = list.find(node => node.value === 'b'); +var found = list.find(node => node.value === 'b'); /* found.value === "b" @@ -1249,7 +1288,7 @@ found.next.value === "b" #### findIndex(predicate) ```js -findIndex(predicate: ListIteratorFunction\): number +findIndex(predicate: ListIteratorFn): number ``` Finds the position of the first node from the list that matches the given predicate: @@ -1259,10 +1298,10 @@ list.addTailMany(['a', 'b', 'b', 'c']); // "a" <-> "b" <-> "b" <-> "c" -const i0 = list.findIndex(node => node.next && node.next.value === 'b'); -const i1 = list.findIndex(node => node.value === 'b'); -const i2 = list.findIndex(node => node.previous && node.previous.value === 'b'); -const i3 = list.findIndex(node => node.value === 'x'); +var i0 = list.findIndex(node => node.next && node.next.value === 'b'); +var i1 = list.findIndex(node => node.value === 'b'); +var i2 = list.findIndex(node => node.previous && node.previous.value === 'b'); +var i3 = list.findIndex(node => node.value === 'x'); /* i0 === 0 @@ -1277,7 +1316,7 @@ i3 === -1 #### get(position) ```js -get(position: number): ListNode\ | undefined +get(position: number): ListNode | undefined ``` Finds and returns the node with specific position in the list: @@ -1287,7 +1326,7 @@ list.addTailMany(['a', 'b', 'c']); // "a" <-> "b" <-> "c" -const found = list.get(1); +var found = list.get(1); /* found.value === "b" @@ -1298,10 +1337,10 @@ found.next.value === "c" -#### indexOf(value, compareFn) +#### indexOf(value [, compareFn]) ```js -indexOf(value: T, compareFn = compare): number +indexOf(value: T, compareFn?: ListComparisonFn): number ``` Finds the position of the first node from the list that has the given value: @@ -1311,10 +1350,10 @@ list.addTailMany(['a', 'b', 'b', 'c']); // "a" <-> "b" <-> "b" <-> "c" -const i0 = list.indexOf('a'); -const i1 = list.indexOf('b'); -const i2 = list.indexOf('c'); -const i3 = list.indexOf('x'); +var i0 = list.indexOf('a'); +var i1 = list.indexOf('b'); +var i2 = list.indexOf('c'); +var i3 = list.indexOf('x'); /* i0 === 0 @@ -1333,11 +1372,11 @@ list.addTailMany([{ x: 1 }, { x: 0 }, { x: 2 }, { x: 0 }, { x: 3 }]); // {"x":1} <-> {"x":0} <-> {"x":2} <-> {"x":0} <-> {"x":3} -const i0 = indexOf(1, (value, searchedValue) => value.x === searchedValue); -const i1 = indexOf(2, (value, searchedValue) => value.x === searchedValue); -const i2 = indexOf(3, (value, searchedValue) => value.x === searchedValue); -const i3 = indexOf(0, (value, searchedValue) => value.x === searchedValue); -const i4 = indexOf(4, (value, searchedValue) => value.x === searchedValue); +var i0 = indexOf(1, (value, searchedValue) => value.x === searchedValue); +var i1 = indexOf(2, (value, searchedValue) => value.x === searchedValue); +var i2 = indexOf(3, (value, searchedValue) => value.x === searchedValue); +var i3 = indexOf(0, (value, searchedValue) => value.x === searchedValue); +var i4 = indexOf(4, (value, searchedValue) => value.x === searchedValue); /* i0 === 0 @@ -1360,13 +1399,13 @@ There are a few ways to iterate over or display a linked list. -#### forEach(callback) +#### forEach(iteratorFn) ```js -forEach(callback: ListIteratorFunction\): void +forEach(iteratorFn: ListIteratorFn): void ``` -Runs a callback function on all nodes in a linked list from head to tail: +Runs a function on all nodes in a linked list from head to tail: ```js list.addTailMany(['a', 'b', 'c']); @@ -1381,7 +1420,6 @@ list.forEach((node, index) => console.log(node.value + index)); ``` - #### \*\[Symbol.iterator\]\(\) A linked list is iterable. In other words, you may use methods like `for...of` on it. @@ -1391,7 +1429,7 @@ list.addTailMany(['a', 'b', 'c']); // "a" <-> "b" <-> "c" -for(const node of list) { +for(const node of list) { /* ES6 for...of statement */ console.log(node.value); } @@ -1405,7 +1443,7 @@ for(const node of list) { #### toArray() ```js -toArray(): T\[\] +toArray(): T[] ``` Converts a linked list to an array of values: @@ -1415,7 +1453,7 @@ list.addTailMany(['a', 'b', 'c']); // "a" <-> "b" <-> "c" -const arr = list.toArray(); +var arr = list.toArray(); /* arr === ['a', 'b', 'c'] @@ -1427,7 +1465,7 @@ arr === ['a', 'b', 'c'] #### toNodeArray() ```js -toNodeArray(): T\[\] +toNodeArray(): ListNode[] ``` Converts a linked list to an array of nodes: @@ -1437,7 +1475,7 @@ list.addTailMany(['a', 'b', 'c']); // "a" <-> "b" <-> "c" -const arr = list.toNodeArray(); +var arr = list.toNodeArray(); /* arr[0].value === 'a' @@ -1448,10 +1486,10 @@ arr[2].value === 'a' -#### toString() +#### toString([mapperFn]) ```js -toString(): string +toString(mapperFn: ListMapperFn = JSON.stringify): string ``` Converts a linked list to a string representation of nodes and their relations: @@ -1461,7 +1499,7 @@ list.addTailMany(['a', 2, 'c', { k: 4, v: 'd' }]); // "a" <-> 2 <-> "c" <-> {"k":4,"v":"d"} -const str = list.toString(); +var str = list.toString(); /* str === '"a" <-> 2 <-> "c" <-> {"k":4,"v":"d"}' @@ -1477,7 +1515,7 @@ list.addMany([{ x: 1 }, { x: 2 }, { x: 3 }, { x: 4 }, { x: 5 }]).tail(); // {"x":1} <-> {"x":2} <-> {"x":3} <-> {"x":4} <-> {"x":5} -const str = list.toString(value => value.x); +var str = list.toString(value => value.x); /* str === '1 <-> 2 <-> 3 <-> 4 <-> 5' @@ -1486,3 +1524,93 @@ str === '1 <-> 2 <-> 3 <-> 4 <-> 5' + + + +## API + +### Classes + +#### LinkedList + +```js +export class LinkedList { + + // properties and methods are explained above + +} +``` + + + +#### ListNode + +```js +export class ListNode { + next: ListNode | undefined; + + previous: ListNode | undefined; + + constructor(public readonly value: T) {} +} +``` + +`ListNode` is the node that is being stored in the `LinkedList` for every record. + +- `value` is the value stored in the node and is passed through the constructor. +- `next` refers to the next node in the list. +- `previous` refers to the previous node in the list. + +```js +list.addTailMany([ 0, 1, 2 ]); + +console.log( + list.head.value, // 0 + list.head.next.value, // 1 + list.head.next.next.value, // 2 + list.head.next.next.previous.value, // 1 + list.head.next.next.previous.previous.value, // 0 + list.tail.value, // 2 + list.tail.previous.value, // 1 + list.tail.previous.previous.value, // 0 + list.tail.previous.previous.next.value, // 1 + list.tail.previous.previous.next.next.value, // 2 +); +``` + + + + +### Types + +#### ListMapperFn + +```js +type ListMapperFn = (value: T) => any; +``` + +This function is used in `toString` method to map the node values before generating a string representation of the list. + + + +#### ListComparisonFn + +```js +type ListComparisonFn = (nodeValue: T, comparedValue: any) => boolean; +``` + +This function is used while adding, dropping, ang finding nodes based on a comparison value. + + + +#### ListIteratorFn + +```js +type ListIteratorFn = ( + node: ListNode, + index?: number, + list?: LinkedList, +) => R; +``` + +This function is used while iterating over the list either to do something with each node or to find a node. diff --git a/docs/en/docs-nav.json b/docs/en/docs-nav.json index 0e13262b18..8b5d41aa59 100644 --- a/docs/en/docs-nav.json +++ b/docs/en/docs-nav.json @@ -5,17 +5,7 @@ "items": [ { "text": "From Startup Templates", - "path": "Getting-Started-With-Startup-Templates.md", - "items": [ - { - "text": "Application with MVC (Razor Pages) UI", - "path": "Getting-Started-AspNetCore-MVC-Template.md" - }, - { - "text": "Application with Angular UI", - "path": "Getting-Started-Angular-Template.md" - } - ] + "path": "Getting-Started.md" }, { "text": "From Empty Projects", @@ -302,7 +292,17 @@ }, { "text": "Tag Helpers", - "path": "UI/AspNetCore/Tag-Helpers/Index.md" + "path": "UI/AspNetCore/Tag-Helpers/Index.md", + "items": [ + { + "text": "Form Elements", + "path": "UI/AspNetCore/Tag-Helpers/Form-elements.md" + }, + { + "text": "Dynamic Forms", + "path": "UI/AspNetCore/Tag-Helpers/Dynamic-Forms.md" + } + ] }, { "text": "Widgets", @@ -371,8 +371,13 @@ "text": "Common", "items": [ { - "text": "Linked List (Doubly)", - "path": "UI/Common/Utils/Linked-List.md" + "text": "Utilities", + "items": [ + { + "text": "Linked List (Doubly)", + "path": "UI/Common/Utils/Linked-List.md" + } + ] } ] } diff --git a/docs/en/images/bookstore-home.png b/docs/en/images/bookstore-home.png new file mode 100644 index 0000000000..5e5b512220 Binary files /dev/null and b/docs/en/images/bookstore-home.png differ diff --git a/docs/en/images/bookstore-login.png b/docs/en/images/bookstore-login.png new file mode 100644 index 0000000000..cd8bfa9bf9 Binary files /dev/null and b/docs/en/images/bookstore-login.png differ diff --git a/docs/en/images/db-migrator-output.png b/docs/en/images/db-migrator-output.png new file mode 100644 index 0000000000..ace6abb226 Binary files /dev/null and b/docs/en/images/db-migrator-output.png differ diff --git a/docs/en/images/package-manager-console-update-database.png b/docs/en/images/package-manager-console-update-database.png new file mode 100644 index 0000000000..d5bb9c2975 Binary files /dev/null and b/docs/en/images/package-manager-console-update-database.png differ diff --git a/docs/en/images/rn-environment-local-ip.png b/docs/en/images/rn-environment-local-ip.png new file mode 100644 index 0000000000..7e60efff2f Binary files /dev/null and b/docs/en/images/rn-environment-local-ip.png differ diff --git a/docs/en/images/rn-expo-interface.png b/docs/en/images/rn-expo-interface.png new file mode 100644 index 0000000000..f1f405ebf4 Binary files /dev/null and b/docs/en/images/rn-expo-interface.png differ diff --git a/docs/en/images/rn-host-local-ip.png b/docs/en/images/rn-host-local-ip.png new file mode 100644 index 0000000000..8691d749e5 Binary files /dev/null and b/docs/en/images/rn-host-local-ip.png differ diff --git a/docs/en/images/rn-login-iphone.png b/docs/en/images/rn-login-iphone.png new file mode 100644 index 0000000000..2da1d24601 Binary files /dev/null and b/docs/en/images/rn-login-iphone.png differ diff --git a/docs/en/images/rn-tiered-local-ip.png b/docs/en/images/rn-tiered-local-ip.png new file mode 100644 index 0000000000..35168455ab Binary files /dev/null and b/docs/en/images/rn-tiered-local-ip.png differ diff --git a/docs/en/images/solution-files-mvc.png b/docs/en/images/solution-files-mvc.png new file mode 100644 index 0000000000..08bbfb9595 Binary files /dev/null and b/docs/en/images/solution-files-mvc.png differ diff --git a/docs/en/images/solution-files-non-mvc.png b/docs/en/images/solution-files-non-mvc.png new file mode 100644 index 0000000000..880cf20d46 Binary files /dev/null and b/docs/en/images/solution-files-non-mvc.png differ diff --git a/docs/en/images/swagger-ui.png b/docs/en/images/swagger-ui.png new file mode 100644 index 0000000000..7f52269474 Binary files /dev/null and b/docs/en/images/swagger-ui.png differ diff --git a/docs/en/images/vs-app-solution-structure-mongodb.png b/docs/en/images/vs-app-solution-structure-mongodb.png new file mode 100644 index 0000000000..8e0e6ba565 Binary files /dev/null and b/docs/en/images/vs-app-solution-structure-mongodb.png differ diff --git a/docs/en/images/vs-app-solution-structure-tiered.png b/docs/en/images/vs-app-solution-structure-tiered.png new file mode 100644 index 0000000000..fd41ef4b0a Binary files /dev/null and b/docs/en/images/vs-app-solution-structure-tiered.png differ diff --git a/docs/en/images/vs-app-solution-structure.png b/docs/en/images/vs-app-solution-structure.png new file mode 100644 index 0000000000..00d92164e7 Binary files /dev/null and b/docs/en/images/vs-app-solution-structure.png differ diff --git a/docs/en/images/vs-spa-app-backend-structure-mongodb.png b/docs/en/images/vs-spa-app-backend-structure-mongodb.png new file mode 100644 index 0000000000..8f0427c14b Binary files /dev/null and b/docs/en/images/vs-spa-app-backend-structure-mongodb.png differ diff --git a/docs/en/images/vs-spa-app-backend-structure.png b/docs/en/images/vs-spa-app-backend-structure.png new file mode 100644 index 0000000000..2cd394c8eb Binary files /dev/null and b/docs/en/images/vs-spa-app-backend-structure.png differ diff --git a/docs/pt-BR/Tutorials/Angular/Part-I.md b/docs/pt-BR/Tutorials/Angular/Part-I.md index 3b79483cd3..3b0b1daf1b 100644 --- a/docs/pt-BR/Tutorials/Angular/Part-I.md +++ b/docs/pt-BR/Tutorials/Angular/Part-I.md @@ -537,11 +537,13 @@ import { GetBooks } from '../actions/books.actions'; import { Books } from '../models/books'; import { BooksService } from '../../books/shared/books.service'; import { tap } from 'rxjs/operators'; +import { Injectable } from '@angular/core'; @State({ name: 'BooksState', defaults: { books: {} } as Books.State, }) +@Injectable() export class BooksState { @Selector() static getBooks(state: Books.State) { diff --git a/docs/zh-Hans/AutoMapper-Integration.md b/docs/zh-Hans/AutoMapper-Integration.md deleted file mode 100644 index d197861f25..0000000000 --- a/docs/zh-Hans/AutoMapper-Integration.md +++ /dev/null @@ -1,3 +0,0 @@ -## AutoMapper Integration - -TODO \ No newline at end of file diff --git a/docs/zh-Hans/Best-Practices/Application-Services.md b/docs/zh-Hans/Best-Practices/Application-Services.md index 6c8d11b32b..6c681edde1 100644 --- a/docs/zh-Hans/Best-Practices/Application-Services.md +++ b/docs/zh-Hans/Best-Practices/Application-Services.md @@ -17,7 +17,7 @@ ##### 基础DTO -**推荐** 为实体定义一个**基础**DTO. +**推荐** 为聚合根定义一个**基础**DTO. - 直接包含实体中所有的**原始属性**. - 例外: 出于**安全**原因,可以**排除**某些属性(像 `User.Password`). @@ -27,7 +27,7 @@ ```c# [Serializable] -public class IssueDto : FullAuditedEntityDto +public class IssueDto : ExtensibleFullAuditedEntityDto { public string Title { get; set; } public string Text { get; set; } @@ -57,7 +57,7 @@ public class IssueLabelDto ````C# [Serializable] -public class IssueWithDetailsDto : FullAuditedEntityDto +public class IssueWithDetailsDto : ExtensibleFullAuditedEntityDto { public string Title { get; set; } public string Text { get; set; } @@ -66,14 +66,14 @@ public class IssueWithDetailsDto : FullAuditedEntityDto } [Serializable] -public class MilestoneDto : EntityDto +public class MilestoneDto : ExtensibleEntityDto { public string Name { get; set; } public bool IsClosed { get; set; } } [Serializable] -public class LabelDto : EntityDto +public class LabelDto : ExtensibleEntityDto { public string Name { get; set; } public string Color { get; set; } @@ -120,6 +120,7 @@ Task> GetListAsync(QuestionListQueryDto queryDto); * **推荐** 使用 `CreateAsync` 做为**方法名**. * **推荐** 使用**专门的输入DTO**来创建实体. +* **推荐** DTO类从 `ExtensibleObject` 类继承(或任何实现 `ExtensibleObject`的类) 以允许在需要时传递额外的属性. * **推荐** 使用 **data annotations** 进行输入验证. * 尽可能在**领域**之间共享常量(通过**domain shared** package定义的常量). * **推荐** 只需要创建实体的**最少**信息, 但是提供了其他可选属性. @@ -134,7 +135,7 @@ Task CreateAsync(CreateQuestionDto questionDto); ````C# [Serializable] -public class CreateQuestionDto +public class CreateQuestionDto : ExtensibleObject { [Required] [StringLength(QuestionConsts.MaxTitleLength, MinimumLength = QuestionConsts.MinTitleLength)] @@ -151,6 +152,7 @@ public class CreateQuestionDto - **推荐** 使用 `UpdateAsync` 做为**方法名**. - **推荐** 使用**专门的输入DTO**来更新实体. +- **推荐** DTO类从 `ExtensibleObject` 类继承(或任何实现 `ExtensibleObject`的类) 以允许在需要时传递额外的属性. - **推荐** 获取实体的id做为分离的原始参数. 不要包含更新DTO. - **推荐** 使用 **data annotations** 进行输入验证. - 尽可能在**领域**之间共享常量(通过**domain shared** package定义的常量). @@ -199,6 +201,10 @@ Task VoteAsync(Guid id, VoteType type); * **不推荐** 在应用程序服务方法中使用linq/sql查询来自数据库的数据. 让仓储负责从数据源执行linq/sql查询. +#### 额外的属性 + +* **推荐** 使用 `MapExtraPropertiesTo` 扩展方法 ([参阅](Object-Extensions.md)) 或配置对象映射 (`MapExtraProperties`) 以允许应用开发人员能够扩展对象和服务. + #### 操作/删除 实体 * **推荐** 总是从数据库中获取所有的相关实体以对他们执行操作. diff --git a/docs/zh-Hans/Best-Practices/Data-Transfer-Objects.md b/docs/zh-Hans/Best-Practices/Data-Transfer-Objects.md index 0c6017e6e7..29e51501ea 100644 --- a/docs/zh-Hans/Best-Practices/Data-Transfer-Objects.md +++ b/docs/zh-Hans/Best-Practices/Data-Transfer-Objects.md @@ -2,6 +2,7 @@ * **推荐** 在 **application.contracts** 层中定义DTO. * **推荐** 在可能和必要的情况下从预构建的 **基础DTO类** 继承 (如 `EntityDto`, `CreationAuditedEntityDto`, `AuditedEntityDto`, `FullAuditedEntityDto` 等). +* **推荐** 从**聚合根**的**扩展DTO**继承(如 `ExtensibleAuditedEntityDto`), 因为聚合根是可扩展的额外的属性使用这种方式映射到DTO. * **推荐** 定义 **public getter 和 setter** 的DTO成员 . * **推荐** 使用 **data annotations** **验证** service输入DTO的属性. * **不推荐** 在DTO中添加任何 **逻辑**, 在必要的时候可以实现 `IValidatableObject` 接口. diff --git a/docs/zh-Hans/Customizing-Application-Modules-Extending-Entities.md b/docs/zh-Hans/Customizing-Application-Modules-Extending-Entities.md index 4cc73989fc..3e5ff3f6cd 100644 --- a/docs/zh-Hans/Customizing-Application-Modules-Extending-Entities.md +++ b/docs/zh-Hans/Customizing-Application-Modules-Extending-Entities.md @@ -50,7 +50,7 @@ ObjectExtensionManager.Instance * 你提供了 `IdentityUser` 作为实体名(泛型参数), `string` 做为新属性的类型, `SocialSecurityNumber` 做为属性名(也是数据库表的字段名). * 你还需要提供一个使用[EF Core Fluent API](https://docs.microsoft.com/en-us/ef/core/modeling/entity-properties)定义数据库映射属性的操作. -> 必须在使用相关的 `DbContext` 之前执行此代码. 应用程序启动模板定义了一个名为 `YourProjectNameEntityExtensions` 的静态类. 你可以在此类中定义扩展确保在正确的时间执行它. 否则你需要自己处理. +> 必须在使用相关的 `DbContext` 之前执行此代码. 应用程序启动模板定义了一个名为 `YourProjectNameEfCoreEntityExtensionMappings` 的静态类. 你可以在此类中定义扩展确保在正确的时间执行它. 否则你需要自己处理. 定义实体扩展后你需要使用EF Core的[Add-Migration](https://docs.microsoft.com/en-us/ef/core/miscellaneous/cli/powershell#add-migration)和[Update-Database](https://docs.microsoft.com/en-us/ef/core/miscellaneous/cli/powershell#update-database)命令来创建code first迁移类并更新数据库. @@ -58,8 +58,6 @@ ObjectExtensionManager.Instance ## 创建新实体映射到同一个数据库表/Collection -尽管额外属性方法**易于使用**并且适用于一些场景,但它具有[实体文档](Entities.md)中描述的一些缺点. - 另一个方法是**创建你自己的实体**映射到**同一个数据库库**(对于MongoDB数据库是collection) [应用程序启动模板](Startup-Templates/Application.md)的 `AppUser` 已经实现了这种方法. [EF Core迁移文档](Entity-Framework-Core-Migrations.md)描述了在这些情况下如何实现和管理**EF Core数据库迁移**. 这种方法同样适用于MongoDB,但你不需要处理数据库迁移问题. diff --git a/docs/zh-Hans/Customizing-Application-Modules-Overriding-Services.md b/docs/zh-Hans/Customizing-Application-Modules-Overriding-Services.md index cb40de9bdb..1ba35adf80 100644 --- a/docs/zh-Hans/Customizing-Application-Modules-Overriding-Services.md +++ b/docs/zh-Hans/Customizing-Application-Modules-Overriding-Services.md @@ -60,6 +60,7 @@ context.Services.Replace( ````csharp [Dependency(ReplaceServices = true)] +[ExposeServices(typeof(IIdentityUserAppService), typeof(IdentityUserAppService))] public class MyIdentityUserAppService : IdentityUserAppService { //... @@ -161,6 +162,105 @@ public class MyIdentityUserManager : IdentityUserManager 控制器,框架服务,视图组件类以及其他类型注册到依赖注入的类都可以像上面的示例那样被重写. +## 扩展数据传输对象 + +你可以如[扩展实体文档](Customizing-Application-Modules-Extending-Entities.md)所述扩展实体. 并使用上面介绍的重写相关服务**使用自定义属性****执行其他业务逻辑**. + +应用程序使用的数据传输对象(**DTO**)同样可扩展. 这样你可以使服务返回其他属性并在UI(或其他客户端)得到其他属性. + +### 示例 + +假设你已经按照[扩展实体文档](Customizing-Application-Modules-Extending-Entities.md)中的说明添加了 `SocialSecurityNumber` 并希望从 `IdentityUserAppService的GetListAsync` 方法获取用户列表时包括此属性. + +你可以使用[对象扩展系统](Object-Extensions.md)将属性添加到 `IdentityUserDto`. 在应用程序启动模板带有的 `YourProjectNameDtoExtensions` 类中编写以下代码: + +````csharp +ObjectExtensionManager.Instance + .AddOrUpdateProperty( + "SocialSecurityNumber" + ); +```` + +这段代码为 `IdentityUserDto` 类添加了 `string` 类型的 `SocialSecurityNumber` 属性. 现在你可以在RREST API客户端调用 `/api/identity/users` HTTP API(内部使用 `IdentityUserAppService`),你会在 `extraProperties` 部分看到 `SocialSecurityNumber` 值. + +````json +{ + "totalCount": 1, + "items": [{ + "tenantId": null, + "userName": "admin", + "name": "admin", + "surname": null, + "email": "admin@abp.io", + "emailConfirmed": false, + "phoneNumber": null, + "phoneNumberConfirmed": false, + "twoFactorEnabled": false, + "lockoutEnabled": true, + "lockoutEnd": null, + "concurrencyStamp": "b4c371a0ab604de28af472fa79c3b70c", + "isDeleted": false, + "deleterId": null, + "deletionTime": null, + "lastModificationTime": "2020-04-09T21:25:47.0740706", + "lastModifierId": null, + "creationTime": "2020-04-09T21:25:46.8308744", + "creatorId": null, + "id": "8edecb8f-1894-a9b1-833b-39f4725db2a3", + "extraProperties": { + "SocialSecurityNumber": "123456789" + } + }] +} +```` + +手动添加了 `123456789` 值到数据库中. + +所有预构建的模块都在DTO中支持额外属性,你可以对其轻松的配置. + +### 定义检查 + +当为实体[定义](Customizing-Application-Modules-Extending-Entities.md)额外的属性时,由于安全性它不会自动出现在所有相关的DTO中. 额外属性可能包含敏感数据并且你可能不想默认公开给客户端. + +因此如果要用于DTO,需要为相应的DTO显式定义相同的属性(如上所述). 如果要允许在用户创建时进行设置还需要为 `IdentityUserCreateDto` 定义. + +如果属性并不是安全敏感,这可能会很枯燥. 对象扩展系统允许你忽略检查定义的属性. 参阅示例: + +````csharp +ObjectExtensionManager.Instance + .AddOrUpdateProperty( + "SocialSecurityNumber", + options => + { + options.MapEfCore(b => b.HasMaxLength(32)); + options.CheckPairDefinitionOnMapping = false; + } + ); +```` + +这是定义实体属性的另一种方法( 有关 `ObjectExtensionManager` 更多信息,请参阅[文档](Object-Extensions.md)). 这次我们设置了 `CheckPairDefinitionOnMapping` 为false,在将实体映射到DTO时会跳过定义检查. + +如果你不喜欢这种方法,但想简单的向多个对象(DTO)添加单个属, `AddOrUpdateProperty` 可以使用类型数组添加额外的属性: + +````csharp +ObjectExtensionManager.Instance + .AddOrUpdateProperty( + new[] + { + typeof(IdentityUserDto), + typeof(IdentityUserCreateDto), + typeof(IdentityUserUpdateDto) + }, + "SocialSecurityNumber" + ); +```` + +### 关于用户界面 + +该系统允许你向实体和DTO添加额外的属性并执行自定义业务代码,但它与用户界面无关. + +参阅 [重写用户界面](Customizing-Application-Modules-Overriding-User-Interface.md) 指南了解关于UI部分. + ## 如何找到服务? -[模块文档](Modules/Index.md) 包含了定义的主要服务列表. 另外 你也可以查看[源码](https://github.com/abpframework/abp/tree/dev/modules)找到所有的服务. \ No newline at end of file +[模块文档](Modules/Index.md) 包含了定义的主要服务列表. 另外 你也可以查看[源码](https://github.com/abpframework/abp/tree/dev/modules)找到所有的服务. diff --git a/docs/zh-Hans/Entities.md b/docs/zh-Hans/Entities.md index 96d75895d2..1a059e477f 100644 --- a/docs/zh-Hans/Entities.md +++ b/docs/zh-Hans/Entities.md @@ -379,10 +379,10 @@ public static class IdentityUserExtensions * 这些属性**不容易[自动映射](Object-To-Object-Mapping.md)到其他对象**. * 它**不会**为EF Core在数据库表中**创建字段**,因此在数据库中针对这个字段创建索引或搜索/排序并不容易. -###　额外属性背后的实体 +### 额外属性背后的实体 `IHasExtraProperties` 不限于与实体一起使用. 你可以为任何类型的类实现这个接口,使用 `GetProperty`,`SetProperty` 和其他相关方法. ## 另请参阅 -* [实体设计最佳实践指南](Best-Practices/Entities.md) \ No newline at end of file +* [实体设计最佳实践指南](Best-Practices/Entities.md) diff --git a/docs/zh-Hans/Exception-Handling.md b/docs/zh-Hans/Exception-Handling.md index 6bbbed56d4..3d8408b26d 100644 --- a/docs/zh-Hans/Exception-Handling.md +++ b/docs/zh-Hans/Exception-Handling.md @@ -295,8 +295,8 @@ services.Configure(options => 框架会自动抛出以下异常类型: -- 当用户没有权限执行操作时,会抛出 `AbpAuthorizationException` 异常. 有关更多信息,请参阅授权文档(TODO:link). -- 如果当前请求的输入无效,则抛出`AbpValidationException 异常`. 有关更多信息,请参阅授权文档(TODO:link). +- 当用户没有权限执行操作时,会抛出 `AbpAuthorizationException` 异常. 有关更多信息,请参阅授权文档[authorization](Authorization.md). +- 如果当前请求的输入无效,则抛出`AbpValidationException 异常`. 有关更多信息,请参阅[验证文档](Validation.md). - 如果请求的实体不存在,则抛出`EntityNotFoundException` 异常. 此异常大多数由 [repositories](Repositories.md) 抛出. 你同样可以在代码中抛出这些类型的异常(虽然很少需要这样做) diff --git a/docs/zh-Hans/Modules/Index.md b/docs/zh-Hans/Modules/Index.md index 9b44967c53..fb07b5b001 100644 --- a/docs/zh-Hans/Modules/Index.md +++ b/docs/zh-Hans/Modules/Index.md @@ -16,6 +16,7 @@ ABP是一个 **模块化的应用程序框架** 由十多个 **nuget packages** * **Background Jobs**: 用于在使用默认后台作业管理器时保存后台作业. * **Blogging**: 用于创建精美的博客. ABP的[博客](https://blog.abp.io/) 就使用了此模块. * [**Docs**](Docs.md): 用于创建技术文档页面. ABP的[文档](https://abp.io/documents/) 就使用了此模块. +* **Feature Management**: 用于保存和管理功能. * **Identity**: 基于Microsoft Identity管理角色,用户和他们的权限. * **Identity Server**: 集成了IdentityServer4. * **Permission Management**: 用于保存权限. @@ -27,4 +28,4 @@ ABP是一个 **模块化的应用程序框架** 由十多个 **nuget packages** ## 商业应用模块 -[ABP商业](https://commercial.abp.io/)许可证在ABP框架上提供了额外的预构建应用程序模块. 参见ABP商业版提供的[模块列表](https://commercial.abp.io/module). \ No newline at end of file +[ABP商业](https://commercial.abp.io/)许可证在ABP框架上提供了额外的预构建应用程序模块. 参见ABP商业版提供的[模块列表](https://commercial.abp.io/module). diff --git a/docs/zh-Hans/Nightly-Builds.md b/docs/zh-Hans/Nightly-Builds.md index 3d34330ca3..84ea243b05 100644 --- a/docs/zh-Hans/Nightly-Builds.md +++ b/docs/zh-Hans/Nightly-Builds.md @@ -23,3 +23,19 @@ 2. 将包源更改为`全部`. 3. 搜索nuget包. 你将看到包的预发布格式为`(VERSION)-preview(DATE)` (如本示例中的**v0.16.0-preview20190401**). 4. 你可以单击`安装`按钮将包添加到项目中. + +## 安装和卸载预览NPM包 + +预览NPM包的最新版本可以通过在应用程序的根文件夹命令运行命令安装: + +```bash +abp switch-to-preview +``` + +如果你正在使用ABP框架预览包,你可以使用此命令切换回稳定版本: + +```bash +abp switch-to-stable +``` + +参阅 [ABP CLI 文档](./CLI.md) 了解更多信息. \ No newline at end of file diff --git a/docs/zh-Hans/Object-Extensions.md b/docs/zh-Hans/Object-Extensions.md new file mode 100644 index 0000000000..27957708f4 --- /dev/null +++ b/docs/zh-Hans/Object-Extensions.md @@ -0,0 +1,267 @@ +# 对象扩展 + +ABP框架提供了 **实体扩展系统** 允许你 **添加额外属性** 到已存在的对象 **无需修改相关类**. 它允许你扩展[应用程序依赖模块](Modules/Index.md)实现的功能,尤其是当你要扩展[模块定义的实体](Customizing-Application-Modules-Extending-Entities.md)和[DTO](Customizing-Application-Modules-Overriding-Services.md)时. + +> 你自己的对象通常不需要对象扩展系统,因为你可以轻松的添加常规属性到你的类中. + +## IHasExtraProperties 接口 + +这是一个使类可扩展的接口. 它定义了 `Dictionary` 属性: + +````csharp +Dictionary ExtraProperties { get; } +```` + +然后你可以使用此字典添加或获取其他属性. + +### 基类 + +默认以下基类实现了 `IHasExtraProperties` 接口: + +* 由 `AggregateRoot` 类实现 (参阅 [entities](Entities.md)). +* 由 `ExtensibleEntityDto`, `ExtensibleAuditedEntityDto`... [DTO](Data-Transfer-Objects.md)基类实现. +* 由 `ExtensibleObject` 实现, 它是一个简单的基类,任何类型的对象都可以继承. + +如果你的类从这些类继承,那么你的类也是可扩展的,如果没有,你也可以随时手动继承. + +### 基本扩展方法 + +虽然可以直接使用类的 `ExtraProperties` 属性,但建议使用以下扩展方法使用额外属性. + +#### SetProperty + +用于设置额外属性值: + +````csharp +user.SetProperty("Title", "My Title"); +user.SetProperty("IsSuperUser", true); +```` + +`SetProperty` 返回相同的对象, 你可以使用链式编程: + +````csharp +user.SetProperty("Title", "My Title") + .SetProperty("IsSuperUser", true); +```` + +#### GetProperty + +用于读取额外属性的值: + +````csharp +var title = user.GetProperty("Title"); + +if (user.GetProperty("IsSuperUser")) +{ + //... +} +```` + +* `GetProperty` 是一个泛型方法,对象类型做为泛型参数. +* 如果未设置给定的属性,则返回默认值 (`int` 的默认值为 `0` , `bool` 的默认值是 `false` ... 等). + +##### 非基本属性类型 + +如果您的属性类型不是原始类型(int,bool,枚举，字符串等),你需要使用 `GetProperty` 的非泛型版本,它会返回 `object`. + +#### HasProperty + +用于检查对象之前是否设置了属性. + +#### RemoveProperty + +用于从对象中删除属性. 使用此方法代替为属性设置 `null` 值. + +### 一些最佳实践 + +为属性名称使用魔术字符串很危险,因为你很容易输入错误的属性名称-这并不安全; + +* 为你的额外属性名称定义一个常量. +* 使用扩展方法轻松设置你的属性. + +示例: + +````csharp +public static class IdentityUserExtensions +{ + private const string TitlePropertyName = "Title"; + + public static void SetTitle(this IdentityUser user, string title) + { + user.SetProperty(TitlePropertyName, title); + } + + public static string GetTitle(this IdentityUser user) + { + return user.GetProperty(TitlePropertyName); + } +} +```` + +然后, 你可以很容易地设置或获取 `Title` 属性: + +````csharp +user.SetTitle("My Title"); +var title = user.GetTitle(); +```` + +## Object Extension Manager + +你可以为可扩展对象(实现 `IHasExtraProperties`接口)设置任意属性, `ObjectExtensionManager` 用于显式定义可扩展类的其他属性. + +显式定义额外的属性有一些用例: + +* 允许控制如何在对象到对象的映射上处理额外的属性 (参阅下面的部分). +* 允许定义属性的元数据. 例如你可以在使用[EF Core](Entity-Framework-Core.md)时将额外的属性映射到数据库中的表字段. + +> `ObjectExtensionManager` 实现单例模式 (`ObjectExtensionManager.Instance`) ,你应该在应用程序启动之前定义对象扩展. [应用程序启动模板](Startup-Templates/Application.md) 有一些预定义的静态类,可以安全在内部定义对象扩展. + +### AddOrUpdate + +`AddOrUpdate` 是定义对象额外属性或更新对象额外属性的主要方法. + +示例: 为 `IdentityUser` 实体定义额外属性: + +````csharp +ObjectExtensionManager.Instance + .AddOrUpdate(options => + { + options.AddOrUpdateProperty("SocialSecurityNumber"); + options.AddOrUpdateProperty("IsSuperUser"); + } + ); +```` + +### AddOrUpdateProperty + +虽然可以如上所示使用 `AddOrUpdateProperty`, 但如果要定义单个额外的属性,也可以使用快捷的扩展方法: + +````csharp +ObjectExtensionManager.Instance + .AddOrUpdateProperty("SocialSecurityNumber"); +```` + +有时将单个额外属性定义为多种类型是可行的. 你可以使用以下代码,而不是一个一个地定义: + +````csharp +ObjectExtensionManager.Instance + .AddOrUpdateProperty( + new[] + { + typeof(IdentityUserDto), + typeof(IdentityUserCreateDto), + typeof(IdentityUserUpdateDto) + }, + "SocialSecurityNumber" + ); +```` + +#### 属性配置 + +`AddOrUpdateProperty` 还可以为属性定义执行其他配置的操作. + +Example: + +````csharp +ObjectExtensionManager.Instance + .AddOrUpdateProperty( + "SocialSecurityNumber", + options => + { + options.CheckPairDefinitionOnMapping = false; + }); +```` + +> 参阅 "对象到对象映射" 部分了解 `CheckPairDefinitionOnMapping` 选项. + +`options` 有一个名为 `Configuration` 的字典,该字典存储对象扩展定义甚至可以扩展. EF Core使用它来将其他属性映射到数据库中的表字段. 请参阅[扩展实体文档](Customizing-Application-Modules-Extending-Entities.md). + +## 对象到对象映射 + +假设你已向可扩展的实体对象添加了额外的属性并使用了自动[对象到对象的映射](Object-To-Object-Mapping.md)将该实体映射到可扩展的DTO类. 在这种情况下你需要格外小心,因为额外属性可能包含**敏感数据**,这些数据对于客户端不可用. + +本节提供了一些**好的做法**,可以控制对象映射的额外属性。 + +### MapExtraPropertiesTo + +`MapExtraPropertiesTo` 是ABP框架提供的扩展方法,用于以受控方式将额外的属性从一个对象复制到另一个对象. 示例: + +````csharp +identityUser.MapExtraPropertiesTo(identityUserDto); +```` + +`MapExtraPropertiesTo` 需要在**两侧**(本例中是`IdentityUser` 和 `IdentityUserDto`)**定义属性**. 以将值复制到目标对象. 否则即使源对象(在此示例中为 `identityUser` )中确实存在该值,它也不会复制. 有一些重载此限制的方法. + +#### MappingPropertyDefinitionChecks + +`MapExtraPropertiesTo` 获取一个附加参数来控制单个映射操作的定义检查: + +````csharp +identityUser.MapExtraPropertiesTo( + identityUserDto, + MappingPropertyDefinitionChecks.None +); +```` + +> 要小心,因为 `MappingPropertyDefinitionChecks.None` 会复制所有的额外属性而不进行任何检查. `MappingPropertyDefinitionChecks` 枚举还有其他成员. + +如果要完全禁用属性的定义检查,可以在定义额外的属性(或更新现有定义)时进行,如下所示: + +````csharp +ObjectExtensionManager.Instance + .AddOrUpdateProperty( + "SocialSecurityNumber", + options => + { + options.CheckPairDefinitionOnMapping = false; + }); +```` + +#### 忽略属性 + +你可能要在映射操作忽略某些属性: + +````csharp +identityUser.MapExtraPropertiesTo( + identityUserDto, + ignoredProperties: new[] {"MySensitiveProp"} +); +```` + +忽略的属性不会复制到目标对象. + +#### AutoMapper集成 + +如果您使用的是[AutoMapper](https://automapper.org/)库,ABP框架还提供了一种扩展方法来利用上面定义的 `MapExtraPropertiesTo` 方法. + +你可以在映射配置文件中使用 `MapExtraProperties()` 方法. + +````csharp +public class MyProfile : Profile +{ + public MyProfile() + { + CreateMap() + .MapExtraProperties(); + } +} +```` + +它与 `MapExtraPropertiesTo()` 方法具有相同的参数。 + +## Entity Framework Core 数据库映射 + +如果你使用的是EF Core,可以将额外的属性映射到数据库中的表字段. 例: + +````csharp +ObjectExtensionManager.Instance + .AddOrUpdateProperty( + "SocialSecurityNumber", + options => + { + options.MapEfCore(b => b.HasMaxLength(32)); + } + ); +```` + +参阅 [Entity Framework Core 集成文档](Entity-Framework-Core.md) 了解更多内容. \ No newline at end of file diff --git a/docs/zh-Hans/Object-To-Object-Mapping.md b/docs/zh-Hans/Object-To-Object-Mapping.md index 67d580ae54..57b744e0bf 100644 --- a/docs/zh-Hans/Object-To-Object-Mapping.md +++ b/docs/zh-Hans/Object-To-Object-Mapping.md @@ -145,6 +145,23 @@ options.AddProfile(validate: true); > 如果你有多个配置文件,并且只需要为其中几个启用验证,那么首先使用`AddMaps`而不进行验证,然后为你想要验证的每个配置文件使用`AddProfile`. +### 映射对象扩展 + +[对象扩展系统](Object-Extensions.md) 允许为已存在的类定义额外属性. ABP 框架提供了一个映射定义扩展可以正确的映射两个对象的额外属性. + +````csharp +public class MyProfile : Profile +{ + public MyProfile() + { + CreateMap() + .MapExtraProperties(); + } +} +```` + +如果两个类都是可扩展对象(实现了 `IHasExtraProperties` 接口),建议使用 `MapExtraProperties` 方法. 更多信息请参阅[对象扩展文档](Object-Extensions.md). + ## 高级主题 ### IObjectMapper 接口 diff --git a/docs/zh-Hans/Startup-Templates/Application.md b/docs/zh-Hans/Startup-Templates/Application.md index 78d43759db..31453ff728 100644 --- a/docs/zh-Hans/Startup-Templates/Application.md +++ b/docs/zh-Hans/Startup-Templates/Application.md @@ -139,7 +139,7 @@ ABP是一个模块化的框架,理想的设计是让每个模块都有自己的 初始化种子数据很重要,ABP具有模块化的种子数据基础设施. 种子数据的更多信息,请参阅[文档](../Data-Seeding.md). -虽然创建数据库和应用迁移似乎只对关系数据库有用,但即使您选择NoSQL数据库提供程序(如MongoDB),也会生成此项目. 这时,它会为应用程序提供必要的初始数据. +虽然创建数据库和应用迁移似乎只对关系数据库有用,但即使你选择NoSQL数据库提供程序(如MongoDB),也会生成此项目. 这时,它会为应用程序提供必要的初始数据. * 它依赖 `.EntityFrameworkCore.DbMigrations` 项目 (针对EF Core),因为它需要访问迁移文件. * 它依赖 `.Application.Contracts` 项目,因为它需要访问权限定义在初始化种子数据时为管理员用户赋予所有权限. @@ -270,6 +270,159 @@ ABP使用开源的[IdentityServer4](https://identityserver.io/)框架做应用 `angular/src/environments` 文件夹下的文件含有应用程序的基础配置. +#### AppModule（应用程序模块） + +`AppModule` 是应用程序的根模块. 一些ABP模块和一些基本模块导入到 `AppModule` 中. + +ABP 配置模块也已经导入到 `AppModule` 中, 以满足可延迟加载 ABP 模块的初始需求. + +#### AppRoutingModule（应用程序路由模块） + +在 `AppRoutingModule` 中有可延迟加载的 ABP 模块作为路由. + +> 不应更改ABP模块的路径. + +你应该在 `data` 对象中添加 `routes` 属性, 以便在菜单中添加一个链接来重定向到自定义页面. + +```js +{ + path: 'dashboard', + loadChildren: () => import('./dashboard/dashboard.module').then(m => m.DashboardModule), + canActivate: [AuthGuard, PermissionGuard], + data: { + routes: { + name: 'ProjectName::Menu:Dashboard', + order: 2, + iconClass: 'fa fa-dashboard', + requiredPolicy: 'ProjectName.Dashboard.Host' + } as ABP.Route + } +} +``` +在上面的例子中; +* 如果用户没有登录, AuthGuard 会阻塞访问并重定向到登录页面. +* PermissionGuard 使用 `rotues` 对象的 `requiredPolicy` 属性检查用户的权限. 如果用户未被授权访问该页, 则显示403页. +* `routes` 的 `name` 属性是菜单链接标签. 可以定义本地化 key. +* `routes` 对象的 `iconClass` 属性是菜单链接图标类. +* `routes` 对象的 `requiredPolicy` 属性是访问页面所需的策略 key. + +在上述 `routes` 定义之后, 如果用户被授权, 仪表盘链接将出现在菜单上. + +#### Shared Module（共享模块） + +所有模块可能需要的模块已导入到 `SharedModule`. 你应该将 `SharedModule` 导入所有模块. + +参见 [Sharing Modules（共享模块）](https://angular.io/guide/sharing-ngmodules) 文档. + +#### Environments（环境） + +`src/environments` 文件夹下的文件包含应用程序的基本配置. + +#### Home Module + +Home模块是一个可延迟加载的模块, 它加载应用程序的根地址. + +#### Styles（样式） + +在 `angular.json` 中向 `styles` 数组添加所需的样式文件. `AppComponent` 在主包加载后通过 `LazyLoadService` 加载一些样式文件, 以缩短第一次绘制的时间. + +#### Testing（测试） + +你应该在与要测试的文件相同的文件夹中创建测试. + +参见[测试文档](https://angular.io/guide/testing/). + +#### Depended Packages（依赖包） + +* [NG Bootstrap](https://ng-bootstrap.github.io/) 被用作UI组件库. +* [NGXS](https://www.ngxs.io/) 被用作状态管理库. +* [angular-oauth2-oidc](https://github.com/manfredsteyer/angular-oauth2-oidc) 用于支持OAuth 2和OpenId Connect (OIDC). +* [Chart.js](https://www.chartjs.org/) 用于创建小部件. +* [ngx-validate](https://github.com/ng-turkey/ngx-validate) 用于对交互表单进行动态验证. + +### React Native + +解决方案将[React Native](https://reactnative.dev/)应用程序作为默认值包含在 `react-native` 文件夹中. + +服务器端类似于上面描述的解决方案. `*.HttpApi.Host` 的项目提供 API, 所以 React 本机应用程序使用它. + +React 本机应用程序是用 [Expo](https://expo.io/)生成的. Expo 是一套基于 React Native 构建的工具, 帮助你快速启动一个应用程序, 尽管它有很多功能. + +React Native 应用文件夹结构, 如下图所示： + +![react-native-folder-structure](../images/react-native-folder-structure.png) + +* `App.js` 是应用程序的引导组件. +* `Environment.js` f文件有应用程序的基本配置. 在这个文件中定义了 `prod` and `dev` 配置. +* [Contexts](https://reactjs.org/docs/context.html) 是在 `src/contexts` 文件夹中创建的. +* [Higher order components](https://reactjs.org/docs/higher-order-components.html) 是在 `src/hocs` 文件夹中创建的. +* [Custom hooks](https://reactjs.org/docs/hooks-custom.html#extracting-a-custom-hook) 是在 `src/hooks` 中创建的. +* [Axios interceptors](https://github.com/axios/axios#interceptors) 是在 `src/interceptors` 文件夹中创建. +* 工具函数从 `src/utils` 文件夹导出. + +#### Components（组件） + +可以在所有屏幕上使用的组件是在 `src/components` 文件夹中创建的. 所有组件都是作为一个能够使用 [hooks](https://reactjs.org/docs/hooks-intro.html) 的函数创建的. + +#### Screens（屏幕） + +![react-native-navigation-structure](../images/react-native-navigation-structure.png) + +Screens 是通过在 `src/screens` 文件夹中创建将名称分开的文件夹来创建的. 某些 screens 的某些部分可以拆分为组件. + +每个 screen 都在 `src/navigators` 文件夹中的导航器中使用. + +#### Navigation（导航） + +[React Navigation](https://reactnavigation.org/) 被用作导航库. 导航器是在 `src/navigators` 中创建的. 一个 [drawer](https://reactnavigation.org/docs/drawer-based-navigation/) 导航器和几个 [stack](https://reactnavigation.org/docs/hello-react-navigation/#installing-the-stack-navigator-library) 导航器在此文件夹中创建. 查看 [上图](#screens) 中的导航结构. + +#### State Management（状态管理） + +[Redux](https://redux.js.org/) 被用作状态管理库. [Redux Toolkit](https://redux-toolkit.js.org/) 库被用作高效Redux开发的工具集. + +在 `src/store` 文件夹中创建 Actions, reducers, sagas, selectors. 存储文件夹如下： + +![react-native-store-folder](../images/react-native-store-folder.png) + +* [**Store**](https://redux.js.org/basics/store) 在 `src/store/index.js` 文件中定义. +* [**Actions**](https://redux.js.org/basics/actions/) 是将数据从应用程序发送到存储的有效信息负载. +* [**Reducers**](https://redux.js.org/basics/reducers) 指定应用程序的状态如何更改以响应发送到存储的操作. +* [**Redux-Saga**](https://redux-saga.js.org/) 是一个库, 旨在使应用程序的副作用(即异步的事情, 如数据获取和不纯的事情, 如访问浏览器缓存)更容易管理. Sagas 是在 `src/store/sagas` 文件夹中创建的. +* [**Reselect**](https://github.com/reduxjs/reselect) 库用于创建缓存的选择器. 选择器是在 `src/store/selectors` 文件夹中创建的. + +#### APIs + +[Axios](https://github.com/axios/axios) 用作HTTP客户端库. Axios 实例从 `src/api/API.js` 导出 . 使用相同的配置进行HTTP调用. `src/api` 文件夹中还有为 API 调用创建的 API 文件. + +#### Theming（主题） + +[Native Base](https://nativebase.io/) 被用作UI组件库. 本地基本组件可以很容易地进行自定义.参见[Native Base customize](https://docs.nativebase.io/Customize.html#Customize) 文档.我们沿着同样的路走. + +* Native Base 主题变量在 `src/theme/variables` 文件夹中. +* Native Base 组件样式在 `src/theme/components` 文件夹中.这些文件是用 Native Base's `ejectTheme` 脚本生成的. +* 组件样式用 `src/theme/overrides` 文件夹下的文件覆盖. + +#### Testing（单元测试） + +将创建单元测试. + +参见[测试概述](https://reactjs.org/docs/testing.html)文档. + +#### Depended Libraries（依赖库） + +* [Native Base](https://nativebase.io/) 用作UI组件库. +* [React Navigation](https://reactnavigation.org/) 用作导航库. +* [Axios](https://github.com/axios/axios) 用作HTTP客户端库. +* [Redux](https://redux.js.org/) 用作状态管理库. +* [Redux Toolkit](https://redux-toolkit.js.org/) 库被用作高效Redux开发的工具集. +* [Redux-Saga](https://redux-saga.js.org/) 用于管理异步进程. +* [Redux Persist](https://github.com/rt2zz/redux-persist) 被用作状态持久化. +* [Reselect](https://github.com/reduxjs/reselect) 用于创建缓存的选择器. +* [i18n-js](https://github.com/fnando/i18n-js) 作为国际化库使用. +* [expo-font](https://docs.expo.io/versions/latest/sdk/font/) 库可以轻松加载字体. +* [Formik](https://github.com/jaredpalmer/formik) 用于构建表单. +* [Yup](https://github.com/jquense/yup) 用于表单验证. + ## 下一步是什么? * 参阅[ASP.NET Core MVC 模板入门](../Getting-Started-AspNetCore-MVC-Template.md)创建此模板的新解决方案并运行它. diff --git a/docs/zh-Hans/UI/Angular/AddingSettingTab.md b/docs/zh-Hans/UI/Angular/AddingSettingTab.md deleted file mode 100644 index c46a559957..0000000000 --- a/docs/zh-Hans/UI/Angular/AddingSettingTab.md +++ /dev/null @@ -1,3 +0,0 @@ -## Creating a Settings Tab - -TODO... diff --git a/docs/zh-Hans/UI/Angular/Component-Replacement.md b/docs/zh-Hans/UI/Angular/Component-Replacement.md index d2369901dc..e98ce4331e 100644 --- a/docs/zh-Hans/UI/Angular/Component-Replacement.md +++ b/docs/zh-Hans/UI/Angular/Component-Replacement.md @@ -1,3 +1,84 @@ -# Component Replacement +## 替换组件 -TODO... \ No newline at end of file +你可以将一些ABP的组件替换为你自己的自定义组件. + +您可以**替换**但**不能自定义**默认ABP组件的原因是禁用或更改该组件的一部分可能会导致问题. 所以我们把这些组件称为可替换组件. + +### 如何替换组件 + +创建一个你想要使用的新组件,添加到 `AppModule` 中的 `declarations` 和`entryComponents` 中. + +然后打开 `app.component.ts` 使用 `AddReplaceableComponent` 将你的组件替换ABP组件. 如下所示: + +```js +import { ..., AddReplaceableComponent } from '@abp/ng.core'; // imported AddReplaceableComponent action +import { eIdentityComponents } from '@abp/ng.identity'; // imported eIdentityComponents enum +import { Store } from '@ngxs/store'; // imported Store +//... +export class AppComponent { + constructor(..., private store: Store) {} // injected Store + + ngOnInit() { + this.store.dispatch( + new AddReplaceableComponent({ + component: YourNewRoleComponent, + key: eIdentityComponents.Roles, + }), + ); + //... + } +} +``` + +![Example Usage](./images/component-replacement.gif) + +### 如何替换布局 + +每个ABP主题模块有3个布局,分别是`ApplicationLayoutComponent`, `AccountLayoutComponent`, `EmptyLayoutComponent`. 这些布局可以用相同的方式替换. + +> 一个布局组件模板应该包含 `` 元素. + +下面的例子解释了如何更换 `ApplicationLayoutComponent`: + +运行以下命令在 `angular` 文件夹中生成布局: + +```bash +yarn ng generate component shared/my-application-layout --export --entryComponent + +# You don't need the --entryComponent option in Angular 9 +``` + +在你的布局模板(`my-layout.component.html`)中添加以下代码: + +```html + +``` + +打开 `app.component.ts` 添加以下内容: + +```js +import { ..., AddReplaceableComponent } from '@abp/ng.core'; // imported AddReplaceableComponent +import { eThemeBasicComponents } from '@abp/ng.theme.basic'; // imported eThemeBasicComponents enum for component keys +import { MyApplicationLayoutComponent } from './shared/my-application-layout/my-application-layout.component'; // imported MyApplicationLayoutComponent +import { Store } from '@ngxs/store'; // imported Store +//... +export class AppComponent { + constructor(..., private store: Store) {} // injected Store + + ngOnInit() { + // added below content + this.store.dispatch( + new AddReplaceableComponent({ + component: MyApplicationLayoutComponent, + key: eThemeBasicComponents.ApplicationLayout, + }), + ); + + //... + } +} +``` + +## 下一步是什么? + +- [自定义设置页面](./Custom-Setting-Page.md) diff --git a/docs/zh-Hans/UI/Angular/Config-State.md b/docs/zh-Hans/UI/Angular/Config-State.md new file mode 100644 index 0000000000..94b522f3fc --- /dev/null +++ b/docs/zh-Hans/UI/Angular/Config-State.md @@ -0,0 +1,294 @@ +## 配置状态 + +`ConfigStateService` 是一个单例服务,即在应用程序的根级别提供,用于与 `Store` 中的应用程序配置状态进行交互. + +## 使用前 + +为了使用 `ConfigStateService`,你必须将其注入到你的类中. + +```js +import { ConfigStateService } from '@abp/ng.core'; + +@Component({ + /* class metadata here */ +}) +class DemoComponent { + constructor(private config: ConfigStateService) {} +} +``` + +你不必在模块或组件/指令级别提供 `ConfigStateService`,因为它已经在**根中**提供. + +## 选择器方法 + +`ConfigStateService` 有许多选择器方法允许你从 `Store` 获取特定或所有的配置. + +### 如何从Store获取所有的配置 + +你可以使用 `ConfigStateService` 的 `getAll` 方法从Store获取所有的配置对象. 用法如下: + +```js +// this.config is instance of ConfigStateService + +const config = this.config.getAll(); +``` + +### 如何从Store获取特定的配置 + +你可以使用 `ConfigStateService` 的 `getOne` 方法从Store获取特定的配置属性. 你需要将属性名做为参数传递给方法: + +```js +// this.config is instance of ConfigStateService + +const currentUser = this.config.getOne("currentUser"); +``` + +有时你想要获取具体信息,而不是当前用户. 例如你只想获取到 `tenantId`: + +```js +const tenantId = this.config.getDeep("currentUser.tenantId"); +``` + +或通过提供键数组作为参数: + +```js +const tenantId = this.config.getDeep(["currentUser", "tenantId"]); +``` + +`getDeep` 可以执行 `getOne` 的所有操作. 但 `getOne` 的执行效率要高一些. + +#### 配置状态属性 + +请参阅 `Config.State` 类型,你可以通过 `getOne` 和 `getDeep` 获取所有属性. 你可以在[config.ts 文件](https://github.com/abpframework/abp/blob/dev/npm/ng-packs/packages/core/src/lib/models/config.ts#L7)中找到. + +### 如何从Store获取应用程序信息 + +`getApplicationInfo` 方法从存储为配置状态存储的环境变量中获取应用程序信息. 你可以这样使用它: + +```js +// this.config is instance of ConfigStateService + +const appInfo = this.config.getApplicationInfo(); +``` + +该方法不会返回 `undefined` 或 `null`,而是会返回一个空对象(`{}`). 换句话说,当你使用上面代码中的 `appInfo` 属性时,永远不会出现错误. + +#### 应用程序信息属性 + +请参阅 `Config.State` 类型,你可以通过 `getApplicationInfo` 获取所有属性. 你可以在[config.ts 文件](https://github.com/abpframework/abp/blob/dev/npm/ng-packs/packages/core/src/lib/models/config.ts#L21)中找到. + +### 如何从Store获取 + +`getApplicationInfo` 方法从存储为配置状态存储的环境变量中获取特定的API URL. 你可以这样使用它: + +```js +// this.config is instance of ConfigStateService + +const apiUrl = this.config.getApiUrl(); +// environment.apis.default.url + +const searchUrl = this.config.getApiUrl("search"); +// environment.apis.search.url +``` + +该方法返回给定键的特定的API `url`. 如果没有Key,则使用 `default`. + +### 如何从Store获取所有的设置 + +你可以使用 `ConfigStateService` 的 `getSettings` 获取配置状态所有的设置对象. 你可以这样使用它: + +```js +// this.config is instance of ConfigStateService + +const settings = this.config.getSettings(); +``` + +实际上该方法可以通过**传递关键字**来搜索设置. + +```js +const localizationSettings = this.config.getSettings("Localization"); +/* +{ + 'Abp.Localization.DefaultLanguage': 'en' +} +*/ +``` + +请注意, **设置搜索区分大小写**. + +### 如何从Store获取特定的设置 + +你可以使用 `ConfigStateService` 的 `getSetting` 获取配置状态特定的设置. 你可以这样使用它: + +```js +// this.config is instance of ConfigStateService + +const defaultLang = this.config.getSetting("Abp.Localization.DefaultLanguage"); +// 'en' +``` + +### 如何从Store获取特定的权限 + +你可以使用 `ConfigStateService` 的 `getGrantedPolicy` 获取配置状态特定的权限. 你应该将策略key做为参数传递给方法: + +```js +// this.config is instance of ConfigStateService + +const hasIdentityPermission = this.config.getGrantedPolicy("Abp.Identity"); +// true +``` + +你还可以使用 **组合策略key** 来微调你的选择: + +```js +// this.config is instance of ConfigStateService + +const hasIdentityAndAccountPermission = this.config.getGrantedPolicy( + "Abp.Identity && Abp.Account" +); +// false + +const hasIdentityOrAccountPermission = this.config.getGrantedPolicy( + "Abp.Identity || Abp.Account" +); +// true +``` + +创建权限选择器时,请考虑以下**规则**: + +- 最多可组合两个键. +- `&&` 操作符查找两个键. +- `||` 操作符查找任意一个键. +- 空字符串 `''` 做为键将返回 `true` +- 使用没有第二个键的操作符将返回 `false` + +### 如何从Store中获取翻译 + +`ConfigStateService` 的 `getLocalization` 用法翻译. 这里有一些示例: + +```js +// this.config is instance of ConfigStateService + +const identity = this.config.getLocalization("AbpIdentity::Identity"); +// 'identity' + +const notFound = this.config.getLocalization("AbpIdentity::IDENTITY"); +// 'AbpIdentity::IDENTITY' + +const defaultValue = this.config.getLocalization({ + key: "AbpIdentity::IDENTITY", + defaultValue: "IDENTITY" +}); +// 'IDENTITY' +``` + +请参阅[本地化文档](./Localization.md)了解详情. + +## 分发方法 + +`ConfigStateService` 有几种分发方法，让你方便地将预定义操作分发到 `Store`. + +### 如何从服务器获取应用程序配置 + +`dispatchGetAppConfiguration` 触发对端点的请求,该端点使用应用程序状态进行响应,然后将此响应作为配置状态放置到 `Store`中. + +```js +// this.config is instance of ConfigStateService + +this.config.dispatchGetAppConfiguration(); +// returns a state stream which emits after dispatch action is complete +``` + +请注意,**你不必在应用程序启动时调用此方法**,因为在启动时已经从服务器收到了应用程序配置. + +### 如何修补路由配置 + +`dispatchPatchRouteByName` 根据名称查找路由, 并将其在 `Store` 中的配置替换为作为第二个参数传递的新配置. + +```js +// this.config is instance of ConfigStateService + +const newRouteConfig: Partial = { + name: "Home", + path: "home", + children: [ + { + name: "Dashboard", + path: "dashboard" + } + ] +}; + +this.config.dispatchPatchRouteByName("::Menu:Home", newRouteConfig); +// returns a state stream which emits after dispatch action is complete +``` + +### 如何添加新路由配置 + +`dispatchAddRoute` 向 `Store` 的配置状态添加一个新路由. 应该将路由配置做为方法参数传递. + +```js +// this.config is instance of ConfigStateService + +const newRoute: ABP.Route = { + name: "My New Page", + iconClass: "fa fa-dashboard", + path: "page", + invisible: false, + order: 2, + requiredPolicy: "MyProjectName::MyNewPage" +}; + +this.config.dispatchAddRoute(newRoute); +// returns a state stream which emits after dispatch action is complete +``` + +`newRoute` 将被放置在根级别,没有任何父路由,并且其url将存储为 `'/path'`. + +如果你想要**添加一个子路由,您可以这样做:** + +```js +// this.config is instance of ConfigStateService + +const newRoute: ABP.Route = { + parentName: "AbpAccount::Login", + name: "My New Page", + iconClass: "fa fa-dashboard", + path: "page", + invisible: false, + order: 2, + requiredPolicy: "MyProjectName::MyNewPage" +}; + +this.config.dispatchAddRoute(newRoute); +// returns a state stream which emits after dispatch action is complete +``` + +`newRoute` 做为 `'AbpAccount::Login'` 父路由的子路由被放置,它的url被设置为 `'/account/login/page'`. + +#### 路由配置属性 + +请参阅 `ABP.Route` 类型,获取可在参数中传递给 `dispatchSetEnvironment` 的所有属性. 你可以在[common.ts 文件](https://github.com/abpframework/abp/blob/dev/npm/ng-packs/packages/core/src/lib/models/common.ts#L27)中找到. + +### 如何设置环境 + +`dispatchSetEnvironment` 将传递给它的环境变量放在 `Store` 中的配置状态下. 使用方法如下: + +```js +// this.config is instance of ConfigStateService + +this.config.dispatchSetEnvironment({ + /* environment properties here */ +}); +// returns a state stream which emits after dispatch action is complete +``` + +注意,**你不必在应用程序启动时调用此方法**,因为环境变量已经在启动时存储了. + +#### 环境属性 + +请参阅 `Config.Environment` 类型,获取可在参数中传递给 `dispatchSetEnvironment` 的所有属性. 你可以在[config.ts 文件](https://github.com/abpframework/abp/blob/dev/npm/ng-packs/packages/core/src/lib/models/config.ts#L13)中找到. + +## 下一步是什么? + +* [组件替换]](./Component-Replacement.md) \ No newline at end of file diff --git a/docs/zh-Hans/UI/Angular/Container-Strategy.md b/docs/zh-Hans/UI/Angular/Container-Strategy.md new file mode 100644 index 0000000000..daf3be01db --- /dev/null +++ b/docs/zh-Hans/UI/Angular/Container-Strategy.md @@ -0,0 +1,87 @@ +# ContainerStrategy + +`ContainerStrategy` 是 @abp/ng.core 包暴露出的抽象类. 有两种扩展容器扩展策略: `ClearContainerStrategy` 和 `InsertIntoContainerStrategy`. 它们实现了相同的方法和属性,这两种策略都可以帮助你定义容器的准备方式和内容的投影位置. + +## API + +`ClearContainerStrategy` 是一个扩展了 `ContainerStrategy` 的类. 它允许你**将内容投影之前清除容器**. + +### 构造函数 + +```js +constructor( + public containerRef: ViewContainerRef, + private index?: number, // works only in InsertIntoContainerStrategy +) +``` + +- `containerRef` 是在投影内容时使用的 `ViewContainerRef`. + +### getIndex + +```js +getIndex(): number +``` + +该方法返回被 `0` 和 `containerRef` `length` 限制的给定索引. 对于没有索引的策略,它返回`0`. + +### prepare + +```js +prepare(): void +``` + +此方法在内容投影之前调用. 基于使用的容器策略,它要么清除容器,要么什么都不做(空操作). + +## ClearContainerStrategy + +`ClearContainerStrategy` 是一个扩展了 `ContainerStrategy` 的类. 它允许你**将内容投影之前清除容器**. + +## InsertIntoContainerStrategy + +`InsertIntoContainerStrategy` 是一个扩展了 `ContainerStrategy` 的类. 它允许你**将内容投影到容器中的特定节点索引上**. + +## 预定义的容器策略 + +可以通过 `CONTAINER_STRATEGY` 常量访问预定义的容器策略. + +### Clear + +```js +CONTAINER_STRATEGY.Clear(containerRef: ViewContainerRef) +``` + +在内容投影之前清除给定的容器. + + +### Append + +```js +CONTAINER_STRATEGY.Append(containerRef: ViewContainerRef) +``` + +将投影内容附加到容器中. + + +### Prepend + +```js +CONTAINER_STRATEGY.Prepend(containerRef: ViewContainerRef) +``` + +将投影的内容预先写入容器中. + +### Insert + +```js +CONTAINER_STRATEGY.Insert( + containerRef: ViewContainerRef, + index: number, +) +``` + +将投影内容按照给定的索引(在`0` 到 `containerRef`的长度之间)插入到容器中. + +## 另请参阅 + +- [ProjectionStrategy](./Projection-Strategy.md) diff --git a/docs/zh-Hans/UI/Angular/Content-Projection-Service.md b/docs/zh-Hans/UI/Angular/Content-Projection-Service.md new file mode 100644 index 0000000000..72fa468a79 --- /dev/null +++ b/docs/zh-Hans/UI/Angular/Content-Projection-Service.md @@ -0,0 +1,77 @@ +# 内容投影 + +你可以使用位于@abp/ng.core包中的 `ContentProjectionService` 简单明确的投影内容. + +## 入门 + +你不必在模块或组件级别提供 `ContentProjectionService`,因为它已经在**根中提供了**. 你可以在组件中注入并开始使用它. 为了获得更好的类型支持,你可以将迭代项目的类型传递给它. + +```js +import { ContentProjectionService } from '@abp/ng.core'; + +@Component({ + /* class metadata here */ +}) +class DemoComponent { + constructor(private contentProjectionService: ContentProjectionService) {} +} +``` + +## 用法 + +你可以使用 `ContentProjectionService` 的 `projectContent` 方法在你的项目中动态的渲染组件和模板. + +### 如何将组件投影到根级别 + +如果将 `RootComponentProjectionStrategy` 做为 `projectContent` 方法的第一个参数,那么 `ContentProjectionService` 会解析投影组件并放在根级别,它还为组件传递上下文. + +```js +const strategy = PROJECTION_STRATEGY.AppendComponentToBody( + SomeOverlayComponent, + { someOverlayProp: "SOME_VALUE" } +); + +const componentRef = this.contentProjectionService.projectContent(strategy); +``` + +在上面的示例中, `SomeOverlayComponent` 组件放置在 `` 的**末尾**并返回 `ComponentRef`. 另外将应用给定的上下文,因此组件的 `someOverlayProp` 被设置为 `SOME_VALUE`. + +> 你应该总是返回 `ComponentRef` 实例,因为它是对投影组件的引用,在你需要时使用该引用销毁投影视图和组件实例. + +### 如何将组件和模板投影到容器中 + +如果将 `ComponentProjectionStrategy` 或 `TemplateProjectionStrategy` 做为 `projectContent` 方法的第一个参数,并且传递 `ViewContainerRef` 做为策略的第二个参数传递. 那么 `ContentProjectionService` 把组件或模板投影到给定的容器中,它还为组件或模板传递上下文. + +```js +const strategy = PROJECTION_STRATEGY.ProjectComponentToContainer( + SomeComponent, + viewContainerRefOfTarget, + { someProp: "SOME_VALUE" } +); + +const componentRef = this.contentProjectionService.projectContent(strategy); +``` + +在上面的示例中,`viewContainerRefOfTarget`(它是一个`ViewContainerRef` 实例)将被清除,并把 `SomeComponent` 组件放在其中. 另外将应用给定的上下文,因此组件的 `someProp` 被设置为 `SOME_VALUE`. + +> 你应该总是返回 `ComponentRef` 或 `EmbeddedViewRef` ,因为它是对投影内容的引用,在你需要时使用该引用销毁它们. + +请参考[ProjectionStrategy](./Projection-Strategy.md)查看所有可用的投影策略以及如何构建自己的投影策略. + +## API + +### projectContent + +```js +projectContent | TemplateRef>( + projectionStrategy: ProjectionStrategy, + injector = this.injector, +): ComponentRef | EmbeddedViewRef +``` + +- `projectionStrategy` 参数是此处的要点,在上面进行了说明. +- `injector` 参数是 `Injector` 实例,你可以传递到投影内容. 在 `TemplateProjectionStrategy` 并没有使用到它. + +## 下一步是什么? + +- [TrackByService](./Track-By-Service.md) \ No newline at end of file diff --git a/docs/zh-Hans/UI/Angular/Content-Security-Strategy.md b/docs/zh-Hans/UI/Angular/Content-Security-Strategy.md new file mode 100644 index 0000000000..7e419f8ab7 --- /dev/null +++ b/docs/zh-Hans/UI/Angular/Content-Security-Strategy.md @@ -0,0 +1,55 @@ +# ContentSecurityStrategy + +`ContentSecurityStrategy` 是@abp/ng.core包暴露出的抽象类. 它可以根据[内容安全策略](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy)帮助你将内联脚本或样式标记为安全. + +## API + +### 构造函数 + +```js +constructor(public nonce?: string) +``` + +- `nonce` 启用将内联脚本或样式列入白名单,避免在[script-src](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/script-src#Unsafe_inline_script)和[style-src](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/style-src#Unsafe_inline_styles)指令中使用 `unsafe-inline`. + +### applyCSP + +```js +applyCSP(element: HTMLScriptElement | HTMLStyleElement): void +``` + +该方法将上述属性映射到给定`element`. + +## LooseContentSecurityPolicy + +`LooseContentSecurityPolicy` 是扩展了 `ContentSecurityStrategy` 的类. 它需要 `nonce` 和带有给定 `