diff --git a/docs/en/Getting-Started.md b/docs/en/Getting-Started.md index 952abc9b70..5f3d79d94a 100644 --- a/docs/en/Getting-Started.md +++ b/docs/en/Getting-Started.md @@ -322,7 +322,6 @@ Once all node modules are loaded, execute `yarn start` (or `npm start`) command: 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/) diff --git a/docs/en/Samples/Index.md b/docs/en/Samples/Index.md index a674d3a880..e3fc0263ad 100644 --- a/docs/en/Samples/Index.md +++ b/docs/en/Samples/Index.md @@ -7,7 +7,7 @@ Here, a list of official samples built with the ABP Framework. Most of these sam A complete solution to demonstrate how to build systems based on the microservice architecture. * [The complete documentation for this sample](Microservice-Demo.md) -* [Source code](https://github.com/abpframework/abp/tree/dev/samples/MicroserviceDemo) +* [Source code](https://github.com/abpframework/abp-samples/tree/master/MicroserviceDemo) * [Microservice architecture document](../Microservice-Architecture.md) ### Book Store diff --git a/docs/en/Samples/Microservice-Demo.md b/docs/en/Samples/Microservice-Demo.md index 25eaf68055..30059a9379 100644 --- a/docs/en/Samples/Microservice-Demo.md +++ b/docs/en/Samples/Microservice-Demo.md @@ -28,7 +28,7 @@ The diagram below shows the system: ### Source Code -You can get the source code from [the GitHub repository](https://github.com/abpframework/abp/tree/master/samples/MicroserviceDemo). +You can get the source code from [the GitHub repository](https://github.com/abpframework/abp-samples/tree/master/MicroserviceDemo). ## Running the Solution diff --git a/docs/en/Tutorials/Part-1.md b/docs/en/Tutorials/Part-1.md index 0493796aa3..2f21b99e4b 100644 --- a/docs/en/Tutorials/Part-1.md +++ b/docs/en/Tutorials/Part-1.md @@ -1,127 +1,70 @@ -## ASP.NET Core {{UI_Value}} Tutorial - Part 1 +# Web Application Development Tutorial - Part 1: Creating the Server Side ````json //[doc-params] { - "UI": ["MVC","NG"] + "UI": ["MVC","NG"], + "DB": ["EF","Mongo"] } ```` {{ if UI == "MVC" - DB="ef" - DB_Text="Entity Framework Core" UI_Text="mvc" else if UI == "NG" - DB="mongodb" - DB_Text="MongoDB" UI_Text="angular" else - DB ="?" UI_Text="?" end +if DB == "EF" + DB_Text="Entity Framework Core" +else if DB == "Mongo" + DB_Text="MongoDB" +else + DB_Text="?" +end }} -### About this tutorial: - -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: - -- **Part-1: Creating the project and book list page (this tutorial)** -- [Part-2: Creating, updating and deleting books](part-2.md) -- [Part-3: Integration tests](part-3.md) - -*You can also check out [the video course](https://amazingsolutions.teachable.com/p/lets-build-the-bookstore-application) prepared by the community, based on this tutorial.* - -### 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. - -#### Create the project - -By running the below command, it creates a new ABP project with the database provider `{{DB_Text}}` and UI option `{{UI_Value}}`. 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}} --mobile none -``` -![Creating project](./images/bookstore-create-project-{{UI_Text}}.png) - -### Apply migrations - -After creating the project, you need to apply the initial migrations and create the database. To apply migrations, right click on the `Acme.BookStore.DbMigrator` and click **Debug** > **Start New Instance**. This will run the application and apply all migrations. You will see the below result when it successfully completes the process. The application database is ready! - -![Migrations applied](./images/bookstore-migrations-applied-{{UI_Text}}.png) - -> Alternatively, you can run `Update-Database` command in the Visual Studio > Package Manager Console to apply migrations. - -#### Initial database tables - -![Initial database tables](./images/bookstore-database-tables-{{DB}}.png) - -### Run the application - -To run the project, right click to the {{if UI == "MVC"}} `Acme.BookStore.Web`{{end}} {{if UI == "NG"}} `Acme.BookStore.HttpApi.Host` {{end}} project and click **Set As StartUp Project**. And run the web project by pressing **CTRL+F5** (*without debugging and fast*) or press **F5** (*with debugging and slow*). {{if UI == "NG"}}You will see the Swagger UI for BookStore API.{{end}} - -Further information, see the [running the application section](../Getting-Started?UI={{UI}}#run-the-application). - -![Set as startup project](./images/bookstore-start-project-{{UI_Text}}.png) - -{{if UI == "NG"}} - -To start Angular project, go to the `angular` folder, open a command line terminal, execute the `yarn` command: - -```bash -yarn -``` - -Once all node modules are loaded, execute the `yarn start` command: +## About This Tutorial -```bash -yarn start -``` - -The website will be accessible from the following default URL: +In this tutorial series, you will build an ABP based web application named `Acme.BookStore`. This application is used to manage a list of books and their authors. It is developed using the following technologies: -http://localhost:4200/ +* **{{DB_Text}}** as the ORM provider. +* **{{UI_Value}}** as the UI Framework. -If you see the website's landing page successfully, you can exit Angular hosting by pressing `ctrl-c`. (We'll later start it again.) +This tutorial is organized as the following parts; -> Be aware that, Firefox does not use the Windows Certificate Store, so you'll need to add the self-signed developer certificate to Firefox manually. To do this, open Firefox and navigate to the below URL: -> -> https://localhost:44322/api/abp/application-configuration -> -> If you see the below screen, click the **Accept the Risk and Continue** button to bypass this warning. -> -> ![Set as startup project](./images/mozilla-self-signed-cert-error.png) - -{{end}} +- **Part 1: Creating the server side (this part)** +- [Part 2: The book list page](Part-2.md) +- [Part 3: Creating, updating and deleting books](Part-3.md) +- [Part 4: Integration tests](Part-4.md) +- [Part 5: Authorization](Part-5.md) -The default login credentials are; +### Download the Source Code -* **Username**: admin -* **Password**: 1q2w3E* +This tutorials has multiple versions based on your **UI** and **Database** preferences. We've prepared two combinations of the source code to be downloaded: -### Solution structure +* [MVC (Razor Pages) UI with EF Core](https://github.com/abpframework/abp-samples/tree/master/BookStore-Mvc-EfCore) +* [Angular UI with MongoDB](https://github.com/abpframework/abp-samples/tree/master/BookStore-Angular-MongoDb) -This is how the layered solution structure looks like: +## Creating the Solution -![bookstore-visual-studio-solution](./images/bookstore-solution-structure-{{UI_Text}}.png) +Before starting to the development, create a new solution named `Acme.BookStore` and run it by following the [getting started tutorial](../Getting-Started.md). -Check out the [solution structure](../startup-templates/application#solution-structure) section to understand the structure in details. +## Create the Book Entity -### Create the book entity +**Domain layer** in the startup template is separated into two projects: -Domain layer in the startup template is separated into two projects: - -- `Acme.BookStore.Domain` contains your [entities](https://docs.abp.io/en/abp/latest/Entities), [domain services](https://docs.abp.io/en/abp/latest/Domain-Services) and other core domain objects. +- `Acme.BookStore.Domain` contains your [entities](../Entities.md), [domain services](../Domain-Services.md) and other core domain objects. - `Acme.BookStore.Domain.Shared` contains `constants`, `enums` or other domain related objects those can be shared with clients. -Define [entities](https://docs.abp.io/en/abp/latest/Entities) in the **domain layer** (`Acme.BookStore.Domain` project) of the solution. The main entity of the application is the `Book`. Create a class, named `Book`, in the `Acme.BookStore.Domain` project as shown below: +So, define your entities in the domain layer (`Acme.BookStore.Domain` project) of the solution. + +The main entity of the application is the `Book`. Create a `Books` folder (namespace) in the `Acme.BookStore.Domain` project and add a `Book` class inside it: ````csharp using System; using Volo.Abp.Domain.Entities.Auditing; -namespace Acme.BookStore +namespace Acme.BookStore.Books { public class Book : AuditedAggregateRoot { @@ -132,34 +75,22 @@ namespace Acme.BookStore public DateTime PublishDate { get; set; } public float Price { get; set; } - - protected Book() - { - - } - - public Book(Guid id, string name, BookType type, DateTime publishDate, float price) : - base(id) - { - Name = name; - Type = type; - PublishDate = publishDate; - Price = price; - } } } ```` -* ABP has 2 fundamental base classes for entities: `AggregateRoot` and `Entity`. **Aggregate Root** is one of the **Domain Driven Design (DDD)** concepts. See [entity document](https://docs.abp.io/en/abp/latest/Entities) for details and best practices. -* `Book` entity inherits `AuditedAggregateRoot` which adds some auditing properties (`CreationTime`, `CreatorId`, `LastModificationTime`... etc.) on top of the `AggregateRoot` class. +* ABP Framework has two fundamental base classes for entities: `AggregateRoot` and `Entity`. **Aggregate Root** is a [Domain Driven Design](../Domain-Driven-Design.md) concept which can be thought as a root entity that is directly queried and worked on (see the [entities document](../Entities.md) for more). +* `Book` entity inherits from the `AuditedAggregateRoot` which adds some base [auditing](../Audit-Logging.md) properties (like `CreationTime`, `CreatorId`, `LastModificationTime`...) on top of the `AggregateRoot` class. ABP automatically manages these properties for you. * `Guid` is the **primary key type** of the `Book` entity. -#### BookType enum +> This tutorials leaves the entity properties with **public get/set** for the sake of simplicity. See the [entities document](../Entities.md) if you learn more about DDD best practices. -Create the `BookType` enum in the `Acme.BookStore.Domain.Shared` project: +### BookType Enum + +The `Book` entity uses the `BookType` enum. Create the `BookType` in the `Acme.BookStore.Domain.Shared` project: ````csharp -namespace Acme.BookStore +namespace Acme.BookStore.Books { public enum BookType { @@ -176,70 +107,112 @@ namespace Acme.BookStore } ```` -#### Add book entity to the DbContext +The final folder/file structure should be as shown below: -{{if DB == "ef"}} +![bookstore-book-and-booktype](images/bookstore-book-and-booktype.png) + +### Add Book Entity to the DbContext + +{{if DB == "EF"}} EF Core requires to relate entities with your `DbContext`. The easiest way to do this is to add a `DbSet` property to the `BookStoreDbContext` class in the `Acme.BookStore.EntityFrameworkCore` project, as shown below: ````csharp - public class BookStoreDbContext : AbpDbContext - { - public DbSet Users { get; set; } - public DbSet Books { get; set; } //<--added this line--> - //... - } +public class BookStoreDbContext : AbpDbContext +{ + public DbSet Books { get; set; } + //... +} ```` {{end}} -{{if DB == "mongodb"}} +{{if DB == "Mongo"}} Add a `IMongoCollection Books` property to the `BookStoreMongoDbContext` inside the `Acme.BookStore.MongoDB` project: ```csharp public class BookStoreMongoDbContext : AbpMongoDbContext { - public IMongoCollection Users => Collection(); - public IMongoCollection Books => Collection();//<--added this line--> - //... + public IMongoCollection Books => Collection(); + //... } ``` {{end}} -{{if DB == "ef"}} +{{if DB == "EF"}} -#### Configure the book entity +### Map the Book Entity to a Database Table -Open `BookStoreDbContextModelCreatingExtensions.cs` file in the `Acme.BookStore.EntityFrameworkCore` project and add following code to the end of the `ConfigureBookStore` method to configure the Book entity: +Open `BookStoreDbContextModelCreatingExtensions.cs` file in the `Acme.BookStore.EntityFrameworkCore` project and add the mapping code for the `Book` entity. The final class should be the following: ````csharp -builder.Entity(b => +using Acme.BookStore.Books; +using Microsoft.EntityFrameworkCore; +using Volo.Abp; +using Volo.Abp.EntityFrameworkCore.Modeling; + +namespace Acme.BookStore.EntityFrameworkCore { - b.ToTable(BookStoreConsts.DbTablePrefix + "Books", BookStoreConsts.DbSchema); - b.ConfigureByConvention(); //auto configure for the base class props - b.Property(x => x.Name).IsRequired().HasMaxLength(128); -}); + public static class BookStoreDbContextModelCreatingExtensions + { + public static void ConfigureBookStore(this ModelBuilder builder) + { + Check.NotNull(builder, nameof(builder)); + + /* Configure your own tables/entities inside here */ + + builder.Entity(b => + { + b.ToTable(BookStoreConsts.DbTablePrefix + "Books", + BookStoreConsts.DbSchema); + b.ConfigureByConvention(); //auto configure for the base class props + b.Property(x => x.Name).IsRequired().HasMaxLength(128); + }); + } + } +} ```` -Add the `using Volo.Abp.EntityFrameworkCore.Modeling;` statement to resolve `ConfigureByConvention` extension method. +* `BookStoreConsts` has constant values for schema and table prefixes for your tables. You don't have to use it, but suggested to control the table prefixes in a single point. +* `ConfigureByConvention()` method gracefully configures/maps the inherited properties. Always use it for all your entities. + +### Add Database Migration + +The startup template uses [EF Core Code First Migrations](https://docs.microsoft.com/en-us/ef/core/managing-schemas/migrations/) to create and maintain the database schema. Open the **Package Manager Console (PMC)** under the menu *Tools > NuGet Package Manager*. + +![Open Package Manager Console](images/bookstore-open-package-manager-console.png) + +Select the `Acme.BookStore.EntityFrameworkCore.DbMigrations` as the **default project** and execute the following command: + +```bash +Add-Migration "Created_Book_Entity" +``` + +![bookstore-pmc-add-book-migration](./images/bookstore-pmc-add-book-migration-v2.png) + +This will create a new migration class inside the `Migrations` folder of the `Acme.BookStore.EntityFrameworkCore.DbMigrations` project. + +Before updating the database, read the section below to learn how to seed some initial data to the database. + +> If you are using another IDE than the Visual Studio, you can use `dotnet-ef` tool as [documented here](https://docs.microsoft.com/en-us/ef/core/managing-schemas/migrations/?tabs=dotnet-core-cli#create-a-migration). {{end}} -{{if DB == "mongodb"}} +### Add Sample Seed Data -#### Add seed (sample) data +> It's good to have some initial data in the database before running the application. This section introduces the [Data Seeding](../Data-Seeding.md) system of the ABP framework. You can skip this section if you don't want to create seed data, but it is suggested to follow it to learn this useful ABP Framework feature. -Adding sample data is optional, but it's good to have initial data in the database for the first run. ABP provides a [data seed system](https://docs.abp.io/en/abp/latest/Data-Seeding). Create a class deriving from the `IDataSeedContributor` in the `*.Domain` project: +Create a class deriving from the `IDataSeedContributor` in the `*.Domain` project and copy the following code: ```csharp using System; using System.Threading.Tasks; +using Acme.BookStore.Books; using Volo.Abp.Data; using Volo.Abp.DependencyInjection; using Volo.Abp.Domain.Repositories; -using Volo.Abp.Guids; namespace Acme.BookStore { @@ -247,14 +220,10 @@ namespace Acme.BookStore : IDataSeedContributor, ITransientDependency { private readonly IRepository _bookRepository; - private readonly IGuidGenerator _guidGenerator; - public BookStoreDataSeederContributor( - IRepository bookRepository, - IGuidGenerator guidGenerator) + public BookStoreDataSeederContributor(IRepository bookRepository) { _bookRepository = bookRepository; - _guidGenerator = guidGenerator; } public async Task SeedAsync(DataSeedContext context) @@ -265,90 +234,69 @@ namespace Acme.BookStore } await _bookRepository.InsertAsync( - new Book( - id: _guidGenerator.Create(), - name: "1984", - type: BookType.Dystopia, - publishDate: new DateTime(1949, 6, 8), - price: 19.84f - ) + new Book + { + Name = "1984", + Type = BookType.Dystopia, + PublishDate = new DateTime(1949, 6, 8), + Price = 19.84f + }, + autoSave: true ); await _bookRepository.InsertAsync( - new Book( - id: _guidGenerator.Create(), - name: "The Hitchhiker's Guide to the Galaxy", - type: BookType.ScienceFiction, - publishDate: new DateTime(1995, 9, 27), - price: 42.0f - ) + new Book + { + Name = "The Hitchhiker's Guide to the Galaxy", + Type = BookType.ScienceFiction, + PublishDate = new DateTime(1995, 9, 27), + Price = 42.0f + }, + autoSave: true ); } } } ``` -{{end}} +* This code simply uses the `IRepository` (the default [repository](../Repositories.md)) to insert two books to the database, if there is no book currently in the database. -{{if DB == "ef"}} +### Update the Database -#### Add new migration & update the database +Run the `Acme.BookStore.DbMigrator` application to update the database: -The startup template uses [EF Core Code First Migrations](https://docs.microsoft.com/en-us/ef/core/managing-schemas/migrations/) to create and maintain the database schema. Open the **Package Manager Console (PMC)** under the menu *Tools > NuGet Package Manager*. +![bookstore-dbmigrator-on-solution](images/bookstore-dbmigrator-on-solution.png) -![Open Package Manager Console](./images/bookstore-open-package-manager-console.png) +{{if DB == "EF"}} -Select the `Acme.BookStore.EntityFrameworkCore.DbMigrations` as the **default project** and execute the following command: +`.DbMigrator` is a console application that can be run to **migrate the database schema** and **seed the data** on **development** and **production** environments. -```bash -Add-Migration "Created_Book_Entity" -``` - -![bookstore-pmc-add-book-migration](./images/bookstore-pmc-add-book-migration-v2.png) - -This will create a new migration class inside the `Migrations` folder of the `Acme.BookStore.EntityFrameworkCore.DbMigrations` project. Then execute the `Update-Database` command to update the database schema: - -````bash -Update-Database -```` - -![bookstore-update-database-after-book-entity](./images/bookstore-update-database-after-book-entity.png) - -#### Add initial (sample) data - -`Update-Database` command has created the `AppBooks` table in the database. Open your database and enter a few sample rows, so you can show them on the listing page. - -```mssql -INSERT INTO AppBooks (Id,CreationTime,[Name],[Type],PublishDate,Price) VALUES -('f3c04764-6bfd-49e2-859e-3f9bfda6183e', '2018-07-01', '1984',3,'1949-06-08','19.84') - -INSERT INTO AppBooks (Id,CreationTime,[Name],[Type],PublishDate,Price) VALUES -('13024066-35c9-473c-997b-83cd8d3e29dc', '2018-07-01', 'The Hitchhiker`s Guide to the Galaxy',7,'1995-09-27','42') +{{end}} -INSERT INTO AppBooks (Id,CreationTime,[Name],[Type],PublishDate,Price) VALUES -('4fa024a1-95ac-49c6-a709-6af9e4d54b54', '2018-07-02', 'Pet Sematary',5,'1983-11-14','23.7') -``` +{{if DB == "Mongo"}} -![bookstore-books-table](./images/bookstore-books-table.png) +While MongoDB **doesn't require** a database schema migration, it is still good to run this application since it **seeds the initial data** on the database. This application can be used on **development** and **production** environments. {{end}} -### Create the application service +## Create the Application Service -The next step is to create an [application service](../Application-Services.md) to manage the books which will allow us the four basic functions: creating, reading, updating and deleting. Application layer is separated into two projects: +The application layer is separated into two projects: -* `Acme.BookStore.Application.Contracts` mainly contains your `DTO`s and application service interfaces. +* `Acme.BookStore.Application.Contracts` contains your [DTO](../Data-Transfer-Objects.md)s and [application service](../Application-Services.md) interfaces. * `Acme.BookStore.Application` contains the implementations of your application services. -#### BookDto +In this section, you will create an application service to get, create, update and delete books using the `CrudAppService` base class of the ABP Framework. + +### BookDto -Create a DTO class named `BookDto` into the `Acme.BookStore.Application.Contracts` project: +`CrudAppService` base class requires to define the fundamental DTOs for the entity. Create a DTO class named `BookDto` into the `Acme.BookStore.Application.Contracts` project: ````csharp using System; using Volo.Abp.Application.Dtos; -namespace Acme.BookStore +namespace Acme.BookStore.Books { public class BookDto : AuditedEntityDto { @@ -365,11 +313,12 @@ namespace Acme.BookStore * **DTO** classes are used to **transfer data** between the *presentation layer* and the *application layer*. See the [Data Transfer Objects document](https://docs.abp.io/en/abp/latest/Data-Transfer-Objects) for more details. * `BookDto` is used to transfer book data to the presentation layer in order to show the book information on the UI. -* `BookDto` is derived from the `AuditedEntityDto` which has audit properties just like the `Book` class defined above. +* `BookDto` is derived from the `AuditedEntityDto` which has audit properties just like the `Book` entity defined above. -It will be needed to map `Book` entities to `BookDto` objects while returning books to the presentation layer. [AutoMapper](https://automapper.org) library can automate this conversion when you define the proper mapping. The startup template comes with AutoMapper configured, so you can just define the mapping in the `BookStoreApplicationAutoMapperProfile` class in the `Acme.BookStore.Application` project: +It will be needed to map `Book` entities to `BookDto` objects while returning books to the presentation layer. [AutoMapper](https://automapper.org) library can automate this conversion when you define the proper mapping. The startup template comes with AutoMapper pre-configured. So, you can just define the mapping in the `BookStoreApplicationAutoMapperProfile` class in the `Acme.BookStore.Application` project: ````csharp +using Acme.BookStore.Books; using AutoMapper; namespace Acme.BookStore @@ -384,15 +333,17 @@ namespace Acme.BookStore } ```` -#### CreateUpdateBookDto +> See the [object to object mapping](../Object-To-Object-Mapping.md) document for details. + +### CreateUpdateBookDto -Create a DTO class named `CreateUpdateBookDto` into the `Acme.BookStore.Application.Contracts` project: +Create another DTO class named `CreateUpdateBookDto` into the `Acme.BookStore.Application.Contracts` project: ````csharp using System; using System.ComponentModel.DataAnnotations; -namespace Acme.BookStore +namespace Acme.BookStore.Books { public class CreateUpdateBookDto { @@ -404,7 +355,8 @@ namespace Acme.BookStore public BookType Type { get; set; } = BookType.Undefined; [Required] - public DateTime PublishDate { get; set; } + [DataType(DataType.Date)] + public DateTime PublishDate { get; set; } = DateTime.Now; [Required] public float Price { get; set; } @@ -415,9 +367,10 @@ namespace Acme.BookStore * This `DTO` class is used to get book information from the user interface while creating or updating a book. * It defines data annotation attributes (like `[Required]`) to define validations for the properties. `DTO`s are [automatically validated](https://docs.abp.io/en/abp/latest/Validation) by the ABP framework. -Next, add a mapping in `BookStoreApplicationAutoMapperProfile` from the `CreateUpdateBookDto` object to the `Book` entity with the `CreateMap();` command: +Just like done for the `BookDto` above, we should define the mapping from the `CreateUpdateBookDto` object to the `Book` entity. The final class will be like shown below: ````csharp +using Acme.BookStore.Books; using AutoMapper; namespace Acme.BookStore @@ -427,30 +380,29 @@ namespace Acme.BookStore public BookStoreApplicationAutoMapperProfile() { CreateMap(); - CreateMap(); //<--added this line--> + CreateMap(); } } } ```` -#### IBookAppService +### IBookAppService -Create an interface named `IBookAppService` in the `Acme.BookStore.Application.Contracts` project: +Next step is to define an interface for the application service. Create an interface named `IBookAppService` in the `Acme.BookStore.Application.Contracts` project: ````csharp using System; using Volo.Abp.Application.Dtos; using Volo.Abp.Application.Services; -namespace Acme.BookStore +namespace Acme.BookStore.Books { public interface IBookAppService : ICrudAppService< //Defines CRUD methods BookDto, //Used to show books Guid, //Primary key of the book entity - PagedAndSortedResultRequestDto, //Used for paging/sorting on getting a list of books - CreateUpdateBookDto, //Used to create a new book - CreateUpdateBookDto> //Used to update a book + PagedAndSortedResultRequestDto, //Used for paging/sorting + CreateUpdateBookDto> //Used to create/update a book { } @@ -458,12 +410,12 @@ namespace Acme.BookStore ```` * Defining interfaces for the application services **are not required** by the framework. However, it's suggested as a best practice. -* `ICrudAppService` defines common **CRUD** methods: `GetAsync`, `GetListAsync`, `CreateAsync`, `UpdateAsync` and `DeleteAsync`. It's not required to extend it. Instead, you could inherit from the empty `IApplicationService` interface and define your own methods manually. -* There are some variations of the `ICrudAppService` where you can use separated DTOs for each method. +* `ICrudAppService` defines common **CRUD** methods: `GetAsync`, `GetListAsync`, `CreateAsync`, `UpdateAsync` and `DeleteAsync`. It's not required to extend it. Instead, you could inherit from the empty `IApplicationService` interface and define your own methods manually (which will be done for the authors in the next parts). +* There are some variations of the `ICrudAppService` where you can use separated DTOs for each method (like using different DTOs for create and update). -#### BookAppService +### BookAppService -Implement the `IBookAppService` as named `BookAppService` in the `Acme.BookStore.Application` project: +Implement the `IBookAppService`, as named `BookAppService`, in the `Acme.BookStore.Application` project: ````csharp using System; @@ -471,12 +423,16 @@ using Volo.Abp.Application.Dtos; using Volo.Abp.Application.Services; using Volo.Abp.Domain.Repositories; -namespace Acme.BookStore +namespace Acme.BookStore.Books { public class BookAppService : - CrudAppService, - IBookAppService + CrudAppService< + Book, //The Book entity + BookDto, //Used to show books + Guid, //Primary key of the book entity + PagedAndSortedResultRequestDto, //Used for paging/sorting + CreateUpdateBookDto>, //Used to create/update a book + IBookAppService //implement the IBookAppService { public BookAppService(IRepository repository) : base(repository) @@ -487,13 +443,15 @@ namespace Acme.BookStore } ```` -* `BookAppService` is derived from `CrudAppService<...>` which implements all the CRUD (create, read, update, delete) methods defined above. +* `BookAppService` is derived from `CrudAppService<...>` which implements all the CRUD (create, read, update, delete) methods defined by the `ICrudAppService`. * `BookAppService` injects `IRepository` which is the default repository for the `Book` entity. ABP automatically creates default repositories for each aggregate root (or entity). See the [repository document](https://docs.abp.io/en/abp/latest/Repositories). -* `BookAppService` uses `IObjectMapper` to map `Book` objects to `BookDto` objects and `CreateUpdateBookDto` objects to `Book` objects. The Startup template uses the [AutoMapper](http://automapper.org/) library as the object mapping provider. We have defined the mappings before, so it will work as expected. +* `BookAppService` uses `IObjectMapper` service ([see](../Object-To-Object-Mapping.md)) to map `Book` objects to `BookDto` objects and `CreateUpdateBookDto` objects to `Book` objects. The Startup template uses the [AutoMapper](http://automapper.org/) library as the object mapping provider. We have defined the mappings before, so it will work as expected. -### Auto API Controllers +## Auto API Controllers -We normally create **Controllers** to expose application services as **HTTP API** endpoints. This allows browsers or 3rd-party clients to call them via AJAX. ABP can [**automagically**](https://docs.abp.io/en/abp/latest/API/Auto-API-Controllers) configures your application services as MVC API Controllers by convention. +In a typical ASP.NET Core application, you create **API Controllers** to expose application services as **HTTP API** endpoints. This allows browsers or 3rd-party clients to call them over HTTP. + +ABP can [**automagically**](../API/Auto-API-Controllers.md) configures your application services as MVC API Controllers by convention. #### Swagger UI @@ -503,502 +461,42 @@ You will see some built-in service endpoints as well as the `Book` service and i ![bookstore-swagger](./images/bookstore-swagger.png) -Swagger has a nice interface to test the APIs. You can try to execute the `[GET] /api/app/book` API to get a list of books. - -{{if UI == "MVC"}} - -### Dynamic JavaScript proxies - -It's common to call HTTP API endpoints via AJAX from the **JavaScript** side. You can use `$.ajax` or another tool to call the endpoints. However, ABP offers a better way. - -ABP **dynamically** creates JavaScript **proxies** for all API endpoints. So, you can use any **endpoint** just like calling a **JavaScript function**. - -#### Testing in developer console of the browser - -You can easily test the JavaScript proxies using your favorite browser's **Developer Console**. Run the application, open your browser's **developer tools** (*shortcut is F12 for Chrome*), switch to the **Console** tab, type the following code and press enter: - -````js -acme.bookStore.book.getList({}).done(function (result) { console.log(result); }); -```` - -* `acme.bookStore` is the namespace of the `BookAppService` converted to [camelCase](https://en.wikipedia.org/wiki/Camel_case). -* `book` is the conventional name for the `BookAppService` (removed `AppService` postfix and converted to camelCase). -* `getList` is the conventional name for the `GetListAsync` method defined in the `AsyncCrudAppService` base class (removed `Async` postfix and converted to camelCase). -* `{}` argument is used to send an empty object to the `GetListAsync` method which normally expects an object of type `PagedAndSortedResultRequestDto` that is used to send paging and sorting options to the server (all properties are optional, so you can send an empty object). -* `getList` function returns a `promise`. You can pass a callback to the `done` (or `then`) function to get the result from the server. - -Running this code produces the following output: - -![bookstore-test-js-proxy-getlist](./images/bookstore-test-js-proxy-getlist.png) - -You can see the **book list** returned from the server. You can also check the **network** tab of the developer tools to see the client to server communication: - -![bookstore-test-js-proxy-getlist-network](./images/bookstore-test-js-proxy-getlist-network.png) - -Let's **create a new book** using the `create` function: - -````js -acme.bookStore.book.create({ name: 'Foundation', type: 7, publishDate: '1951-05-24', price: 21.5 }).done(function (result) { console.log('successfully created the book with id: ' + result.id); }); -```` - -You should see a message in the console something like that: - -````text -successfully created the book with id: 439b0ea8-923e-8e1e-5d97-39f2c7ac4246 -```` - -Check the `Books` table in the database to see the new book row. You can try `get`, `update` and `delete` functions yourself. - -### Create the books page - -It's time to create something visible and usable! Instead of classic MVC, we will use the new [Razor Pages UI](https://docs.microsoft.com/en-us/aspnet/core/tutorials/razor-pages/razor-pages-start) approach which is recommended by Microsoft. - -Create `Books` folder under the `Pages` folder of the `Acme.BookStore.Web` project. Add a new Razor Page by right clicking the Books folder then selecting **Add > Razor Page** menu item. Name it as `Index`: +Swagger has a nice interface to test the APIs. -![bookstore-add-index-page](./images/bookstore-add-index-page-v2.png) +If you try to execute the `[GET] /api/app/book` API to get a list of books, the server returns such a JSON result: -Open the `Index.cshtml` and change the whole content as shown below: - -**Index.cshtml:** - -````html -@page -@using Acme.BookStore.Web.Pages.Books -@model IndexModel - -

Books

-```` - - -* Set the `IndexModel`'s namespace to `Acme.BookStore.Pages.Books` in `Index.cshtml.cs`. - - - -**Index.cshtml.cs:** - -```csharp -using Microsoft.AspNetCore.Mvc.RazorPages; - -namespace Acme.BookStore.Web.Pages.Books +````json { - public class IndexModel : PageModel + "totalCount": 2, + "items": [ { - public void OnGet() - { - - } - } -} -``` - -#### Add books page to the main menu - -Open the `BookStoreMenuContributor` class in the `Menus` folder and add the following code to the end of the `ConfigureMainMenuAsync` method: - -````csharp -//... -namespace Acme.BookStore.Web.Menus -{ - public class BookStoreMenuContributor : IMenuContributor + "name": "The Hitchhiker's Guide to the Galaxy", + "type": 7, + "publishDate": "1995-09-27T00:00:00", + "price": 42, + "lastModificationTime": null, + "lastModifierId": null, + "creationTime": "2020-07-03T21:04:18.4607218", + "creatorId": null, + "id": "86100bb6-cbc1-25be-6643-39f62806969c" + }, { - private async Task ConfigureMainMenuAsync(MenuConfigurationContext context) - { - //<-- added the below code - context.Menu.AddItem( - new ApplicationMenuItem("BooksStore", l["Menu:BookStore"], icon: "fa fa-book") - .AddItem( - new ApplicationMenuItem("BooksStore.Books", l["Menu:Books"], url: "/Books") - ) - ); - //--> - } + "name": "1984", + "type": 3, + "publishDate": "1949-06-08T00:00:00", + "price": 19.84, + "lastModificationTime": null, + "lastModifierId": null, + "creationTime": "2020-07-03T21:04:18.3174016", + "creatorId": null, + "id": "41055277-cce8-37d7-bb37-39f62806960b" } + ] } ```` -{{end}} - -#### Localize the menu items - -Localization texts are located under the `Localization/BookStore` folder of the `Acme.BookStore.Domain.Shared` project: - -![bookstore-localization-files](./images/bookstore-localization-files-v2.png) - -Open the `en.json` (*English translations*) file and add the below localization texts to the end of the file: - -````json -{ - "Culture": "en", - "Texts": { - "Menu:Home": "Home", - "Welcome": "Welcome", - "LongWelcomeMessage": "Welcome to the application. This is a startup project based on the ABP framework. For more information, visit abp.io.", - - "Menu:BookStore": "Book Store", - "Menu:Books": "Books", - "Actions": "Actions", - "Edit": "Edit", - "PublishDate": "Publish date", - "NewBook": "New book", - "Name": "Name", - "Type": "Type", - "Price": "Price", - "CreationTime": "Creation time", - "AreYouSureToDelete": "Are you sure you want to delete this item?", - "Enum:BookType:0": "Undefined", - "Enum:BookType:1": "Adventure", - "Enum:BookType:2": "Biography", - "Enum:BookType:3": "Dystopia", - "Enum:BookType:4": "Fantastic", - "Enum:BookType:5": "Horror", - "Enum:BookType:6": "Science", - "Enum:BookType:7": "ScienceFiction", - "Enum:BookType:8": "Poetry" - } -} -```` - -* ABP's localization system is built on [ASP.NET Core's standard localization](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/localization) system and extends it in many ways. See the [localization document](https://docs.abp.io/en/abp/latest/Localization) for details. -* Localization key names are arbitrary. You can set any name. As a best practice, we prefer to add `Menu:` prefix for menu items to distinguish from other texts. If a text is not defined in the localization file, it **fallbacks** to the localization key (as ASP.NET Core's standard behavior). - -{{if UI == "MVC"}} - -Run the project, login to the application with the username `admin` and password `1q2w3E*` and see the new menu item has been added to the menu. - -![bookstore-menu-items](./images/bookstore-new-menu-item.png) - -When you click to the Books menu item under the Book Store parent, you are being redirected to the new Books page. - -#### Book list - -We will use the [Datatables.net](https://datatables.net/) jQuery plugin to show the book list. [Datatables](https://datatables.net/) can completely work via AJAX, it is fast, popular and provides a good user experience. [Datatables](https://datatables.net/) plugin is configured in the startup template, so you can directly use it in any page without including any style or script file to your page. - -##### Index.cshtml - -Change the `Pages/Books/Index.cshtml` as following: - -````html -@page -@model Acme.BookStore.Web.Pages.Books.IndexModel -@section scripts -{ - -} - - -

@L["Books"]

- - - - - - @L["Name"] - @L["Type"] - @L["PublishDate"] - @L["Price"] - @L["CreationTime"] - - - - - -```` - -* `abp-script` [tag helper](https://docs.microsoft.com/en-us/aspnet/core/mvc/views/tag-helpers/intro) is used to add external **scripts** to the page. It has many additional features compared to standard `script` tag. It handles **minification** and **versioning**. See the [bundling & minification document](https://docs.abp.io/en/abp/latest/UI/AspNetCore/Bundling-Minification) for details. -* `abp-card` and `abp-table` are **tag helpers** for Twitter Bootstrap's [card component](http://getbootstrap.com/docs/4.1/components/card/). There are other useful tag helpers in ABP to easily use most of the [bootstrap](https://getbootstrap.com/) components. You can also use regular HTML tags instead of these tag helpers, but using tag helpers reduces HTML code and prevents errors by help the of IntelliSense and compile time type checking. Further information, see the [tag helpers](https://docs.abp.io/en/abp/latest/UI/AspNetCore/Tag-Helpers/Index) document. -* You can **localize** the column names in the localization file as you did for the menu items above. - -##### Add a Script File - -Create `index.js` JavaScript file under the `Pages/Books/` folder: - -![bookstore-index-js-file](./images/bookstore-index-js-file-v2.png) - -`index.js` content is shown below: - -````js -$(function () { - var l = abp.localization.getResource('BookStore'); - var dataTable = $('#BooksTable').DataTable(abp.libs.datatables.normalizeConfiguration({ - ajax: abp.libs.datatables.createAjax(acme.bookStore.book.getList), - columnDefs: [ - { data: "name" }, - { data: "type", - render: function(data){ - return l('Enum:BookType:' + data); - } - }, - { data: "publishDate" }, - { data: "price" }, - { data: "creationTime" } - ] - })); -}); -```` - -* `abp.libs.datatables.createAjax` is a helper function to adapt ABP's dynamic JavaScript API proxies to [Datatable](https://datatables.net/)'s format. -* `abp.libs.datatables.normalizeConfiguration` is another helper function. There's no requirement to use it, but it simplifies the [Datatables](https://datatables.net/) configuration by providing conventional values for missing options. -* `acme.bookStore.book.getList` is the function to get list of books (as described in [dynamic JavaScript proxies](#dynamic-javascript-proxies)). -* See [Datatables documentation](https://datatables.net/manual/) for all configuration options. - -It's end of this part. The final UI of this work is shown as below: - -![Book list](./images/bookstore-book-list-2.png) - -{{end}} - -{{if UI == "NG"}} - -### Angular development -#### Create the books page - -It's time to create something visible and usable! There are some tools that we will use when developing ABP Angular frontend application: - -- [Angular CLI](https://angular.io/cli) will be used to create modules, components and services. -- [Ng Bootstrap](https://ng-bootstrap.github.io/#/home) will be used as the UI component library. -- [ngx-datatable](https://swimlane.gitbook.io/ngx-datatable/) will be used as the datatable library. -- [Visual Studio Code](https://code.visualstudio.com/) will be used as the code editor (you can use your favorite editor). - -#### Install NPM packages - -Open a new command line interface (terminal window) and go to your `angular` folder and then run `yarn` command to install NPM packages: - -```bash -yarn -``` - -#### BookModule - -Run the following command line to create a new module, named `BookModule`: - -```bash -yarn ng generate module book --routing true -``` - -![Generating books module](./images/bookstore-creating-book-module-terminal.png) - -#### Routing - -Open the `app-routing.module.ts` file in `src\app` folder and add a route as shown below: - -```js -const routes: Routes = [ -// ... -// added a new route to the routes array - { - path: 'books', - loadChildren: () => import('./book/book.module').then(m => m.BookModule) - } -] -``` - -* We added a lazy-loaded route. See the [Lazy-Loading Feature Modules](https://angular.io/guide/lazy-loading-ngmodules#lazy-loading-feature-modules). - -Open the `route.provider.ts` file in `src\app` folder and replace the content as below: - -```js -import { RoutesService, eLayoutType } from '@abp/ng.core'; -import { APP_INITIALIZER } from '@angular/core'; - -export const APP_ROUTE_PROVIDER = [ - { provide: APP_INITIALIZER, useFactory: configureRoutes, deps: [RoutesService], multi: true }, -]; - -function configureRoutes(routes: RoutesService) { - return () => { - routes.add([ - //... - // added below element - { - path: '/books', - name: '::Menu:Books', - iconClass: 'fas fa-book', - order: 101, - layout: eLayoutType.application, - }, - ]); - }; -} -``` - -* We added a new route element to show a navigation element labeled "Books" on the menu. - * `path` is the URL of the route. - * `name` is the menu item name. A Localization key can be passed. - * `iconClass` is the icon of the menu item. - * `order` is the order of the menu item. We define 101 to show the route after the "Administration" item. - * `layout` is the layout of the BooksModule's routes. `eLayoutType.application`, `eLayoutType.account` or `eLayoutType.empty` can be defined. - -For more information, see the [RoutesService document](https://docs.abp.io/en/abp/latest/UI/Angular/Modifying-the-Menu.md#via-routesservice). - -#### Book list component - -Run the command below on the terminal in the root folder to generate a new component, named book-list: - -```bash -yarn ng generate component book/book-list -``` - -![Creating books list](./images/bookstore-creating-book-list-terminal.png) - -Open `book.module.ts` file in the `app\book` folder and replace the content as below: - -```js -import { NgModule } from '@angular/core'; -import { CommonModule } from '@angular/common'; -import { BookRoutingModule } from './book-routing.module'; -import { BookListComponent } from './book-list/book-list.component'; -import { SharedModule } from '../shared/shared.module'; //<== added this line ==> - -@NgModule({ - declarations: [BookListComponent], - imports: [ - CommonModule, - BookRoutingModule, - SharedModule, //<== added this line ==> - ], -}) -export class BookModule {} -``` - -* We imported `SharedModule` and added to `imports` array. - -Open `book-routing.module.ts` file in the `app\book` folder and replace the content as below: - -```js -import { NgModule } from '@angular/core'; -import { Routes, RouterModule } from '@angular/router'; -import { BookListComponent } from './book-list/book-list.component'; // <== added this line ==> - -// <== replaced routes ==> -const routes: Routes = [ - { - path: '', - component: BookListComponent, - }, -]; - -@NgModule({ - imports: [RouterModule.forChild(routes)], - exports: [RouterModule] -}) -export class BookRoutingModule { } -``` - -* We imported `BookListComponent` and replaced `routes` const. - -Run `yarn start` and wait for Angular to serve the application: - -```bash -yarn start -``` - -Open the browser and navigate to http://localhost:4200/books. We'll see **book-list works!** text on the books page: - -![Initial book list page](./images/bookstore-initial-book-list-page.png) - -#### Generate proxies - -ABP CLI provides `generate-proxy` command that generates client proxies for your HTTP APIs to make easy to consume your services from the client side. Before running generate-proxy command, your host must be up and running. See the [CLI documentation](../CLI.md) - -Run the following command in the `angular` folder: - -```bash -abp generate-proxy --module app -``` - -![Generate proxy command](./images/generate-proxy-command.png) - -The generated files looks like below: - -![Generated files](./images/generated-proxies.png) - -#### BookListComponent - -Open the `book-list.component.ts` file in `app\book\book-list` folder and replace the content as below: - -```js -import { ListService, PagedResultDto } from '@abp/ng.core'; -import { Component, OnInit } from '@angular/core'; -import { BookDto, BookType } from '../models'; -import { BookService } from '../services'; - -@Component({ - selector: 'app-book-list', - templateUrl: './book-list.component.html', - styleUrls: ['./book-list.component.scss'], - providers: [ListService], -}) -export class BookListComponent implements OnInit { - book = { items: [], totalCount: 0 } as PagedResultDto; - - booksType = BookType; - - constructor(public readonly list: ListService, private bookService: BookService) {} - - ngOnInit() { - const bookStreamCreator = (query) => this.bookService.getListByInput(query); - - this.list.hookToQuery(bookStreamCreator).subscribe((response) => { - this.book = response; - }); - } -} -``` - -* We imported and injected the generated `BookService`. -* We implemented the [ListService](https://docs.abp.io/en/abp/latest/UI/Angular/List-Service) that is a utility service to provide easy pagination, sorting, and search implementation. - -Open the `book-list.component.html` file in `app\book\book-list` folder and replace the content as below: - -```html -
-
-
-
-
- {%{{{ '::Menu:Books' | abpLocalization }}}%} -
-
-
-
-
-
- - - - - {%{{{ booksType[row.type] }}}%} - - - - - {%{{{ row.publishDate | date }}}%} - - - - - {%{{{ row.price | currency }}}%} - - - -
-
-``` - -* We added HTML code of book list page. - -Now you can see the final result on your browser: - -![Book list final result](./images/bookstore-book-list.png) - -The file system structure of the project: - -![Book list final result](./images/bookstore-angular-file-tree.png) - -In this tutorial we have applied the rules of official [Angular Style Guide](https://angular.io/guide/styleguide#file-tree). - -{{end}} +That's pretty cool since we haven't written a single line of code to create the API controller, but now we have a fully working REST API! -### Next Part +## The Next Part -See the [part 2](./Part-2.md) for creating, updating and deleting books. +See the [next part](Part-2.md) of this tutorial. diff --git a/docs/en/Tutorials/Part-2.md b/docs/en/Tutorials/Part-2.md index 0a48866956..0029eb466d 100644 --- a/docs/en/Tutorials/Part-2.md +++ b/docs/en/Tutorials/Part-2.md @@ -1,925 +1,491 @@ -## ASP.NET Core {{UI_Value}} Tutorial - Part 2 +# Web Application Development Tutorial - Part 2: The Book List Page ````json //[doc-params] { - "UI": ["MVC","NG"] + "UI": ["MVC","NG"], + "DB": ["EF","Mongo"] } ```` - {{ if UI == "MVC" - DB="ef" - DB_Text="Entity Framework Core" UI_Text="mvc" else if UI == "NG" - DB="mongodb" - DB_Text="MongoDB" UI_Text="angular" else - DB ="?" UI_Text="?" end +if DB == "EF" + DB_Text="Entity Framework Core" +else if DB == "Mongo" + DB_Text="MongoDB" +else + DB_Text="?" +end }} -### About this tutorial +## About This Tutorial -This is the second part of the ASP.NET Core {{UI_Value}} tutorial series. All parts: +In this tutorial series, you will build an ABP based web application named `Acme.BookStore`. This application is used to manage a list of books and their authors. It is developed using the following technologies: -* [Part I: Creating the project and book list page](part-1.md) -* **Part II: Creating, updating and deleting books (this tutorial)** -* [Part III: Integration tests](part-3.md) +* **{{DB_Text}}** as the ORM provider. +* **{{UI_Value}}** as the UI Framework. -*You can also watch [this video course](https://amazingsolutions.teachable.com/p/lets-build-the-bookstore-application) prepared by an ABP community member, based on this tutorial.* +This tutorial is organized as the following parts; -{{if UI == "MVC"}} +- [Part 1: Creating the server side](Part-1.md) +- **Part 2: The book list page (this part)** +- [Part 3: Creating, updating and deleting books](Part-3.md) +- [Part 4: Integration tests](Part-4.md) +- [Part 5: Authorization](Part-5.md) -### Creating a new book +### Download the Source Code -In this section, you will learn how to create a new modal dialog form to create a new book. The modal dialog will look like in the below image: +This tutorials has multiple versions based on your **UI** and **Database** preferences. We've prepared two combinations of the source code to be downloaded: -![bookstore-create-dialog](./images/bookstore-create-dialog-2.png) +* [MVC (Razor Pages) UI with EF Core](https://github.com/abpframework/abp-samples/tree/master/BookStore-Mvc-EfCore) +* [Angular UI with MongoDB](https://github.com/abpframework/abp-samples/tree/master/BookStore-Angular-MongoDb) -#### Create the modal form +{{if UI == "MVC"}} -Create a new razor page, named `CreateModal.cshtml` under the `Pages/Books` folder of the `Acme.BookStore.Web` project. +## Dynamic JavaScript Proxies -![bookstore-add-create-dialog](./images/bookstore-add-create-dialog-v2.png) +It's common to call the HTTP API endpoints via AJAX from the **JavaScript** side. You can use `$.ajax` or another tool to call the endpoints. However, ABP offers a better way. -##### CreateModal.cshtml.cs +ABP **dynamically** creates **[JavaScript Proxies](../UI/AspNetCore/)** for all API endpoints. So, you can use any **endpoint** just like calling a **JavaScript function**. -Open the `CreateModal.cshtml.cs` file (`CreateModalModel` class) and replace with the following code: +### Testing in the Developer Console -````C# -using System.Threading.Tasks; -using Microsoft.AspNetCore.Mvc; +You can easily test the JavaScript proxies using your favorite browser's **Developer Console**. Run the application, open your browser's **developer tools** (*shortcut is generally F12*), switch to the **Console** tab, type the following code and press enter: -namespace Acme.BookStore.Web.Pages.Books -{ - public class CreateModalModel : BookStorePageModel - { - [BindProperty] - public CreateUpdateBookDto Book { get; set; } +````js +acme.bookStore.books.book.getList({}).done(function (result) { console.log(result); }); +```` - private readonly IBookAppService _bookAppService; +* `acme.bookStore.books` is the namespace of the `BookAppService` converted to [camelCase](https://en.wikipedia.org/wiki/Camel_case). +* `book` is the conventional name for the `BookAppService` (removed `AppService` postfix and converted to camelCase). +* `getList` is the conventional name for the `GetListAsync` method defined in the `CrudAppService` base class (removed `Async` postfix and converted to camelCase). +* `{}` argument is used to send an empty object to the `GetListAsync` method which normally expects an object of type `PagedAndSortedResultRequestDto` that is used to send paging and sorting options to the server (all properties are optional with default values, so you can send an empty object). +* `getList` function returns a `promise`. You can pass a callback to the `then` (or `done`) function to get the result returned from the server. - public CreateModalModel(IBookAppService bookAppService) - { - _bookAppService = bookAppService; - } +Running this code produces the following output: - public async Task OnPostAsync() - { - await _bookAppService.CreateAsync(Book); - return NoContent(); - } - } -} -```` +![bookstore-javascript-proxy-console](images/bookstore-javascript-proxy-console.png) -* This class is derived from the `BookStorePageModel` instead of standard `PageModel`. `BookStorePageModel` inherits the `PageModel` and adds some common properties & methods that can be used in your page model classes. -* `[BindProperty]` attribute on the `Book` property binds post request data to this property. -* This class simply injects the `IBookAppService` in the constructor and calls the `CreateAsync` method in the `OnPostAsync` handler. +You can see the **book list** returned from the server. You can also check the **network** tab of the developer tools to see the client to server communication: -##### CreateModal.cshtml +![bookstore-getlist-result-network](images/bookstore-getlist-result-network.png) -Open the `CreateModal.cshtml` file and paste the code below: +Let's **create a new book** using the `create` function: -````html -@page -@using Volo.Abp.AspNetCore.Mvc.UI.Bootstrap.TagHelpers.Modal -@model Acme.BookStore.Web.Pages.Books.CreateModalModel -@{ - Layout = null; -} - - - - - - - - - +````js +acme.bookStore.books.book.create({ + name: 'Foundation', + type: 7, + publishDate: '1951-05-24', + price: 21.5 + }).then(function (result) { + console.log('successfully created the book with id: ' + result.id); + }); ```` -* This modal uses `abp-dynamic-form` tag helper to automatically create the form from the model `CreateBookViewModel`. - * `abp-model` attribute indicates the model object where it's the `Book` property in this case. - * `data-ajaxForm` attribute sets the form to submit via AJAX, instead of a classic page post. - * `abp-form-content` tag helper is a placeholder to render the form controls (it is optional and needed only if you have added some other content in the `abp-dynamic-form` tag, just like in this page). +You should see a message in the console something like that: -#### Add the "New book" button - -Open the `Pages/Books/Index.cshtml` and set the content of `abp-card-header` tag as below: - -````html - - - -

@L["Books"]

- - - - - - +````text +successfully created the book with id: 439b0ea8-923e-8e1e-5d97-39f2c7ac4246 ```` -This adds a new button called **New book** to the **top-right** of the table: +Check the `Books` table in the database to see the new book row. You can try `get`, `update` and `delete` functions yourself. -![bookstore-new-book-button](./images/bookstore-new-book-button.png) +We will use these dynamic proxy functions in the next sections to communicate to the server. -Open the `pages/books/index.js` and add the following code just after the `Datatable` configuration: +{{end}} -````js -var createModal = new abp.ModalManager(abp.appPath + 'Books/CreateModal'); +## Localization -createModal.onResult(function () { - dataTable.ajax.reload(); -}); +Before starting to the UI development, we first want to prepare the localization texts (you normally do when needed while developing your application). -$('#NewBookButton').click(function (e) { - e.preventDefault(); - createModal.open(); -}); -```` +Localization texts are located under the `Localization/BookStore` folder of the `Acme.BookStore.Domain.Shared` project: -* `abp.ModalManager` is a helper class to manage modals in the client side. It internally uses Twitter Bootstrap's standard modal, but abstracts many details by providing a simple API. +![bookstore-localization-files](./images/bookstore-localization-files-v2.png) -Now, you can **run the application** and add new books using the new modal form. +Open the `en.json` (*the English translations*) file and change the content as below: -### Updating a book +````json +{ + "Culture": "en", + "Texts": { + "Menu:Home": "Home", + "Welcome": "Welcome", + "LongWelcomeMessage": "Welcome to the application. This is a startup project based on the ABP framework. For more information, visit abp.io.", + "Menu:BookStore": "Book Store", + "Menu:Books": "Books", + "Actions": "Actions", + "Edit": "Edit", + "PublishDate": "Publish date", + "NewBook": "New book", + "Name": "Name", + "Type": "Type", + "Price": "Price", + "CreationTime": "Creation time", + "AreYouSureToDelete": "Are you sure you want to delete this item?", + "Enum:BookType:0": "Undefined", + "Enum:BookType:1": "Adventure", + "Enum:BookType:2": "Biography", + "Enum:BookType:3": "Dystopia", + "Enum:BookType:4": "Fantastic", + "Enum:BookType:5": "Horror", + "Enum:BookType:6": "Science", + "Enum:BookType:7": "Science fiction", + "Enum:BookType:8": "Poetry" + } +} +```` -Create a new razor page, named `EditModal.cshtml` under the `Pages/Books` folder of the `Acme.BookStore.Web` project: +* Localization key names are arbitrary. You can set any name. We prefer some conventions for specific text types; + * Add `Menu:` prefix for menu items. + * Use `Enum::` naming convention to localize the enum members. When you do it like that, ABP can automatically localize the enums in some proper cases. -![bookstore-add-edit-dialog](./images/bookstore-add-edit-dialog.png) +If a text is not defined in the localization file, it **fallbacks** to the localization key (as ASP.NET Core's standard behavior). -#### EditModal.cshtml.cs +> ABP's localization system is built on [ASP.NET Core's standard localization](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/localization) system and extends it in many ways. See the [localization document](../Localization.md) for details. -Open the `EditModal.cshtml.cs` file (`EditModalModel` class) and replace with the following code: +{{if UI == "MVC"}} -````csharp -using System; -using System.Threading.Tasks; -using Microsoft.AspNetCore.Mvc; +## Create a Books Page -namespace Acme.BookStore.Web.Pages.Books -{ - public class EditModalModel : BookStorePageModel - { - [HiddenInput] - [BindProperty(SupportsGet = true)] - public Guid Id { get; set; } +It's time to create something visible and usable! Instead of classic MVC, we will use the [Razor Pages UI](https://docs.microsoft.com/en-us/aspnet/core/tutorials/razor-pages/razor-pages-start) approach which is recommended by Microsoft. - [BindProperty] - public CreateUpdateBookDto Book { get; set; } +Create `Books` folder under the `Pages` folder of the `Acme.BookStore.Web` project. Add a new Razor Page by right clicking the Books folder then selecting **Add > Razor Page** menu item. Name it as `Index`: - private readonly IBookAppService _bookAppService; +![bookstore-add-index-page](./images/bookstore-add-index-page-v2.png) - public EditModalModel(IBookAppService bookAppService) - { - _bookAppService = bookAppService; - } +Open the `Index.cshtml` and change the whole content as shown below: - public async Task OnGetAsync() - { - var bookDto = await _bookAppService.GetAsync(Id); - Book = ObjectMapper.Map(bookDto); - } +````html +@page +@using Acme.BookStore.Web.Pages.Books +@model IndexModel - public async Task OnPostAsync() - { - await _bookAppService.UpdateAsync(Id, Book); - return NoContent(); - } - } -} +

Books

```` -* `[HiddenInput]` and `[BindProperty]` are standard ASP.NET Core MVC attributes. `SupportsGet` is used to be able to get `Id` value from query string parameter of the request. -* In the `GetAsync` method, we get `BookDto `from `BookAppService` and this is being mapped to the DTO object `CreateUpdateBookDto`. -* The `OnPostAsync` uses `BookAppService.UpdateAsync()` to update the entity. +`Index.cshtml.cs` content should be like that: -#### Mapping from BookDto to CreateUpdateBookDto - -To be able to map the `BookDto` to `CreateUpdateBookDto`, configure a new mapping. To do this, open the `BookStoreWebAutoMapperProfile.cs` in the `Acme.BookStore.Web` project and change it as shown below: - -````csharp -using AutoMapper; +```csharp +using Microsoft.AspNetCore.Mvc.RazorPages; -namespace Acme.BookStore.Web +namespace Acme.BookStore.Web.Pages.Books { - public class BookStoreWebAutoMapperProfile : Profile + public class IndexModel : PageModel { - public BookStoreWebAutoMapperProfile() + public void OnGet() { - CreateMap(); + } } } -```` - -* We have just added `CreateMap();` to define this mapping. +``` -#### EditModal.cshtml +### Add Books Page to the Main Menu -Replace `EditModal.cshtml` content with the following content: +Open the `BookStoreMenuContributor` class in the `Menus` folder and add the following code to the end of the `ConfigureMainMenuAsync` method: -````html -@page -@using Acme.BookStore.Web.Pages.Books -@using Volo.Abp.AspNetCore.Mvc.UI.Bootstrap.TagHelpers.Modal -@model EditModalModel -@{ - Layout = null; -} - - - - - - - - - - +````csharp +context.Menu.AddItem( + new ApplicationMenuItem( + "BooksStore", + l["Menu:BookStore"], + icon: "fa fa-book" + ).AddItem( + new ApplicationMenuItem( + "BooksStore.Books", + l["Menu:Books"], + url: "/Books" + ) + ) +); ```` -This page is very similar to the `CreateModal.cshtml`, except: - -* It includes an `abp-input` for the `Id` property to store `Id` of the editing book (which is a hidden input). -* It uses `Books/EditModal` as the post URL and *Update* text as the modal header. - -#### Add "Actions" dropdown to the table +Run the project, login to the application with the username `admin` and the password `1q2w3E*` and see the new menu item has been added to the main menu: -We will add a dropdown button to the table named *Actions*. +![bookstore-menu-items](./images/bookstore-new-menu-item.png) -Open the `Pages/Books/Index.cshtml` page and change the `` section as shown below: +When you click to the Books menu item under the Book Store parent, you are being redirected to the new empty Books Page. -````html - - - - @L["Actions"] - @L["Name"] - @L["Type"] - @L["PublishDate"] - @L["Price"] - @L["CreationTime"] - - - -```` - -* We just added a new `th` tag for the "*Actions*" button. +### Book List -Open the `pages/books/index.js` and replace the content as below: - -````js -$(function () { +We will use the [Datatables.net](https://datatables.net/) jQuery library to show the book list. Datatables library completely work via AJAX, it is fast, popular and provides a good user experience. - var l = abp.localization.getResource('BookStore'); +> Datatables library is configured in the startup template, so you can directly use it in any page without including any style or script file to your page. - var createModal = new abp.ModalManager(abp.appPath + 'Books/CreateModal'); - var editModal = new abp.ModalManager(abp.appPath + 'Books/EditModal'); - - var dataTable = $('#BooksTable').DataTable(abp.libs.datatables.normalizeConfiguration({ - processing: true, - serverSide: true, - paging: true, - searching: false, - autoWidth: false, - scrollCollapse: true, - order: [[1, "asc"]], - ajax: abp.libs.datatables.createAjax(acme.bookStore.book.getList), - columnDefs: [ - { - rowAction: { - items: - [ - { - text: l('Edit'), - action: function (data) { - editModal.open({ id: data.record.id }); - } - } - ] - } - }, - { data: "name" }, - { data: "type" }, - { data: "publishDate" }, - { data: "price" }, - { data: "creationTime" } - ] - })); - - createModal.onResult(function () { - dataTable.ajax.reload(); - }); +#### Index.cshtml - editModal.onResult(function () { - dataTable.ajax.reload(); - }); +Change the `Pages/Books/Index.cshtml` as following: - $('#NewBookButton').click(function (e) { - e.preventDefault(); - createModal.open(); - }); -}); +````html +@page +@using Acme.BookStore.Localization +@using Acme.BookStore.Web.Pages.Books +@using Microsoft.Extensions.Localization +@model IndexModel +@inject IStringLocalizer L +@section scripts +{ + +} + + +

@L["Books"]

+ + + + + ```` -* Used `abp.localization.getResource('BookStore')` to be able to use the same localization texts defined on the server-side. -* Added a new `ModalManager` named `createModal` to open the create modal dialog. -* Added a new `ModalManager` named `editModal` to open the edit modal dialog. -* Added a new column at the beginning of the `columnDefs` section. This column is used for the "*Actions*" dropdown button. -* "*New Book*" action simply calls `createModal.open()` to open the create dialog. -* "*Edit*" action simply calls `editModal.open()` to open the edit dialog. - -You can run the application and edit any book by selecting the edit action. The final UI looks as below: +* `abp-script` [tag helper](https://docs.microsoft.com/en-us/aspnet/core/mvc/views/tag-helpers/intro) is used to add external **scripts** to the page. It has many additional features compared to standard `script` tag. It handles **minification** and **versioning**. See the [bundling & minification document](../UI/AspNetCore/Bundling-Minification.md) for details. +* `abp-card` is a tag helper for Twitter Bootstrap's [card component](https://getbootstrap.com/docs/4.5/components/card/). There are other useful tag helpers provided by the ABP Framework to easily use most of the [bootstrap](https://getbootstrap.com/) components. You could use the regular HTML tags instead of these tag helpers, but using tag helpers reduces HTML code and prevents errors by help the of IntelliSense and compile time type checking. Further information, see the [tag helpers](../UI/AspNetCore/Tag-Helpers/Index.md) document. -![bookstore-books-table-actions](./images/bookstore-edit-button.png) +#### Index.js -### Deleting a book - -Open the `pages/books/index.js` and add a new item to the `rowAction` `items`: - -````js -{ - text: l('Delete'), - confirmMessage: function (data) { - return l('BookDeletionConfirmationMessage', data.record.name); - }, - action: function (data) { - acme.bookStore.book - .delete(data.record.id) - .then(function() { - abp.notify.info(l('SuccessfullyDeleted')); - dataTable.ajax.reload(); - }); - } -} -```` +Create an `Index.js` file under the `Pages/Books` folder: -* `confirmMessage` option is used to ask a confirmation question before executing the `action`. -* `acme.bookStore.book.delete()` method makes an AJAX request to JavaScript proxy function to delete a book. -* `abp.notify.info()` shows a notification after the delete operation. +![bookstore-index-js-file](./images/bookstore-index-js-file-v3.png) -The final `index.js` content is shown below: +The content of the file is shown below: ````js $(function () { - var l = abp.localization.getResource('BookStore'); - var createModal = new abp.ModalManager(abp.appPath + 'Books/CreateModal'); - var editModal = new abp.ModalManager(abp.appPath + 'Books/EditModal'); - - var dataTable = $('#BooksTable').DataTable(abp.libs.datatables.normalizeConfiguration({ - processing: true, - serverSide: true, - paging: true, - searching: false, - autoWidth: false, - scrollCollapse: true, - order: [[1, "asc"]], - ajax: abp.libs.datatables.createAjax(acme.bookStore.book.getList), - columnDefs: [ - { - rowAction: { - items: - [ - { - text: l('Edit'), - action: function (data) { - editModal.open({ id: data.record.id }); - } - }, - { - text: l('Delete'), - confirmMessage: function (data) { - return l('BookDeletionConfirmationMessage', data.record.name); - }, - action: function (data) { - acme.bookStore.book - .delete(data.record.id) - .then(function() { - abp.notify.info(l('SuccessfullyDeleted')); - dataTable.ajax.reload(); - }); - } - } - ] + var dataTable = $('#BooksTable').DataTable( + abp.libs.datatables.normalizeConfiguration({ + serverSide: true, + paging: true, + order: [[1, "asc"]], + searching: false, + scrollX: true, + ajax: abp.libs.datatables.createAjax(acme.bookStore.books.book.getList), + columnDefs: [ + { + title: l('Name'), + data: "name" + }, + { + title: l('Type'), + data: "type", + render: function (data) { + return l('Enum:BookType:' + data); + } + }, + { + title: l('PublishDate'), + data: "publishDate", + render: function (data) { + return luxon + .DateTime + .fromISO(data, { + locale: abp.localization.currentCulture.name + }).toLocaleString(); + } + }, + { + title: l('Price'), + data: "price" + }, + { + title: l('CreationTime'), data: "creationTime", + render: function (data) { + return luxon + .DateTime + .fromISO(data, { + locale: abp.localization.currentCulture.name + }).toLocaleString(luxon.DateTime.DATETIME_SHORT); + } } - }, - { data: "name" }, - { data: "type" }, - { data: "publishDate" }, - { data: "price" }, - { data: "creationTime" } - ] - })); - - createModal.onResult(function () { - dataTable.ajax.reload(); - }); - - editModal.onResult(function () { - dataTable.ajax.reload(); - }); - - $('#NewBookButton').click(function (e) { - e.preventDefault(); - createModal.open(); - }); + ] + }) + ); }); ```` -Open the `en.json` in the `Acme.BookStore.Domain.Shared` project and add the following translations: - -````json -"BookDeletionConfirmationMessage": "Are you sure to delete the book {0}?", -"SuccessfullyDeleted": "Successfully deleted" -```` - -Run the application and try to delete a book. - -{{end}} - -{{if UI == "NG"}} - -### Creating a new book - -In this section, you will learn how to create a new modal dialog form to create a new book. - -#### Add a modal to BookListComponent - -Open `book-list.component.ts` file in `app\book\book-list` folder and replace the content as below: - -```js -import { ListService, PagedResultDto } from '@abp/ng.core'; -import { Component, OnInit } from '@angular/core'; -import { BookDto, BookType } from '../models'; -import { BookService } from '../services'; - -@Component({ - selector: 'app-book-list', - templateUrl: './book-list.component.html', - styleUrls: ['./book-list.component.scss'], - providers: [ListService], -}) -export class BookListComponent implements OnInit { - book = { items: [], totalCount: 0 } as PagedResultDto; - - booksType = BookType; - - isModalOpen = false; // <== added this line ==> - - constructor(public readonly list: ListService, private bookService: BookService) {} - - ngOnInit() { - const bookStreamCreator = (query) => this.bookService.getListByInput(query); - - this.list.hookToQuery(bookStreamCreator).subscribe((response) => { - this.book = response; - }); - } - - // added createBook method - createBook() { - this.isModalOpen = true; - } -} -``` - -* We defined a variable called `isModalOpen` and `createBook` method. -* We added the `createBook` method. - - -Open `book-list.component.html` file in `books\book-list` folder and replace the content as below: - -```html -
-
-
-
-
{%{{{ '::Menu:Books' | abpLocalization }}}%}
-
- -
-
- -
-
-
-
-
- - - - - {%{{{ booksType[row.type] }}}%} - - - - - {%{{{ row.publishDate | date }}}%} - - - - - {%{{{ row.price | currency }}}%} - - - -
-
- - - - -

{%{{{ '::NewBook' | abpLocalization }}}%}

- +* `abp.localization.getResource` gets a function that is used to localize text using the same JSON file defined in the server side. In this way, you can share the localization values with the client side. +* `abp.libs.datatables.normalizeConfiguration` is a helper function defined by the ABP Framework. There's no requirement to use it, but it simplifies the [Datatables](https://datatables.net/) configuration by providing conventional default values for missing options. +* `abp.libs.datatables.createAjax` is another helper function to adapt ABP's dynamic JavaScript API proxies to [Datatable](https://datatables.net/)'s expected parameter format +* `acme.bookStore.books.book.getList` is the dynamic JavaScript proxy function introduced before. +* [luxon](https://moment.github.io/luxon/) library is also a standard library that is pre-configured in the solution, so you can use to perform date/time operations easily. - +> See [Datatables documentation](https://datatables.net/manual/) for all configuration options. - - - - -``` +## Run the Final Application -* We added the `abp-modal` which renders a modal to allow user to create a new book. -* `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`. +You can run the application! The final UI of this part is shown below: -You can open your browser and click **New book** button to see the new modal. +![Book list](images/bookstore-book-list-3.png) -![Empty modal for new book](./images/bookstore-empty-new-book-modal.png) +This is a fully working, server side paged, sorted and localized table of books. -#### Create a reactive form - -[Reactive forms](https://angular.io/guide/reactive-forms) provide a model-driven approach to handling form inputs whose values change over time. - -Open `book-list.component.ts` file in `app\book\book-list` folder and replace the content as below: - -```js -import { ListService, PagedResultDto } from '@abp/ng.core'; -import { Component, OnInit } from '@angular/core'; -import { BookDto, BookType } from '../models'; -import { BookService } from '../services'; -import { FormGroup, FormBuilder, Validators } from '@angular/forms'; // <== added this line ==> - -@Component({ - selector: 'app-book-list', - templateUrl: './book-list.component.html', - styleUrls: ['./book-list.component.scss'], - providers: [ListService], -}) -export class BookListComponent implements OnInit { - book = { items: [], totalCount: 0 } as PagedResultDto; - - booksType = BookType; - - isModalOpen = false; +{{end}} - form: FormGroup; // <== added this line ==> +{{if UI == "NG"}} - constructor( - public readonly list: ListService, - private bookService: BookService, - private fb: FormBuilder // <== injected FormBuilder ==> - ) {} +## Install NPM packages - ngOnInit() { - const bookStreamCreator = (query) => this.bookService.getListByInput(query); +> Notice: This tutorial is based on the ABP Framework v3.0.3+ If your project version is older, then please upgrade your solution. See the [migration guide](../UI/Angular/Migration-Guide-v3.md) if you are upgrading an existing project with v2.x. - this.list.hookToQuery(bookStreamCreator).subscribe((response) => { - this.book = response; - }); - } +If you haven't done it before, open a new command line interface (terminal window) and go to your `angular` folder and then run `yarn` command to install NPM packages: - createBook() { - this.buildForm(); // <== added this line ==> - this.isModalOpen = true; - } - - // added buildForm method - buildForm() { - this.form = this.fb.group({ - name: ['', Validators.required], - type: [null, Validators.required], - publishDate: [null, Validators.required], - price: [null, Validators.required], - }); - } -} +```bash +yarn ``` -* We imported `FormGroup, FormBuilder and Validators`. -* We added `form: FormGroup` variable. -* We injected `fb: FormBuilder` service to the constructor. The [FormBuilder](https://angular.io/api/forms/FormBuilder) service provides convenient methods for generating controls. It reduces the amount of boilerplate needed to build complex forms. -* We added `buildForm` method to the end of the file and executed `buildForm()` in the `createBook` method. This method creates a reactive form to be able to create a new book. - * The `group` method of `FormBuilder`, `fb` creates a `FormGroup`. - * Added `Validators.required` static method which validates the relevant form element. +## Create a Books Page -#### Create the DOM elements of the form +It's time to create something visible and usable! There are some tools that we will use when developing the Angular frontend application: -Open `book-list.component.html` in `app\books\book-list` folder and replace ` ` with the following code part: +- [Ng Bootstrap](https://ng-bootstrap.github.io/#/home) will be used as the UI component library. +- [Ngx-Datatable](https://swimlane.gitbook.io/ngx-datatable/) will be used as the datatable library. -```html - -
-
- * - -
+### BookModule -
- * - -
- -
- * - -
+Run the following command line to create a new module, named `BookModule` in the root folder of the angular application: -
- * - -
-
- +```bash +yarn ng generate module book --module app --routing --route books ``` -- This template creates a form with `Name`, `Price`, `Type` and `Publish` date fields. -- We've used [NgBootstrap datepicker](https://ng-bootstrap.github.io/#/components/datepicker/overview) in this component. +This command should produce the following output: + +````bash +> yarn ng generate module book --module app --routing --route books + +yarn run v1.19.1 +$ ng generate module book --module app --routing --route books +CREATE src/app/book/book-routing.module.ts (336 bytes) +CREATE src/app/book/book.module.ts (335 bytes) +CREATE src/app/book/book.component.html (19 bytes) +CREATE src/app/book/book.component.spec.ts (614 bytes) +CREATE src/app/book/book.component.ts (268 bytes) +CREATE src/app/book/book.component.scss (0 bytes) +UPDATE src/app/app-routing.module.ts (1289 bytes) +Done in 3.88s. +```` -#### Datepicker requirements +### BookModule -Open `book.module.ts` file in `app\book` folder and replace the content as below: +Open the `/src/app/book/book.module.ts` and replace the content as shown below: -```js +````js import { NgModule } from '@angular/core'; -import { CommonModule } from '@angular/common'; -import { BookRoutingModule } from './book-routing.module'; -import { BookListComponent } from './book-list/book-list.component'; import { SharedModule } from '../shared/shared.module'; -import { NgbDatepickerModule } from '@ng-bootstrap/ng-bootstrap'; //<== added this line ==> +import { BookRoutingModule } from './book-routing.module'; +import { BookComponent } from './book.component'; @NgModule({ - declarations: [BookListComponent], + declarations: [BookComponent], imports: [ - CommonModule, BookRoutingModule, - SharedModule, - NgbDatepickerModule, //<== added this line ==> - ], + SharedModule + ] }) -export class BookModule {} -``` - -* We imported `NgbDatepickerModule` to be able to use the date picker. +export class BookModule { } -Open `book-list.component.ts` file in `app\book\book-list` folder and replace the content as below: - -```js -import { ListService, PagedResultDto } from '@abp/ng.core'; -import { Component, OnInit } from '@angular/core'; -import { BookDto, BookType } from '../models'; -import { BookService } from '../services'; -import { FormGroup, FormBuilder, Validators } from '@angular/forms'; -import { NgbDateNativeAdapter, NgbDateAdapter } from '@ng-bootstrap/ng-bootstrap'; // <== added this line ==> - -@Component({ - selector: 'app-book-list', - templateUrl: './book-list.component.html', - styleUrls: ['./book-list.component.scss'], - providers: [ListService, { provide: NgbDateAdapter, useClass: NgbDateNativeAdapter }], // <== added a provide ==> -}) -export class BookListComponent implements OnInit { - book = { items: [], totalCount: 0 } as PagedResultDto; - - booksType = BookType; - - // <== added bookTypeArr array ==> - bookTypeArr = Object.keys(BookType).filter( - (bookType) => typeof this.booksType[bookType] === 'number' - ); - - isModalOpen = false; +```` - form: FormGroup; +* Added the `SharedModule`. `SharedModule` exports some common modules needed to create user interfaces. +* `SharedModule` already exports the `CommonModule`, so we've removed the `CommonModule`. - constructor( - public readonly list: ListService, - private bookService: BookService, - private fb: FormBuilder - ) {} +### Routing - ngOnInit() { - const bookStreamCreator = (query) => this.bookService.getListByInput(query); +Generated code places the new route definition to the `src/app/app-routing.module.ts` file as shown below: - this.list.hookToQuery(bookStreamCreator).subscribe((response) => { - this.book = response; - }); - } +````js +const routes: Routes = [ + // other route definitions... + { path: 'books', loadChildren: () => import('./book/book.module').then(m => m.BookModule) }, +]; +```` - createBook() { - this.buildForm(); - this.isModalOpen = true; - } +Now, open the `src/app/route.provider.ts` file replace the `configureRoutes` function declaration as shown below: - buildForm() { - this.form = this.fb.group({ - name: ['', Validators.required], - type: [null, Validators.required], - publishDate: [null, Validators.required], - price: [null, Validators.required], - }); - } +```js +function configureRoutes(routes: RoutesService) { + return () => { + routes.add([ + { + path: '/', + name: '::Menu:Home', + iconClass: 'fas fa-home', + order: 1, + layout: eLayoutType.application, + }, + { + path: '/book-store', + name: '::Menu:BookStore', + iconClass: 'fas fa-book', + order: 2, + layout: eLayoutType.application, + }, + { + path: '/books', + name: '::Menu:Books', + parentName: '::Menu:BookStore', + layout: eLayoutType.application, + }, + ]); + }; } ``` -* We imported ` NgbDateNativeAdapter, NgbDateAdapter` - -* We added a new provider `NgbDateAdapter` that converts Datepicker value to `Date` type. See the [datepicker adapters](https://ng-bootstrap.github.io/#/components/datepicker/overview) for more details. - -* We added `bookTypeArr` array to be able to use it in the combobox values. The `bookTypeArr` contains the fields of the `BookType` enum. Resulting array is shown below: - - ```js - ['Adventure', 'Biography', 'Dystopia', 'Fantastic' ...] - ``` - - This array was used in the previous form template in the `ngFor` loop. - -Now, you can open your browser to see the changes: - - -![New book modal](./images/bookstore-new-book-form.png) - -#### Saving the book - -Open `book-list.component.ts` file in `app\book\book-list` folder and replace the content as below: - -```js -import { ListService, PagedResultDto } from '@abp/ng.core'; -import { Component, OnInit } from '@angular/core'; -import { BookDto, BookType } from '../models'; -import { BookService } from '../services'; -import { FormGroup, FormBuilder, Validators } from '@angular/forms'; -import { NgbDateNativeAdapter, NgbDateAdapter } from '@ng-bootstrap/ng-bootstrap'; - -@Component({ - selector: 'app-book-list', - templateUrl: './book-list.component.html', - styleUrls: ['./book-list.component.scss'], - providers: [ListService, { provide: NgbDateAdapter, useClass: NgbDateNativeAdapter }], -}) -export class BookListComponent implements OnInit { - book = { items: [], totalCount: 0 } as PagedResultDto; - - booksType = BookType; - - bookTypeArr = Object.keys(BookType).filter( - (bookType) => typeof this.booksType[bookType] === 'number' - ); +`RoutesService` is a service provided by the ABP Framework to configure the main menu and the routes. - isModalOpen = false; +* `path` is the URL of the route. +* `name` is the localized menu item name (see the [localization document](../UI/Angular/Localization.md) for details). +* `iconClass` is the icon of the menu item (you can use [Font Awesome](https://fontawesome.com/) icons by default). +* `order` is the order of the menu item. +* `layout` is the layout of the BooksModule's routes (there are three types of pre-defined layouts: `eLayoutType.application`, `eLayoutType.account` or `eLayoutType.empty`). - form: FormGroup; +For more information, see the [RoutesService document](https://docs.abp.io/en/abp/latest/UI/Angular/Modifying-the-Menu.md#via-routesservice). - constructor( - public readonly list: ListService, - private bookService: BookService, - private fb: FormBuilder - ) {} +### Service Proxy Generation - ngOnInit() { - const bookStreamCreator = (query) => this.bookService.getListByInput(query); +[ABP CLI](../CLI.md) provides `generate-proxy` command that generates client proxies for your HTTP APIs to make easy to consume your HTTP APIs from the client side. Before running `generate-proxy` command, your host must be up and running. - this.list.hookToQuery(bookStreamCreator).subscribe((response) => { - this.book = response; - }); - } +Run the following command in the `angular` folder: - createBook() { - this.buildForm(); - this.isModalOpen = true; - } - - buildForm() { - this.form = this.fb.group({ - name: ['', Validators.required], - type: [null, Validators.required], - publishDate: [null, Validators.required], - price: [null, Validators.required], - }); - } - - // <== added save ==> - save() { - if (this.form.invalid) { - return; - } - - this.bookService.createByInput(this.form.value).subscribe(() => { - this.isModalOpen = false; - this.form.reset(); - this.list.get(); - }); - } -} +```bash +abp generate-proxy --apiUrl https://localhost:XXXXX ``` -* We added `save` method +* XXXXX should be replaced with the backend port of your application. +* If you don't specify the `--apiUrl` parameter, it will try to get the URL from the `src/environments/environment.ts` file. -Open `book-list.component.html` in `app\book\book-list` folder, find the `` element and replace this element with the following to create a new book. +The generated files looks like below: -```html - - - - - - -``` +![Generated files](./images/generated-proxies-2.png) -Find the `
` tag and replace below content: +### BookComponent -```html - -``` - - -* We added the `(ngSubmit)="save()"` to `` element to save a new book by pressing the enter. -* We added `abp-button` to the bottom area of the modal to save a new book. - -The final modal UI looks like below: - -![Save button to the modal](./images/bookstore-new-book-form-v2.png) - -### Updating a book - -Open `book-list.component.ts` in `app\book\book-list` folder and add a variable named `selectedBook`. +Open the `/src/app/book/book.component.ts` file and replace the content as below: ```js import { ListService, PagedResultDto } from '@abp/ng.core'; import { Component, OnInit } from '@angular/core'; -import { BookDto, BookType } from '../models'; -import { BookService } from '../services'; -import { FormGroup, FormBuilder, Validators } from '@angular/forms'; -import { NgbDateNativeAdapter, NgbDateAdapter } from '@ng-bootstrap/ng-bootstrap'; +import { BookDto, BookType } from './models'; +import { BookService } from './services'; @Component({ - selector: 'app-book-list', - templateUrl: './book-list.component.html', - styleUrls: ['./book-list.component.scss'], - providers: [ListService, { provide: NgbDateAdapter, useClass: NgbDateNativeAdapter }], + selector: 'app-book', + templateUrl: './book.component.html', + styleUrls: ['./book.component.scss'], + providers: [ListService], }) -export class BookListComponent implements OnInit { +export class BookComponent implements OnInit { book = { items: [], totalCount: 0 } as PagedResultDto; booksType = BookType; - bookTypeArr = Object.keys(BookType).filter( - (bookType) => typeof this.booksType[bookType] === 'number' - ); - - isModalOpen = false; - - form: FormGroup; - - selectedBook = {} as BookDto; // <== declared selectedBook ==> - - constructor( - public readonly list: ListService, - private bookService: BookService, - private fb: FormBuilder - ) {} + constructor(public readonly list: ListService, private bookService: BookService) {} ngOnInit() { const bookStreamCreator = (query) => this.bookService.getListByInput(query); @@ -928,198 +494,55 @@ export class BookListComponent implements OnInit { this.book = response; }); } - - // <== this method is replaced ==> - createBook() { - this.selectedBook = {} as BookDto; // <== added ==> - this.buildForm(); - this.isModalOpen = true; - } - - // <== added editBook method ==> - editBook(id: string) { - this.bookService.getById(id).subscribe((book) => { - this.selectedBook = book; - this.buildForm(); - this.isModalOpen = true; - }); - } - - // <== this method is replaced ==> - buildForm() { - this.form = this.fb.group({ - name: [this.selectedBook.name || '', Validators.required], - type: [this.selectedBook.type || null, Validators.required], - publishDate: [ - this.selectedBook.publishDate ? new Date(this.selectedBook.publishDate) : null, - Validators.required, - ], - price: [this.selectedBook.price || null, Validators.required], - }); - } - - // <== this method is replaced ==> - save() { - if (this.form.invalid) { - return; - } - - // <== added request ==> - const request = this.selectedBook.id - ? this.bookService.updateByIdAndInput(this.form.value, this.selectedBook.id) - : this.bookService.createByInput(this.form.value); - - request.subscribe(() => { - this.isModalOpen = false; - this.form.reset(); - this.list.get(); - }); - } } ``` -* We declared a variable named `selectedBook` as `BookDto`. -* We added `editBook` method. This method fetches the book with the given `Id` and sets it to `selectedBook` object. -* We replaced the `buildForm` method so that it creates the form with the `selectedBook` data. -* We replaced the `createBook` method so it sets `selectedBook` to an empty object. -* We replaced the `save` method. - -#### Add "Actions" dropdown to the table +* We imported and injected the generated `BookService`. +* We are using the [ListService](https://docs.abp.io/en/abp/latest/UI/Angular/List-Service), a utility service of the ABP Framework which provides easy pagination, sorting and searching. -Open the `book-list.component.html` in `app\book\book-list` folder and replace the `
` tag as below: +Open the `/src/app/book/book.component.html` and replace the content as below: ```html -
- - - - -
- -
- -
-
- - - - - - {%{{{ booksType[row.type] }}}%} - - - - - {%{{{ row.publishDate | date }}}%} - - - - - {%{{{ row.price | currency }}}%} - - - -
-``` - -- We added a `ngx-datatable-column` for the "Actions" column. -- We added `button` with `ngbDropdownToggle` to open actions when clicked the button. -- We have used to [NgbDropdown](https://ng-bootstrap.github.io/#/components/dropdown/examples) for the dropdown menu of actions. - -The final UI looks like as below: - -![Action buttons](./images/bookstore-actions-buttons.png) - -Open `book-list.component.html` in `app\book\book-list` folder and find the `` tag and replace the content as below. - -```html - -

{%{{{ (selectedBook.id ? '::Edit' : '::NewBook' ) | abpLocalization }}}%}

- -``` - -* This template will show **Edit** text for edit record operation, **New Book** for new record operation in the title. - -### Deleting a book - -#### Delete confirmation popup - -Open `book-list.component.ts` in `app\book\book-list` folder and inject the `ConfirmationService`. - -Replace the constructor as below: - -```js -import { ConfirmationService } from '@abp/ng.theme.shared'; -//... - -constructor( - public readonly list: ListService, - private bookService: BookService, - private fb: FormBuilder, - private confirmation: ConfirmationService // <== added this line ==> -) {} -``` - -* We imported `ConfirmationService`. -* We injected `ConfirmationService` to the constructor. - -See the [Confirmation Popup documentation](https://docs.abp.io/en/abp/latest/UI/Angular/Confirmation-Service) - -In the `book-list.component.ts` add a delete method: - -```js -import { ConfirmationService, Confirmation } from '@abp/ng.theme.shared'; //<== imported Confirmation namespace ==> - -//... - -delete(id: string) { - this.confirmation.warn('::AreYouSureToDelete', 'AbpAccount::AreYouSure').subscribe((status) => { - if (status === Confirmation.Status.confirm) { - this.bookService.deleteById(id).subscribe(() => this.list.get()); - } - }); -} -``` - - -The `delete` method shows a confirmation popup and subscribes for the user response. The `deleteById` method of `BookService` called only if user clicks to the `Yes` button. The confirmation popup looks like below: - -![bookstore-confirmation-popup](./images/bookstore-confirmation-popup.png) - - -#### Add a delete button - - -Open `book-list.component.html` in `app\book\book-list` folder and modify the `ngbDropdownMenu` to add the delete button as shown below: - -```html -
- - +
+
+
+
+
+ {%{{{ '::Menu:Books' | abpLocalization }}}%} +
+
+
+
+
+
+ + + + + {%{{{ '::Enum:BookType:' + row.type | abpLocalization }}}%} + + + + + {%{{{ row.publishDate | date }}}%} + + + + + {%{{{ row.price | currency }}}%} + + + +
``` -The final actions dropdown UI looks like below: +Now you can see the final result on your browser: -![bookstore-final-actions-dropdown](./images/bookstore-final-actions-dropdown.png) +![Book list final result](./images/bookstore-book-list.png) {{end}} -### Next Part +## The Next Part -See the [next part](part-3.md) of this tutorial. +See the [next part](Part-3.md) of this tutorial. diff --git a/docs/en/Tutorials/Part-3.md b/docs/en/Tutorials/Part-3.md index 14822c9fe2..275f1b9730 100644 --- a/docs/en/Tutorials/Part-3.md +++ b/docs/en/Tutorials/Part-3.md @@ -1,198 +1,1185 @@ -## ASP.NET Core {{UI_Value}} Tutorial - Part 3 +# Web Application Development Tutorial - Part 3: Creating, Updating and Deleting Books ````json //[doc-params] { - "UI": ["MVC","NG"] + "UI": ["MVC","NG"], + "DB": ["EF","Mongo"] } ```` - {{ if UI == "MVC" - DB="ef" - DB_Text="Entity Framework Core" UI_Text="mvc" else if UI == "NG" - DB="mongodb" - DB_Text="MongoDB" UI_Text="angular" -else - DB ="?" +else UI_Text="?" end +if DB == "EF" + DB_Text="Entity Framework Core" +else if DB == "Mongo" + DB_Text="MongoDB" +else + DB_Text="?" +end }} -### About this tutorial +## About This Tutorial -This is the third part of the ASP.NET Core {{UI_Value}} tutorial series. See all parts: +In this tutorial series, you will build an ABP based web application named `Acme.BookStore`. This application is used to manage a list of books and their authors. It is developed using the following technologies: -- [Part I: Creating the project and book list page](part-1.md) -- [Part II: Creating, updating and deleting books](part-2.md) -- **Part III: Integration tests (this tutorial)** +* **{{DB_Text}}** as the ORM provider. +* **{{UI_Value}}** as the UI Framework. -*You can also check out [the video course](https://amazingsolutions.teachable.com/p/lets-build-the-bookstore-application) prepared by the community, based on this tutorial.* +This tutorial is organized as the following parts; -### Test projects in the solution +- [Part 1: Creating the project and book list page](Part-1.md) +- [Part 2: The book list page](Part-2.md) +- **Part 3: Creating, updating and deleting books (this part)** +- [Part 4: Integration tests](Part-4.md) +- [Part 5: Authorization](Part-5.md) -This part covers the **server side** tests. There are several test projects in the solution: +### Download the Source Code -![bookstore-test-projects-v2](./images/bookstore-test-projects-{{UI_Text}}.png) +This tutorials has multiple versions based on your **UI** and **Database** preferences. We've prepared two combinations of the source code to be downloaded: -Each project is used to test the related project. Test projects use the following libraries for testing: +* [MVC (Razor Pages) UI with EF Core](https://github.com/abpframework/abp-samples/tree/master/BookStore-Mvc-EfCore) +* [Angular UI with MongoDB](https://github.com/abpframework/abp-samples/tree/master/BookStore-Angular-MongoDb) -* [Xunit](https://xunit.github.io/) as the main test framework. -* [Shoudly](http://shouldly.readthedocs.io/en/latest/) as the assertion library. -* [NSubstitute](http://nsubstitute.github.io/) as the mocking library. +{{if UI == "MVC"}} -### Adding test data +## Creating a New Book -Startup template contains the `BookStoreTestDataBuilder` class in the `Acme.BookStore.TestBase` project which creates initial data to run tests. Change the content of `BookStoreTestDataSeedContributor` class as show below: +In this section, you will learn how to create a new modal dialog form to create a new book. The modal dialog will look like in the image below: -````csharp -using System; +![bookstore-create-dialog](./images/bookstore-create-dialog-2.png) + +### Create the Modal Form + +Create a new razor page, named `CreateModal.cshtml` under the `Pages/Books` folder of the `Acme.BookStore.Web` project. + +![bookstore-add-create-dialog](./images/bookstore-add-create-dialog-v2.png) + +#### CreateModal.cshtml.cs + +Open the `CreateModal.cshtml.cs` file (`CreateModalModel` class) and replace with the following code: + +````C# using System.Threading.Tasks; -using Volo.Abp.Data; -using Volo.Abp.DependencyInjection; -using Volo.Abp.Domain.Repositories; -using Volo.Abp.Guids; +using Acme.BookStore.Books; +using Microsoft.AspNetCore.Mvc; -namespace Acme.BookStore +namespace Acme.BookStore.Web.Pages.Books { - public class BookStoreTestDataSeedContributor - : IDataSeedContributor, ITransientDependency + public class CreateModalModel : BookStorePageModel { - private readonly IRepository _bookRepository; - private readonly IGuidGenerator _guidGenerator; + [BindProperty] + public CreateUpdateBookDto Book { get; set; } + + private readonly IBookAppService _bookAppService; - public BookStoreTestDataSeedContributor( - IRepository bookRepository, - IGuidGenerator guidGenerator) + public CreateModalModel(IBookAppService bookAppService) { - _bookRepository = bookRepository; - _guidGenerator = guidGenerator; + _bookAppService = bookAppService; } - public async Task SeedAsync(DataSeedContext context) + public void OnGet() { - await _bookRepository.InsertAsync( - new Book(id: _guidGenerator.Create(), - name: "Test book 1", - type: BookType.Fantastic, - publishDate: new DateTime(2015, 05, 24), - price: 21 - ) - ); - - await _bookRepository.InsertAsync( - new Book(id: _guidGenerator.Create(), - name: "Test book 2", - type: BookType.Science, - publishDate: new DateTime(2014, 02, 11), - price: 15 - ) - ); + Book = new CreateUpdateBookDto(); + } + + public async Task OnPostAsync() + { + await _bookAppService.CreateAsync(Book); + return NoContent(); } } } ```` -* `IRepository` is injected and used it in the `SeedAsync` to create two book entities as the test data. -* `IGuidGenerator` is injected to create GUIDs. While `Guid.NewGuid()` would perfectly work for testing, `IGuidGenerator` has additional features especially important while using real databases. Further information, see the [Guid generation document](../Guid-Generation.md). +* This class is derived from the `BookStorePageModel` instead of standard `PageModel`. `BookStorePageModel` indirectly inherits the `PageModel` and adds some common properties & methods that can be shared in your page model classes. +* `[BindProperty]` attribute on the `Book` property binds post request data to this property. +* This class simply injects the `IBookAppService` in the constructor and calls the `CreateAsync` method in the `OnPostAsync` handler. +* It creates a new `CreateUpdateBookDto` object in the `OnGet` method. ASP.NET Core can work without creating a new instance like that. However, it doesn't create an instance for you and if your class has some default value assignments or code execution in the class constructor, they won't work. For this case, we set default values for some of the `CreateUpdateBookDto` properties. + +#### CreateModal.cshtml + +Open the `CreateModal.cshtml` file and paste the code below: + +````html +@page +@using Acme.BookStore.Localization +@using Acme.BookStore.Web.Pages.Books +@using Microsoft.Extensions.Localization +@using Volo.Abp.AspNetCore.Mvc.UI.Bootstrap.TagHelpers.Modal +@model CreateModalModel +@inject IStringLocalizer L +@{ + Layout = null; +} + + + + + + + + + +```` + +* This modal uses `abp-dynamic-form` [tag helper](../UI/AspNetCore/Tag-Helpers/Dynamic-Forms.md) to automatically create the form from the `CreateBookViewModel` model class. +* `abp-model` attribute indicates the model object where it's the `Book` property in this case. +* `abp-form-content` tag helper is a placeholder to render the form controls (it is optional and needed only if you have added some other content in the `abp-dynamic-form` tag, just like in this page). + +> Tip: `Layout` should be `null` just as done in this example since we don't want to include all the layout for the modals when they are loaded via AJAX. + +### Add the "New book" Button + +Open the `Pages/Books/Index.cshtml` and set the content of `abp-card-header` tag as below: -### Testing the application service BookAppService +````html + + + + @L["Books"] + + + + + + +```` + +The final content of the `Index.cshtml` is shown below: -Create a test class named `BookAppService_Tests` in the `Acme.BookStore.Application.Tests` project: +````html +@page +@using Acme.BookStore.Localization +@using Acme.BookStore.Web.Pages.Books +@using Microsoft.Extensions.Localization +@model IndexModel +@inject IStringLocalizer L +@section scripts +{ + +} + + + + + + @L["Books"] + + + + + + + + + + +```` + +This adds a new button called **New book** to the **top-right** of the table: + +![bookstore-new-book-button](./images/bookstore-new-book-button-2.png) + +Open the `Pages/Books/Index.js` and add the following code just after the `Datatable` configuration: + +````js +var createModal = new abp.ModalManager(abp.appPath + 'Books/CreateModal'); + +createModal.onResult(function () { + dataTable.ajax.reload(); +}); + +$('#NewBookButton').click(function (e) { + e.preventDefault(); + createModal.open(); +}); +```` + +* `abp.ModalManager` is a helper class to manage modals in the client side. It internally uses Twitter Bootstrap's standard modal, but abstracts many details by providing a simple API. +* `createModal.onResult(...)` used to refresh the data table after creating a new book. +* `createModal.open();` is used to open the model to create a new book. + +The final content of the `Index.js` should be like that: + +````js +$(function () { + var l = abp.localization.getResource('BookStore'); + + var dataTable = $('#BooksTable').DataTable( + abp.libs.datatables.normalizeConfiguration({ + serverSide: true, + paging: true, + order: [[1, "asc"]], + searching: false, + scrollX: true, + ajax: abp.libs.datatables.createAjax(acme.bookStore.books.book.getList), + columnDefs: [ + { + title: l('Name'), + data: "name" + }, + { + title: l('Type'), + data: "type", + render: function (data) { + return l('Enum:BookType:' + data); + } + }, + { + title: l('PublishDate'), + data: "publishDate", + render: function (data) { + return luxon + .DateTime + .fromISO(data, { + locale: abp.localization.currentCulture.name + }).toLocaleString(); + } + }, + { + title: l('Price'), + data: "price" + }, + { + title: l('CreationTime'), data: "creationTime", + render: function (data) { + return luxon + .DateTime + .fromISO(data, { + locale: abp.localization.currentCulture.name + }).toLocaleString(luxon.DateTime.DATETIME_SHORT); + } + } + ] + }) + ); + + var createModal = new abp.ModalManager(abp.appPath + 'Books/CreateModal'); + + createModal.onResult(function () { + dataTable.ajax.reload(); + }); + + $('#NewBookButton').click(function (e) { + e.preventDefault(); + createModal.open(); + }); +}); +```` + +Now, you can **run the application** and add some new books using the new modal form. + +## Updating a Book + +Create a new razor page, named `EditModal.cshtml` under the `Pages/Books` folder of the `Acme.BookStore.Web` project: + +![bookstore-add-edit-dialog](./images/bookstore-add-edit-dialog.png) + +### EditModal.cshtml.cs + +Open the `EditModal.cshtml.cs` file (`EditModalModel` class) and replace with the following code: ````csharp using System; -using System.Linq; using System.Threading.Tasks; -using Xunit; -using Shouldly; -using Volo.Abp.Application.Dtos; -using Volo.Abp.Validation; -using Microsoft.EntityFrameworkCore.Internal; +using Acme.BookStore.Books; +using Microsoft.AspNetCore.Mvc; -namespace Acme.BookStore +namespace Acme.BookStore.Web.Pages.Books { - public class BookAppService_Tests : BookStoreApplicationTestBase + public class EditModalModel : BookStorePageModel { + [HiddenInput] + [BindProperty(SupportsGet = true)] + public Guid Id { get; set; } + + [BindProperty] + public CreateUpdateBookDto Book { get; set; } + private readonly IBookAppService _bookAppService; - public BookAppService_Tests() + public EditModalModel(IBookAppService bookAppService) + { + _bookAppService = bookAppService; + } + + public async Task OnGetAsync() { - _bookAppService = GetRequiredService(); + var bookDto = await _bookAppService.GetAsync(Id); + Book = ObjectMapper.Map(bookDto); } - [Fact] - public async Task Should_Get_List_Of_Books() + public async Task OnPostAsync() { - //Act - var result = await _bookAppService.GetListAsync( - new PagedAndSortedResultRequestDto() - ); - - //Assert - result.TotalCount.ShouldBeGreaterThan(0); - result.Items.ShouldContain(b => b.Name == "Test book 1"); + await _bookAppService.UpdateAsync(Id, Book); + return NoContent(); } } } ```` -* `Should_Get_List_Of_Books` test simply uses `BookAppService.GetListAsync` method to get and check the list of users. +* `[HiddenInput]` and `[BindProperty]` are standard ASP.NET Core MVC attributes. `SupportsGet` is used to be able to get `Id` value from query string parameter of the request. +* In the `OnGetAsync` method, we get `BookDto ` from the `BookAppService` and this is being mapped to the DTO object `CreateUpdateBookDto`. +* The `OnPostAsync` uses `BookAppService.UpdateAsync(...)` to update the entity. -Add a new test that creates a valid new book: +### Mapping from BookDto to CreateUpdateBookDto + +To be able to map the `BookDto` to `CreateUpdateBookDto`, configure a new mapping. To do this, open the `BookStoreWebAutoMapperProfile.cs` in the `Acme.BookStore.Web` project and change it as shown below: ````csharp -[Fact] -public async Task Should_Create_A_Valid_Book() +using AutoMapper; + +namespace Acme.BookStore.Web { - //Act - var result = await _bookAppService.CreateAsync( - new CreateUpdateBookDto + public class BookStoreWebAutoMapperProfile : Profile + { + public BookStoreWebAutoMapperProfile() { - Name = "New test book 42", - Price = 10, - PublishDate = System.DateTime.Now, - Type = BookType.ScienceFiction + CreateMap(); } - ); + } +} +```` + +* We have just added `CreateMap();` to define this mapping. - //Assert - result.Id.ShouldNotBe(Guid.Empty); - result.Name.ShouldBe("New test book 42"); +> Notice that we do the mapping definition in the web layer as a best practice since it is only needed in this layer. + +### EditModal.cshtml + +Replace `EditModal.cshtml` content with the following content: + +````html +@page +@using Acme.BookStore.Localization +@using Acme.BookStore.Web.Pages.Books +@using Microsoft.Extensions.Localization +@using Volo.Abp.AspNetCore.Mvc.UI.Bootstrap.TagHelpers.Modal +@model EditModalModel +@inject IStringLocalizer L +@{ + Layout = null; } + + + + + + + + + + ```` -Add a new test that tries to create an invalid book and fails: +This page is very similar to the `CreateModal.cshtml`, except: -````csharp -[Fact] -public async Task Should_Not_Create_A_Book_Without_Name() +* It includes an `abp-input` for the `Id` property to store `Id` of the editing book (which is a hidden input). +* It uses `Books/EditModal` as the post URL. + +### Add "Actions" Dropdown to the Table + +We will add a dropdown button to the table named *Actions*. + +Open the `Pages/Books/Index.js` and replace the content as below: + +````js +$(function () { + var l = abp.localization.getResource('BookStore'); + var createModal = new abp.ModalManager(abp.appPath + 'Books/CreateModal'); + var editModal = new abp.ModalManager(abp.appPath + 'Books/EditModal'); + + var dataTable = $('#BooksTable').DataTable( + abp.libs.datatables.normalizeConfiguration({ + serverSide: true, + paging: true, + order: [[1, "asc"]], + searching: false, + scrollX: true, + ajax: abp.libs.datatables.createAjax(acme.bookStore.books.book.getList), + columnDefs: [ + { + title: l('Actions'), + rowAction: { + items: + [ + { + text: l('Edit'), + action: function (data) { + editModal.open({ id: data.record.id }); + } + } + ] + } + }, + { + title: l('Name'), + data: "name" + }, + { + title: l('Type'), + data: "type", + render: function (data) { + return l('Enum:BookType:' + data); + } + }, + { + title: l('PublishDate'), + data: "publishDate", + render: function (data) { + return luxon + .DateTime + .fromISO(data, { + locale: abp.localization.currentCulture.name + }).toLocaleString(); + } + }, + { + title: l('Price'), + data: "price" + }, + { + title: l('CreationTime'), data: "creationTime", + render: function (data) { + return luxon + .DateTime + .fromISO(data, { + locale: abp.localization.currentCulture.name + }).toLocaleString(luxon.DateTime.DATETIME_SHORT); + } + } + ] + }) + ); + + createModal.onResult(function () { + dataTable.ajax.reload(); + }); + + editModal.onResult(function () { + dataTable.ajax.reload(); + }); + + $('#NewBookButton').click(function (e) { + e.preventDefault(); + createModal.open(); + }); +}); +```` + +* Added a new `ModalManager` named `editModal` to open the edit modal dialog. +* Added a new column at the beginning of the `columnDefs` section. This column is used for the "*Actions*" dropdown button. +* "*Edit*" action simply calls `editModal.open()` to open the edit dialog. +* `editModal.onResult(...)` callback refreshes the data table when you close the edit modal. + +You can run the application and edit any book by selecting the edit action on a book. + +The final UI looks as below: + +![bookstore-books-table-actions](./images/bookstore-edit-button-2.png) + +## Deleting a Book + +Open the `Pages/Books/Index.js` and add a new item to the `rowAction` `items`: + +````js { - var exception = await Assert.ThrowsAsync(async () => - { - await _bookAppService.CreateAsync( - new CreateUpdateBookDto - { - Name = "", - Price = 10, - PublishDate = DateTime.Now, - Type = BookType.ScienceFiction - } - ); - }); - - exception.ValidationErrors - .ShouldContain(err => err.MemberNames.Any(mem => mem == "Name")); + text: l('Delete'), + confirmMessage: function (data) { + return l('BookDeletionConfirmationMessage', data.record.name); + }, + action: function (data) { + acme.bookStore.books.book + .delete(data.record.id) + .then(function() { + abp.notify.info(l('SuccessfullyDeleted')); + dataTable.ajax.reload(); + }); + } +} +```` + +* `confirmMessage` option is used to ask a confirmation question before executing the `action`. +* `acme.bookStore.books.book.delete(...)` method makes an AJAX request to the server to delete a book. +* `abp.notify.info()` shows a notification after the delete operation. + +Since we've used two new localization texts (`BookDeletionConfirmationMessage` and `SuccessfullyDeleted`) you need to add these to the localization file (`en.json` under the `Localization/BookStore` folder of the `Acme.BookStore.Domain.Shared` project): + +````json +"BookDeletionConfirmationMessage": "Are you sure to delete the book '{0}'?", +"SuccessfullyDeleted": "Successfully deleted!" +```` + +The final `Index.js` content is shown below: + +````js +$(function () { + var l = abp.localization.getResource('BookStore'); + var createModal = new abp.ModalManager(abp.appPath + 'Books/CreateModal'); + var editModal = new abp.ModalManager(abp.appPath + 'Books/EditModal'); + + var dataTable = $('#BooksTable').DataTable( + abp.libs.datatables.normalizeConfiguration({ + serverSide: true, + paging: true, + order: [[1, "asc"]], + searching: false, + scrollX: true, + ajax: abp.libs.datatables.createAjax(acme.bookStore.books.book.getList), + columnDefs: [ + { + title: l('Actions'), + rowAction: { + items: + [ + { + text: l('Edit'), + action: function (data) { + editModal.open({ id: data.record.id }); + } + }, + { + text: l('Delete'), + confirmMessage: function (data) { + return l( + 'BookDeletionConfirmationMessage', + data.record.name + ); + }, + action: function (data) { + acme.bookStore.books.book + .delete(data.record.id) + .then(function() { + abp.notify.info( + l('SuccessfullyDeleted') + ); + dataTable.ajax.reload(); + }); + } + } + ] + } + }, + { + title: l('Name'), + data: "name" + }, + { + title: l('Type'), + data: "type", + render: function (data) { + return l('Enum:BookType:' + data); + } + }, + { + title: l('PublishDate'), + data: "publishDate", + render: function (data) { + return luxon + .DateTime + .fromISO(data, { + locale: abp.localization.currentCulture.name + }).toLocaleString(); + } + }, + { + title: l('Price'), + data: "price" + }, + { + title: l('CreationTime'), data: "creationTime", + render: function (data) { + return luxon + .DateTime + .fromISO(data, { + locale: abp.localization.currentCulture.name + }).toLocaleString(luxon.DateTime.DATETIME_SHORT); + } + } + ] + }) + ); + + createModal.onResult(function () { + dataTable.ajax.reload(); + }); + + editModal.onResult(function () { + dataTable.ajax.reload(); + }); + + $('#NewBookButton').click(function (e) { + e.preventDefault(); + createModal.open(); + }); +}); +```` + +You can run the application and try to delete a book. + +{{end}} + +{{if UI == "NG"}} + +## Creating a New Book + +In this section, you will learn how to create a new modal dialog form to create a new book. + +### BookComponent + +Open `/src/app/book/book.component.ts` and replace the content as below: + +```js +import { ListService, PagedResultDto } from '@abp/ng.core'; +import { Component, OnInit } from '@angular/core'; +import { BookDto, BookType } from './models'; +import { BookService } from './services'; + +@Component({ + selector: 'app-book', + templateUrl: './book.component.html', + styleUrls: ['./book.component.scss'], + providers: [ListService], +}) +export class BookComponent implements OnInit { + book = { items: [], totalCount: 0 } as PagedResultDto; + + booksType = BookType; + + isModalOpen = false; // add this line + + constructor(public readonly list: ListService, private bookService: BookService) {} + + ngOnInit() { + const bookStreamCreator = (query) => this.bookService.getListByInput(query); + + this.list.hookToQuery(bookStreamCreator).subscribe((response) => { + this.book = response; + }); + } + + // add new method + createBook() { + this.isModalOpen = true; + } } +``` + +* We defined a property called `isModalOpen` and a method called `createBook`. + + +Open `/src/app/book/book.component.html` and make the following changes: + +```html +
+
+
+
+
{%{{{ '::Menu:Books' | abpLocalization }}}%}
+
+
+ + +
+ +
+ +
+
+
+
+ +
+
+ + + + +

{%{{{ '::NewBook' | abpLocalization }}}%}

+ + + + + + + + +``` + +* Added `New book` button to the card header.. +* Added the `abp-modal` which renders a modal to allow user to create a new book. `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. + +You can open your browser and click **New book** button to see the new modal. + +![Empty modal for new book](./images/bookstore-empty-new-book-modal.png) + +### Create a Reactive Form + +[Reactive forms](https://angular.io/guide/reactive-forms) provide a model-driven approach to handling form inputs whose values change over time. + +Open `/src/app/book/book.component.ts` and replace the content as below: + +```js +import { ListService, PagedResultDto } from '@abp/ng.core'; +import { Component, OnInit } from '@angular/core'; +import { BookDto, BookType } from './models'; +import { BookService } from './services'; +import { FormGroup, FormBuilder, Validators } from '@angular/forms'; // add this + +@Component({ + selector: 'app-book', + templateUrl: './book.component.html', + styleUrls: ['./book.component.scss'], + providers: [ListService], +}) +export class BookComponent implements OnInit { + book = { items: [], totalCount: 0 } as PagedResultDto; + + booksType = BookType; + + form: FormGroup; // add this line + + // add bookTypes as a list of enum members + bookTypes = Object.keys(BookType).filter( + (bookType) => typeof this.booksType[bookType] === 'number' + ); + + isModalOpen = false; + + constructor( + public readonly list: ListService, + private bookService: BookService, + private fb: FormBuilder // inject FormBuilder + ) {} + + ngOnInit() { + const bookStreamCreator = (query) => this.bookService.getListByInput(query); + + this.list.hookToQuery(bookStreamCreator).subscribe((response) => { + this.book = response; + }); + } + + createBook() { + this.buildForm(); // add this line + this.isModalOpen = true; + } + + // add buildForm method + buildForm() { + this.form = this.fb.group({ + name: ['', Validators.required], + type: [null, Validators.required], + publishDate: [null, Validators.required], + price: [null, Validators.required], + }); + } + + // add save method + save() { + if (this.form.invalid) { + return; + } + + this.bookService.createByInput(this.form.value).subscribe(() => { + this.isModalOpen = false; + this.form.reset(); + this.list.get(); + }); + } +} +``` + +* Imported `FormGroup`, `FormBuilder` and `Validators` from `@angular/forms`. +* Added `form: FormGroup` property. +* Add `bookTypes` as a list of `BookType` enum members. +* Injected `FormBuilder` into the constructor. [FormBuilder](https://angular.io/api/forms/FormBuilder) provides convenient methods for generating form controls. It reduces the amount of boilerplate needed to build complex forms. +* Added `buildForm` method to the end of the file and executed the `buildForm()` in the `createBook` method. +* Added `save` method. + +Open `/src/app/book/book.component.html` and replace ` ` with the following code part: + +```html + + +
+ * + +
+ +
+ * + +
+ +
+ * + +
+ +
+ * + +
+ + +``` + +Also replace ` ` with the following code part: + +````html + + + + + + ```` -* Since the `Name` is empty, ABP will throw an `AbpValidationException`. +### Datepicker + +We've used [NgBootstrap datepicker](https://ng-bootstrap.github.io/#/components/datepicker/overview) in this component. So, need to arrange dependencies related to this component. + +Open `/src/app/book/book.module.ts` and replace the content as below: + +```js +import { NgModule } from '@angular/core'; +import { SharedModule } from '../shared/shared.module'; +import { BookRoutingModule } from './book-routing.module'; +import { BookComponent } from './book.component'; +import { NgbDatepickerModule } from '@ng-bootstrap/ng-bootstrap'; // add this line + +@NgModule({ + declarations: [BookComponent], + imports: [ + BookRoutingModule, + SharedModule, + NgbDatepickerModule, // add this line + ] +}) +export class BookModule { } +``` + +* We imported `NgbDatepickerModule` to be able to use the date picker. + +Open `/src/app/book/book.component.ts` and replace the content as below: + +```js +import { ListService, PagedResultDto } from '@abp/ng.core'; +import { Component, OnInit } from '@angular/core'; +import { BookDto, BookType } from './models'; +import { BookService } from './services'; +import { FormGroup, FormBuilder, Validators } from '@angular/forms'; + +// added this line +import { NgbDateNativeAdapter, NgbDateAdapter } from '@ng-bootstrap/ng-bootstrap'; + +@Component({ + selector: 'app-book', + templateUrl: './book.component.html', + styleUrls: ['./book.component.scss'], + providers: [ + ListService, + { provide: NgbDateAdapter, useClass: NgbDateNativeAdapter } // add this line + ], +}) +export class BookComponent implements OnInit { + book = { items: [], totalCount: 0 } as PagedResultDto; + + booksType = BookType; + + form: FormGroup; + + // <== added bookTypeArr array ==> + bookTypes = Object.keys(BookType).filter( + (bookType) => typeof this.booksType[bookType] === 'number' + ); + + isModalOpen = false; + + constructor( + public readonly list: ListService, + private bookService: BookService, + private fb: FormBuilder + ) {} + + ngOnInit() { + const bookStreamCreator = (query) => this.bookService.getListByInput(query); + + this.list.hookToQuery(bookStreamCreator).subscribe((response) => { + this.book = response; + }); + } + + createBook() { + this.buildForm(); + this.isModalOpen = true; + } + + buildForm() { + this.form = this.fb.group({ + name: ['', Validators.required], + type: [null, Validators.required], + publishDate: [null, Validators.required], + price: [null, Validators.required], + }); + } + + save() { + if (this.form.invalid) { + return; + } + + this.bookService.createByInput(this.form.value).subscribe(() => { + this.isModalOpen = false; + this.form.reset(); + this.list.get(); + }); + } +} +``` + +* Imported ` NgbDateNativeAdapter` and `NgbDateAdapter`. +* We added a new provider `NgbDateAdapter` that converts Datepicker value to `Date` type. See the [datepicker adapters](https://ng-bootstrap.github.io/#/components/datepicker/overview) for more details. + +Now, you can open your browser to see the changes: + +![Save button to the modal](./images/bookstore-new-book-form-v2.png) + +## Updating a Book + +Open `/src/app/book/book.component.ts` and replace the content as shown below: + +```js +import { ListService, PagedResultDto } from '@abp/ng.core'; +import { Component, OnInit } from '@angular/core'; +import { BookDto, BookType, CreateUpdateBookDto } from './models'; +import { BookService } from './services'; +import { FormGroup, FormBuilder, Validators } from '@angular/forms'; +import { NgbDateNativeAdapter, NgbDateAdapter } from '@ng-bootstrap/ng-bootstrap'; + +@Component({ + selector: 'app-book', + templateUrl: './book.component.html', + styleUrls: ['./book.component.scss'], + providers: [ListService, { provide: NgbDateAdapter, useClass: NgbDateNativeAdapter }], +}) +export class BookComponent implements OnInit { + book = { items: [], totalCount: 0 } as PagedResultDto; + + booksType = BookType; + + form: FormGroup; + + selectedBook = new BookDto(); // declare selectedBook + + bookTypes = Object.keys(BookType).filter( + (bookType) => typeof this.booksType[bookType] === 'number' + ); + + isModalOpen = false; + + constructor( + public readonly list: ListService, + private bookService: BookService, + private fb: FormBuilder + ) {} + + ngOnInit() { + const bookStreamCreator = (query) => this.bookService.getListByInput(query); + + this.list.hookToQuery(bookStreamCreator).subscribe((response) => { + this.book = response; + }); + } + + createBook() { + this.selectedBook = new BookDto(); // reset the selected book + this.buildForm(); + this.isModalOpen = true; + } + + // Add editBook method + editBook(id: string) { + this.bookService.getById(id).subscribe((book) => { + this.selectedBook = book; + this.buildForm(); + this.isModalOpen = true; + }); + } + + buildForm() { + this.form = this.fb.group({ + name: [this.selectedBook.name || '', Validators.required], + type: [this.selectedBook.type || null, Validators.required], + publishDate: [ + this.selectedBook.publishDate ? new Date(this.selectedBook.publishDate) : null, + Validators.required, + ], + price: [this.selectedBook.price || null, Validators.required], + }); + } + + // change the save method + save() { + if (this.form.invalid) { + return; + } + + const request = this.selectedBook.id + ? this.bookService.updateByIdAndInput(this.form.value, this.selectedBook.id) + : this.bookService.createByInput(this.form.value); + + request.subscribe(() => { + this.isModalOpen = false; + this.form.reset(); + this.list.get(); + }); + } +} +``` + +* We declared a variable named `selectedBook` as `BookDto`. +* We added `editBook` method. This method fetches the book with the given `id` and sets it to `selectedBook` object. +* We replaced the `buildForm` method so that it creates the form with the `selectedBook` data. +* We replaced the `createBook` method so it sets `selectedBook` to an empty object. +* We changed the `save` method to handle both of create and update operations. + +### Add "Actions" Dropdown to the Table + +Open the `/src/app/book/book.component.html`  and add the following `ngx-datatable-column` definition as the first column in the `ngx-datatable`: + +```html + + +
+ +
+ +
+
+ + +``` + +Added an "Actions" dropdown as the first column of the table that is shown below: + +![Action buttons](./images/bookstore-actions-buttons.png) + +Also, change the `ng-template #abpHeader` section as shown below: + +```html + +

{%{{{ (selectedBook.id ? '::Edit' : '::NewBook' ) | abpLocalization }}}%}

+ +``` + +This template will show **Edit** text for edit record operation, **New Book** for new record operation in the title. + +## Deleting a Book + +Open the `/src/app/book/book.component.ts` and inject the `ConfirmationService`. + +Replace the constructor as below: + +```js +// ... + +// add new imports +import { ConfirmationService, Confirmation } from '@abp/ng.theme.shared'; + +//change the constructor +constructor( + public readonly list: ListService, + private bookService: BookService, + private fb: FormBuilder, + private confirmation: ConfirmationService // inject the ConfirmationService +) {} + +// Add a delete method +delete(id: string) { + this.confirmation.warn('::AreYouSureToDelete', 'AbpAccount::AreYouSure').subscribe((status) => { + if (status === Confirmation.Status.confirm) { + this.bookService.deleteById(id).subscribe(() => this.list.get()); + } + }); +} +``` + +* We imported `ConfirmationService`. +* We injected `ConfirmationService` to the constructor. +* Added a `delete` method. + +> See the [Confirmation Popup documentation](../UI/Angular/Confirmation-Service) for more about this service. + +### Add a Delete Button + + +Open `/src/app/book/book.component.html` and modify the `ngbDropdownMenu` to add the delete button as shown below: + +```html +
+ + +
+``` + +The final actions dropdown UI looks like below: + +![bookstore-final-actions-dropdown](./images/bookstore-final-actions-dropdown.png) + +Clicking the "Delete" action calls the `delete` method which then shows a confirmation popup as shown below: -Open the **Test Explorer Window** (use Test -> Windows -> Test Explorer menu if it is not visible) and **Run All** tests: +![bookstore-confirmation-popup](./images/bookstore-confirmation-popup.png) -![bookstore-appservice-tests](./images/bookstore-appservice-tests.png) +{{end}} -Congratulations, the green icons show, the tests have been successfully passed! +## The Next Part +See the [next part](part-4.md) of this tutorial. diff --git a/docs/en/Tutorials/Part-4.md b/docs/en/Tutorials/Part-4.md new file mode 100644 index 0000000000..0325f3f60a --- /dev/null +++ b/docs/en/Tutorials/Part-4.md @@ -0,0 +1,248 @@ +# Web Application Development Tutorial - Part 4: Integration Tests +````json +//[doc-params] +{ + "UI": ["MVC","NG"], + "DB": ["EF","Mongo"] +} +```` +{{ +if UI == "MVC" + UI_Text="mvc" +else if UI == "NG" + UI_Text="angular" +else + UI_Text="?" +end +if DB == "EF" + DB_Text="Entity Framework Core" +else if DB == "Mongo" + DB_Text="MongoDB" +else + DB_Text="?" +end +}} + +## About This Tutorial + +In this tutorial series, you will build an ABP based web application named `Acme.BookStore`. This application is used to manage a list of books and their authors. It is developed using the following technologies: + +* **{{DB_Text}}** as the ORM provider. +* **{{UI_Value}}** as the UI Framework. + +This tutorial is organized as the following parts; + +- [Part 1: Creating the project and book list page](Part-1.md) +- [Part 2: The book list page](Part-2.md) +- [Part 3: Creating, updating and deleting books](Part-3.md) +- **Part 4: Integration tests (this part)** +- [Part 5: Authorization](Part-5.md) + +### Download the Source Code + +This tutorials has multiple versions based on your **UI** and **Database** preferences. We've prepared two combinations of the source code to be downloaded: + +* [MVC (Razor Pages) UI with EF Core](https://github.com/abpframework/abp-samples/tree/master/BookStore-Mvc-EfCore) +* [Angular UI with MongoDB](https://github.com/abpframework/abp-samples/tree/master/BookStore-Angular-MongoDb) + +## Test Projects in the Solution + +This part covers the **server side** tests. There are several test projects in the solution: + +![bookstore-test-projects-v2](./images/bookstore-test-projects-{{UI_Text}}.png) + +Each project is used to test the related project. Test projects use the following libraries for testing: + +* [Xunit](https://xunit.github.io/) as the main test framework. +* [Shoudly](http://shouldly.readthedocs.io/en/latest/) as the assertion library. +* [NSubstitute](http://nsubstitute.github.io/) as the mocking library. + +{{if DB=="EF"}} + +> The test projects are configured to use **SQLite in-memory** as the database. A separate database instance is created and seeded (with the data seed system) to prepare a fresh database for every test. + +{{else if DB=="Mongo"}} + +> **[Mongo2Go](https://github.com/Mongo2Go/Mongo2Go)** library is used to mock the MongoDB database. A separate database instance is created and seeded (with the data seed system) to prepare a fresh database for every test. + +{{end}} + +## Adding Test Data + +If you had created a data seed contributor as described in the [first part](Part-1.md), the same data will be available in your tests. So, you can skip this section. If you haven't created the seed contributor, you can use the `BookStoreTestDataSeedContributor` to seed the same data to be used in the tests below. + +## Testing the BookAppService + +Create a test class named `BookAppService_Tests` in the `Acme.BookStore.Application.Tests` project: + +````csharp +using System.Threading.Tasks; +using Shouldly; +using Volo.Abp.Application.Dtos; +using Xunit; + +namespace Acme.BookStore.Books +{ + public class BookAppService_Tests : BookStoreApplicationTestBase + { + private readonly IBookAppService _bookAppService; + + public BookAppService_Tests() + { + _bookAppService = GetRequiredService(); + } + + [Fact] + public async Task Should_Get_List_Of_Books() + { + //Act + var result = await _bookAppService.GetListAsync( + new PagedAndSortedResultRequestDto() + ); + + //Assert + result.TotalCount.ShouldBeGreaterThan(0); + result.Items.ShouldContain(b => b.Name == "1984"); + } + } +} +```` + +* `Should_Get_List_Of_Books` test simply uses `BookAppService.GetListAsync` method to get and check the list of books. +* We can safely check the book "1984" by its name, because we know that this books is available in the database since we've added it in the seed data. + +Add a new test method to the `BookAppService_Tests` class that creates a new **valid** book: + +````csharp +[Fact] +public async Task Should_Create_A_Valid_Book() +{ + //Act + var result = await _bookAppService.CreateAsync( + new CreateUpdateBookDto + { + Name = "New test book 42", + Price = 10, + PublishDate = System.DateTime.Now, + Type = BookType.ScienceFiction + } + ); + + //Assert + result.Id.ShouldNotBe(Guid.Empty); + result.Name.ShouldBe("New test book 42"); +} +```` + +Add a new test that tries to create an invalid book and fails: + +````csharp +[Fact] +public async Task Should_Not_Create_A_Book_Without_Name() +{ + var exception = await Assert.ThrowsAsync(async () => + { + await _bookAppService.CreateAsync( + new CreateUpdateBookDto + { + Name = "", + Price = 10, + PublishDate = DateTime.Now, + Type = BookType.ScienceFiction + } + ); + }); + + exception.ValidationErrors + .ShouldContain(err => err.MemberNames.Any(mem => mem == "Name")); +} +```` + +* Since the `Name` is empty, ABP will throw an `AbpValidationException`. + +The final test class should be as shown below: + +````csharp +using System; +using System.Linq; +using System.Threading.Tasks; +using Shouldly; +using Volo.Abp.Application.Dtos; +using Volo.Abp.Validation; +using Xunit; + +namespace Acme.BookStore.Books +{ + public class BookAppService_Tests : BookStoreApplicationTestBase + { + private readonly IBookAppService _bookAppService; + + public BookAppService_Tests() + { + _bookAppService = GetRequiredService(); + } + + [Fact] + public async Task Should_Get_List_Of_Books() + { + //Act + var result = await _bookAppService.GetListAsync( + new PagedAndSortedResultRequestDto() + ); + + //Assert + result.TotalCount.ShouldBeGreaterThan(0); + result.Items.ShouldContain(b => b.Name == "1984"); + } + + [Fact] + public async Task Should_Create_A_Valid_Book() + { + //Act + var result = await _bookAppService.CreateAsync( + new CreateUpdateBookDto + { + Name = "New test book 42", + Price = 10, + PublishDate = System.DateTime.Now, + Type = BookType.ScienceFiction + } + ); + + //Assert + result.Id.ShouldNotBe(Guid.Empty); + result.Name.ShouldBe("New test book 42"); + } + + [Fact] + public async Task Should_Not_Create_A_Book_Without_Name() + { + var exception = await Assert.ThrowsAsync(async () => + { + await _bookAppService.CreateAsync( + new CreateUpdateBookDto + { + Name = "", + Price = 10, + PublishDate = DateTime.Now, + Type = BookType.ScienceFiction + } + ); + }); + + exception.ValidationErrors + .ShouldContain(err => err.MemberNames.Any(mem => mem == "Name")); + } + } +} +```` + +Open the **Test Explorer Window** (use Test -> Windows -> Test Explorer menu if it is not visible) and **Run All** tests: + +![bookstore-appservice-tests](./images/bookstore-appservice-tests.png) + +Congratulations, the **green icons** indicates that the tests have been successfully passed! + +## The Next Part + +See the [next part](part-5.md) of this tutorial. \ No newline at end of file diff --git a/docs/en/Tutorials/Part-5.md b/docs/en/Tutorials/Part-5.md new file mode 100644 index 0000000000..441db14638 --- /dev/null +++ b/docs/en/Tutorials/Part-5.md @@ -0,0 +1,401 @@ +# Web Application Development Tutorial - Part 5: Authorization +````json +//[doc-params] +{ + "UI": ["MVC","NG"], + "DB": ["EF","Mongo"] +} +```` +{{ +if UI == "MVC" + UI_Text="mvc" +else if UI == "NG" + UI_Text="angular" +else + UI_Text="?" +end +if DB == "EF" + DB_Text="Entity Framework Core" +else if DB == "Mongo" + DB_Text="MongoDB" +else + DB_Text="?" +end +}} + +## About This Tutorial + +In this tutorial series, you will build an ABP based web application named `Acme.BookStore`. This application is used to manage a list of books and their authors. It is developed using the following technologies: + +* **{{DB_Text}}** as the ORM provider. +* **{{UI_Value}}** as the UI Framework. + +This tutorial is organized as the following parts; + +- [Part 1: Creating the project and book list page](Part-1.md) +- [Part 2: The book list page](Part-2.md) +- [Part 3: Creating, updating and deleting books](Part-3.md) +- [Part 4: Integration tests](Part-4.md) +- **Part 5: Authorization (this part)** + +### Download the Source Code + +This tutorials has multiple versions based on your **UI** and **Database** preferences. We've prepared two combinations of the source code to be downloaded: + +* [MVC (Razor Pages) UI with EF Core](https://github.com/abpframework/abp-samples/tree/master/BookStore-Mvc-EfCore) +* [Angular UI with MongoDB](https://github.com/abpframework/abp-samples/tree/master/BookStore-Angular-MongoDb) + +## Permissions + +ABP Framework provides an [authorization system](../Authorization.md) based on the ASP.NET Core's [authorization infrastructure](https://docs.microsoft.com/en-us/aspnet/core/security/authorization/introduction). One major feature added on top of the standard authorization infrastructure is the **permission system** which allows to define permissions and enable/disable per role, user or client. + +### Permission Names + +A permission must have a unique name (a `string`). The best way is to define it as a `const`, so we can reuse the permission name. + +Open the `BookStorePermissions` class inside the `Acme.BookStore.Application.Contracts` project and change the content as shown below: + +````csharp +namespace Acme.BookStore.Permissions +{ + public static class BookStorePermissions + { + public const string GroupName = "BookStore"; + + public static class Books + { + public const string Default = GroupName + ".Books"; + public const string Create = Default + ".Create"; + public const string Edit = Default + ".Edit"; + public const string Delete = Default + ".Delete"; + } + } +} +```` + +This is a hierarchical way of defining permission names. For example, "create book" permission name was defined as `BookStore.Books.Create`. + +### Permission Definitions + +You should define permissions before using them. + +Open the `BookStorePermissionDefinitionProvider` class inside the `Acme.BookStore.Application.Contracts` project and change the content as shown below: + +````csharp +using Acme.BookStore.Localization; +using Volo.Abp.Authorization.Permissions; +using Volo.Abp.Localization; + +namespace Acme.BookStore.Permissions +{ + public class BookStorePermissionDefinitionProvider : PermissionDefinitionProvider + { + public override void Define(IPermissionDefinitionContext context) + { + var bookStoreGroup = context.AddGroup(BookStorePermissions.GroupName, L("Permission:BookStore")); + + var booksPermission = bookStoreGroup.AddPermission(BookStorePermissions.Books.Default, L("Permission:Books")); + booksPermission.AddChild(BookStorePermissions.Books.Create, L("Permission:Books.Create")); + booksPermission.AddChild(BookStorePermissions.Books.Edit, L("Permission:Books.Edit")); + booksPermission.AddChild(BookStorePermissions.Books.Delete, L("Permission:Books.Delete")); + } + + private static LocalizableString L(string name) + { + return LocalizableString.Create(name); + } + } +} +```` + +This class defines a **permission group** (to group permissions on the UI, will be seen below) and **4 permissions** inside this group. Also, **Create**, **Edit** and **Delete** are children of the `BookStorePermissions.Books.Default` permission. A child permission can be selected **only if the parent was selected**. + +Finally, edit the localization file (`en.json` under the `Localization/BookStore` folder of the `Acme.BookStore.Domain.Shared` project) to define the localization keys used above: + +````json +"Permission:BookStore": "Book Store", +"Permission:Books": "Book Management", +"Permission:Books.Create": "Creating new books", +"Permission:Books.Edit": "Editing the books", +"Permission:Books.Delete": "Deleting the books" +```` + +> Localization key names are arbitrary and no forcing rule. But we prefer the convention used above. + +### Permission Management UI + +Once you define the permissions, you can see them on the **permission management modal**. + +Go to the *Administration -> Identity -> Roles* page, select *Permissions* action for the admin role to open the permission management modal: + +![bookstore-permissions-ui](images/bookstore-permissions-ui.png) + +Grant the permissions you want and save the modal. + +## Authorization + +Now, you can use the permissions to authorize the book management. + +### Application Layer & HTTP API + +Open the `BookAppService` class and add set the policy names as the permission names defined above: + +````csharp +using System; +using Acme.BookStore.Permissions; +using Volo.Abp.Application.Dtos; +using Volo.Abp.Application.Services; +using Volo.Abp.Domain.Repositories; + +namespace Acme.BookStore.Books +{ + public class BookAppService : + CrudAppService< + Book, //The Book entity + BookDto, //Used to show books + Guid, //Primary key of the book entity + PagedAndSortedResultRequestDto, //Used for paging/sorting + CreateUpdateBookDto>, //Used to create/update a book + IBookAppService //implement the IBookAppService + { + public BookAppService(IRepository repository) + : base(repository) + { + GetPolicyName = BookStorePermissions.Books.Default; + GetListPolicyName = BookStorePermissions.Books.Default; + CreatePolicyName = BookStorePermissions.Books.Create; + UpdatePolicyName = BookStorePermissions.Books.Edit; + DeletePolicyName = BookStorePermissions.Books.Delete; + } + } +} +```` + +Added code to the constructor. Base `CrudAppService` automatically uses these permissions on the CRUD operations. This makes the **application service** secure, but also makes the **HTTP API** secure since this service is automatically used as an HTTP API as explained before (see [auto API controllers](../API/Auto-API-Controllers.md)). + +{{if UI == "MVC"}} + +### Razor Page + +While securing the HTTP API & the application service prevents unauthorized users to use the services, they can still navigate to the book management page. While they will get authorization exception when the page makes the first AJAX call to the server, we should also authorize the page for a better user experience and security. + +Open the `BookStoreWebModule` and add the following code block inside the `ConfigureServices` method: + +````csharp +Configure(options => +{ + options.Conventions.AuthorizePage("/Books/Index", BookStorePermissions.Books.Default); + options.Conventions.AuthorizePage("/Books/CreateModal", BookStorePermissions.Books.Create); + options.Conventions.AuthorizePage("/Books/EditModal", BookStorePermissions.Books.Edit); +}); +```` + +Now, unauthorized users are redirected to the **login page**. + +#### Hide the New Book Button + +The book management page has a *New Book* button that should be invisible if the current user has no *Book Creation* permission. + +![bookstore-new-book-button-small](images/bookstore-new-book-button-small.png) + +Open the `Pages/Books/Index.cshtml` file and change the content as shown below: + +````html +@page +@using Acme.BookStore.Localization +@using Acme.BookStore.Permissions +@using Acme.BookStore.Web.Pages.Books +@using Microsoft.AspNetCore.Authorization +@using Microsoft.Extensions.Localization +@model IndexModel +@inject IStringLocalizer L +@inject IAuthorizationService AuthorizationService +@section scripts +{ + +} + + + + + + @L["Books"] + + + @if (await AuthorizationService.IsGrantedAsync(BookStorePermissions.Books.Create)) + { + + } + + + + + + + +```` + +* Added `@inject IAuthorizationService AuthorizationService` to access to the authorization service. +* Used `@if (await AuthorizationService.IsGrantedAsync(BookStorePermissions.Books.Create))` to check the book creation permission to conditionally render the *New Book* button. + +### JavaScript Side + +Books table in the book management page has an actions button for each row. The actions button includes *Edit* and *Delete* actions: + +![bookstore-edit-delete-actions](images/bookstore-edit-delete-actions.png) + +We should hide an action if the current user has not granted for the related permission. Datatables row actions has a `visible` option that can be set to `false` to hide the action item. + +Open the `Pages/Books/Index.js` inside the `Acme.BookStore.Web` project and add a `visible` option to the `Edit` action as shown below: + +````js +{ + text: l('Edit'), + visible: abp.auth.isGranted('BookStore.Books.Edit'), //CHECK for the PERMISSION + action: function (data) { + editModal.open({ id: data.record.id }); + } +} +```` + +Do same for the `Delete` action: + +````js +visible: abp.auth.isGranted('BookStore.Books.Delete') +```` + +* `abp.auth.isGranted(...)` is used to check a permission that is defined before. +* `visible` could also be get a function that returns a `bool` if the value will be calculated later, based on some conditions. + +### Menu Item + +Even we have secured all the layers of the book management page, it is still visible on the main menu of the application. We should hide the menu item if the current user has no permission. + +Open the `BookStoreMenuContributor` class, find the code block below: + +````csharp +context.Menu.AddItem( + new ApplicationMenuItem( + "BooksStore", + l["Menu:BookStore"], + icon: "fa fa-book" + ).AddItem( + new ApplicationMenuItem( + "BooksStore.Books", + l["Menu:Books"], + url: "/Books" + ) + ) +); +```` + +And replace this code block with the following: + +````csharp +var bookStoreMenu = new ApplicationMenuItem( + "BooksStore", + l["Menu:BookStore"], + icon: "fa fa-book" +); + +context.Menu.AddItem(bookStoreMenu); + +//CHECK the PERMISSION +if (await context.IsGrantedAsync(BookStorePermissions.Books.Default)) +{ + bookStoreMenu.AddItem(new ApplicationMenuItem( + "BooksStore.Books", + l["Menu:Books"], + url: "/Books" + )); +} +```` + +{{else if UI == "NG"}} + +### Angular Guard Configuration + +First step of the UI is to prevent unauthorized users to see the "Books" menu item and enter to the book management page. + +Open the `/src/app/book/book-routing.module.ts` and replace with the following content: + +````js +import { NgModule } from '@angular/core'; +import { Routes, RouterModule } from '@angular/router'; +import { AuthGuard, PermissionGuard } from '@abp/ng.core'; +import { BookComponent } from './book.component'; + +const routes: Routes = [ + { path: '', component: BookComponent, canActivate: [AuthGuard, PermissionGuard] }, +]; + +@NgModule({ + imports: [RouterModule.forChild(routes)], + exports: [RouterModule], +}) +export class BookRoutingModule {} +```` + +* Imported `AuthGuard` and `PermissionGuard` from the `@abp/ng.core`. +* Added `canActivate: [AuthGuard, PermissionGuard]` to the route definition. + +Open the `/src/app/route.provider.ts` and add `requiredPolicy: 'BookStore.Books'` to the `/books` route. The `/books` route block should be following: + +````js +{ + path: '/books', + name: '::Menu:Books', + parentName: '::Menu:BookStore', + layout: eLayoutType.application, + requiredPolicy: 'BookStore.Books', +} +```` + +### Hide the New Book Button + +The book management page has a *New Book* button that should be invisible if the current user has no *Book Creation* permission. + +![bookstore-new-book-button-small](images/bookstore-new-book-button-small.png) + +Open the `/src/app/book/book.component.html` file and replace the create button HTML content as shown below: + +````html + + +```` + +* Just added `abpPermission="BookStore.Books.Create"` that hides the button if the current user has no permission. + +### Hide the Edit and Delete Actions + +Books table in the book management page has an actions button for each row. The actions button includes *Edit* and *Delete* actions: + +![bookstore-edit-delete-actions](images/bookstore-edit-delete-actions.png) + +We should hide an action if the current user has not granted for the related permission. + +Open the `/src/app/book/book.component.html` file and replace the edit and delete buttons contents as shown below: + +````html + + + + + +```` + +* Added `abpPermission="BookStore.Books.Edit"` that hides the edit action if the current user has no editing permission. +* Added `abpPermission="BookStore.Books.Delete"` that hides the delete action if the current user has no delete permission. + +{{end}} + diff --git a/docs/en/Tutorials/images/bookstore-book-and-booktype.png b/docs/en/Tutorials/images/bookstore-book-and-booktype.png new file mode 100644 index 0000000000..1620ebf150 Binary files /dev/null and b/docs/en/Tutorials/images/bookstore-book-and-booktype.png differ diff --git a/docs/en/Tutorials/images/bookstore-book-list-3.png b/docs/en/Tutorials/images/bookstore-book-list-3.png new file mode 100644 index 0000000000..cbd7ec4a6a Binary files /dev/null and b/docs/en/Tutorials/images/bookstore-book-list-3.png differ diff --git a/docs/en/Tutorials/images/bookstore-book-list.png b/docs/en/Tutorials/images/bookstore-book-list.png index ecdb87c737..4982032e64 100644 Binary files a/docs/en/Tutorials/images/bookstore-book-list.png and b/docs/en/Tutorials/images/bookstore-book-list.png differ diff --git a/docs/en/Tutorials/images/bookstore-dbmigrator-on-solution.png b/docs/en/Tutorials/images/bookstore-dbmigrator-on-solution.png new file mode 100644 index 0000000000..0b81900307 Binary files /dev/null and b/docs/en/Tutorials/images/bookstore-dbmigrator-on-solution.png differ diff --git a/docs/en/Tutorials/images/bookstore-edit-button-2.png b/docs/en/Tutorials/images/bookstore-edit-button-2.png new file mode 100644 index 0000000000..507bdd9406 Binary files /dev/null and b/docs/en/Tutorials/images/bookstore-edit-button-2.png differ diff --git a/docs/en/Tutorials/images/bookstore-edit-delete-actions.png b/docs/en/Tutorials/images/bookstore-edit-delete-actions.png new file mode 100644 index 0000000000..9c275c6d15 Binary files /dev/null and b/docs/en/Tutorials/images/bookstore-edit-delete-actions.png differ diff --git a/docs/en/Tutorials/images/bookstore-getlist-result-network.png b/docs/en/Tutorials/images/bookstore-getlist-result-network.png new file mode 100644 index 0000000000..141f9d14ee Binary files /dev/null and b/docs/en/Tutorials/images/bookstore-getlist-result-network.png differ diff --git a/docs/en/Tutorials/images/bookstore-index-js-file-v3.png b/docs/en/Tutorials/images/bookstore-index-js-file-v3.png new file mode 100644 index 0000000000..add95788a8 Binary files /dev/null and b/docs/en/Tutorials/images/bookstore-index-js-file-v3.png differ diff --git a/docs/en/Tutorials/images/bookstore-javascript-proxy-console.png b/docs/en/Tutorials/images/bookstore-javascript-proxy-console.png new file mode 100644 index 0000000000..f393c47875 Binary files /dev/null and b/docs/en/Tutorials/images/bookstore-javascript-proxy-console.png differ diff --git a/docs/en/Tutorials/images/bookstore-new-book-button-2.png b/docs/en/Tutorials/images/bookstore-new-book-button-2.png new file mode 100644 index 0000000000..12f1819688 Binary files /dev/null and b/docs/en/Tutorials/images/bookstore-new-book-button-2.png differ diff --git a/docs/en/Tutorials/images/bookstore-new-book-button-small.png b/docs/en/Tutorials/images/bookstore-new-book-button-small.png new file mode 100644 index 0000000000..13f7da9285 Binary files /dev/null and b/docs/en/Tutorials/images/bookstore-new-book-button-small.png differ diff --git a/docs/en/Tutorials/images/bookstore-permissions-ui.png b/docs/en/Tutorials/images/bookstore-permissions-ui.png new file mode 100644 index 0000000000..749f7a013f Binary files /dev/null and b/docs/en/Tutorials/images/bookstore-permissions-ui.png differ diff --git a/docs/en/Tutorials/images/generated-proxies-2.png b/docs/en/Tutorials/images/generated-proxies-2.png new file mode 100644 index 0000000000..adad417c3d Binary files /dev/null and b/docs/en/Tutorials/images/generated-proxies-2.png differ diff --git a/docs/en/docs-nav.json b/docs/en/docs-nav.json index b691ea9b07..239f071619 100644 --- a/docs/en/docs-nav.json +++ b/docs/en/docs-nav.json @@ -26,19 +26,27 @@ "text": "Tutorials", "items": [ { - "text": "Application Development", + "text": "Web Application Development", "items": [ { - "text": "Part-1: Creating a new solution and listing items", + "text": "1: Creating the Server Side", "path": "Tutorials/Part-1.md" }, { - "text": "Part-2: CRUD operations", + "text": "2: The Book List Page", "path": "Tutorials/Part-2.md" }, { - "text": "Part-3: Integration tests", + "text": "3: Creating, Updating and Deleting Books", "path": "Tutorials/Part-3.md" + }, + { + "text": "4: Integration Tests", + "path": "Tutorials/Part-4.md" + }, + { + "text": "5: Authorization", + "path": "Tutorials/Part-5.md" } ] }