abpframework · maliming · Dec 2, 2024 · Oct 17, 2024 · Oct 17, 2024 · Nov 25, 2024
diff --git a/docs/en/docs-nav.json b/docs/en/docs-nav.json
@@ -115,6 +115,35 @@
             }
           ]
         },
+        {
+          "text": "Book Store Application (with ABP Suite)",
+          "items": [
+            {
+              "text": "Overview",
+              "path": "tutorials/book-store-with-abp-suite"
+            },
+            {
+              "text": "1: Creating the Solution",
+              "path": "tutorials/book-store-with-abp-suite/part-01.md"
+            },
+            {
+              "text": "2: Creating the Books",
+              "path": "tutorials/book-store-with-abp-suite/part-02.md"
+            },
+            {
+              "text": "3: Creating the Authors",
+              "path": "tutorials/book-store-with-abp-suite/part-03.md"
+            },
+            {
+              "text": "4: Book to Author Relation",
+              "path": "tutorials/book-store-with-abp-suite/part-04.md"
+            },
+            {
+              "text": "5: Customizing the Generated Code",
+              "path": "tutorials/book-store-with-abp-suite/part-05.md"
+            }               
+          ]
+        },        
         {
           "text": "Modular Monolith Application",
           "items": [

diff --git a/docs/en/tutorials/book-store-with-abp-suite/images/abp-suite-generated-tests.png b/docs/en/tutorials/book-store-with-abp-suite/images/abp-suite-generated-tests.png
diff --git a/...en/tutorials/book-store-with-abp-suite/images/abp-suite-navigation-property.png b/...en/tutorials/book-store-with-abp-suite/images/abp-suite-navigation-property.png
diff --git a/docs/en/tutorials/book-store-with-abp-suite/images/abp-suite-opening.png b/docs/en/tutorials/book-store-with-abp-suite/images/abp-suite-opening.png
diff --git a/...tutorials/book-store-with-abp-suite/images/abp-suite-solution-test-projects.png b/...tutorials/book-store-with-abp-suite/images/abp-suite-solution-test-projects.png
diff --git a/...torials/book-store-with-abp-suite/images/book-store-suite-solution-explorer.png b/...torials/book-store-with-abp-suite/images/book-store-suite-solution-explorer.png
diff --git a/docs/en/tutorials/book-store-with-abp-suite/images/bookstore-test-succeed.png b/docs/en/tutorials/book-store-with-abp-suite/images/bookstore-test-succeed.png
diff --git a/docs/en/tutorials/book-store-with-abp-suite/images/studio-browser-suite.png b/docs/en/tutorials/book-store-with-abp-suite/images/studio-browser-suite.png
diff --git a/docs/en/tutorials/book-store-with-abp-suite/images/suite-author-entity-1.png b/docs/en/tutorials/book-store-with-abp-suite/images/suite-author-entity-1.png
diff --git a/docs/en/tutorials/book-store-with-abp-suite/images/suite-author-entity-2.png b/docs/en/tutorials/book-store-with-abp-suite/images/suite-author-entity-2.png
diff --git a/docs/en/tutorials/book-store-with-abp-suite/images/suite-author-new-entity.png b/docs/en/tutorials/book-store-with-abp-suite/images/suite-author-new-entity.png
diff --git a/docs/en/tutorials/book-store-with-abp-suite/images/suite-author-pages-1.png b/docs/en/tutorials/book-store-with-abp-suite/images/suite-author-pages-1.png
diff --git a/docs/en/tutorials/book-store-with-abp-suite/images/suite-book-entity-1.png b/docs/en/tutorials/book-store-with-abp-suite/images/suite-book-entity-1.png
diff --git a/docs/en/tutorials/book-store-with-abp-suite/images/suite-book-entity-2.png b/docs/en/tutorials/book-store-with-abp-suite/images/suite-book-entity-2.png
diff --git a/docs/en/tutorials/book-store-with-abp-suite/images/suite-book-entity-3.png b/docs/en/tutorials/book-store-with-abp-suite/images/suite-book-entity-3.png
diff --git a/docs/en/tutorials/book-store-with-abp-suite/images/suite-book-entity-4.png b/docs/en/tutorials/book-store-with-abp-suite/images/suite-book-entity-4.png
diff --git a/docs/en/tutorials/book-store-with-abp-suite/images/suite-book-entity-5.png b/docs/en/tutorials/book-store-with-abp-suite/images/suite-book-entity-5.png
diff --git a/docs/en/tutorials/book-store-with-abp-suite/images/suite-book-entity-6.png b/docs/en/tutorials/book-store-with-abp-suite/images/suite-book-entity-6.png
diff --git a/docs/en/tutorials/book-store-with-abp-suite/images/suite-book-entity-selection.png b/docs/en/tutorials/book-store-with-abp-suite/images/suite-book-entity-selection.png
diff --git a/docs/en/tutorials/book-store-with-abp-suite/images/suite-book-pages-1.png b/docs/en/tutorials/book-store-with-abp-suite/images/suite-book-pages-1.png
diff --git a/...orials/book-store-with-abp-suite/images/suite-book-with-author-create-modal.png b/...orials/book-store-with-abp-suite/images/suite-book-with-author-create-modal.png
diff --git a/...ls/book-store-with-abp-suite/images/suite-bookstore-advanced-filter-section.png b/...ls/book-store-with-abp-suite/images/suite-bookstore-advanced-filter-section.png
diff --git a/docs/en/tutorials/book-store-with-abp-suite/images/suite-custom-code-result.png b/docs/en/tutorials/book-store-with-abp-suite/images/suite-custom-code-result.png
diff --git a/docs/en/tutorials/book-store-with-abp-suite/images/suite-enabling-custom-code.png b/docs/en/tutorials/book-store-with-abp-suite/images/suite-enabling-custom-code.png
diff --git a/...en/tutorials/book-store-with-abp-suite/images/suite-end-of-generation-modal.png b/...en/tutorials/book-store-with-abp-suite/images/suite-end-of-generation-modal.png
diff --git a/.../en/tutorials/book-store-with-abp-suite/images/suite-repository-custom-code.png b/.../en/tutorials/book-store-with-abp-suite/images/suite-repository-custom-code.png
diff --git a/docs/en/tutorials/book-store-with-abp-suite/images/test-data-seed-contributors.png b/docs/en/tutorials/book-store-with-abp-suite/images/test-data-seed-contributors.png
diff --git a/docs/en/tutorials/book-store-with-abp-suite/index.md b/docs/en/tutorials/book-store-with-abp-suite/index.md
@@ -0,0 +1,40 @@
+# Web Application Development (with ABP Suite) Tutorial
+````json
+//[doc-params]
+{
+    "UI": ["MVC"],
+    "DB": ["EF"]
+}
+````
+````json
+//[doc-nav]
+{
+  "Next": {
+    "Name": "Creating the Solution",
+    "Path": "tutorials/book-store-with-abp-suite/part-01"
+  }
+}
+````
+
+> This tutorial is suitable for those who have an ABP Team or a higher [license](https://abp.io/pricing).
+
+## About This Tutorial
+
+> In this tutorial, you will use the [ABP Suite](../../suite/index.md) to generate everything you need to build the **BookStore** application, such as [*Entities*](../../framework/architecture/domain-driven-design/entities.md), [*Domain Services*](../../framework/architecture/domain-driven-design/domain-services.md), [*Application Services*](../../framework/architecture/domain-driven-design/application-services.md), *CRUD pages* and more... 
+
+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_Value}}** as the database provider.
+* **{{UI_Value}}** as the UI Framework.
+
+This tutorial is organized as the following parts:
+
+- [Part 1: Creating the Solution](part-01.md)
+- [Part 2: Creating the Books](part-02.md)
+- [Part 3: Creating the Authors](part-03.md)
+- [Part 4: Book to Author Relation](part-04.md)
+- [Part 5: Customizing the Generated Code](part-05.md)
+
+### Download the Source Code
+
+After logging in to the ABP website, you can download the source code from [here](https://abp.io/api/download/samples/suite-bookstore-mvc-ef).
diff --git a/docs/en/tutorials/book-store-with-abp-suite/part-01.md b/docs/en/tutorials/book-store-with-abp-suite/part-01.md
@@ -0,0 +1,39 @@
+# Web Application Development (with ABP Suite) Tutorial - Part 1: Creating the Solution
+````json
+//[doc-params]
+{
+    "UI": ["MVC"],
+    "DB": ["EF"]
+}
+````
+````json
+//[doc-nav]
+{
+  "Next": {
+    "Name": "Creating the Books",
+    "Path": "tutorials/book-store-with-abp-suite/part-02"
+  }
+}
+````
+
+Before starting the development, create a new solution named `Acme.BookStore` and run it by following the [getting started tutorial](../../get-started/layered-web-application.md).
+
+You can use the following configurations:
+
+* **Solution Name:** `Acme.BookStore`
+* **UI Framework:** {{if UI=="MVC}} ASP.NET Core MVC / Razor Pages {{end}}
+* **UI Theme:** LeptonX
+* **Mobile Framework:** None
+* **Database Provider:** {{if DB=="EF"}} Entity Framework Core {{end}}
+
+You can select the other options based on your preference.
+
+> **Please complete the [Get Started](../../get-started/layered-web-application.md) guide and run the web application before going further.**
+
+The initial solution structure should be like the following in the ABP Studio's [Solution Explorer](../../studio/solution-explorer.md):
+
+![](./images/book-store-suite-solution-explorer.png)
+
+## Summary
+
+We've created the initial layered monolith solution. In the next part, we will learn how to create entities, and generate CRUD pages based on the specified options (including tests, UI, customizable code support etc.) with [ABP Suite](../../suite/index.md).
diff --git a/docs/en/tutorials/book-store-with-abp-suite/part-02.md b/docs/en/tutorials/book-store-with-abp-suite/part-02.md
@@ -0,0 +1,123 @@
+# Web Application Development (with ABP Suite) Tutorial - Part 2: Creating the Books
+````json
+//[doc-params]
+{
+    "UI": ["MVC"],
+    "DB": ["EF"]
+}
+````
+````json
+//[doc-nav]
+{
+  "Previous": {
+    "Name": "Creating the Solution",
+    "Path": "tutorials/book-store-with-abp-suite/part-01"
+  },
+  "Next": {
+    "Name": "Creating the Authors",
+    "Path": "tutorials/book-store-with-abp-suite/part-03"
+  }
+}
+````
+
+In this part, you will create a new entity named `Book` and generate CRUD pages for the related entities with everything that you would normally implement manually (including application services, tests, CRUD pages, database relations and more...) via [ABP Suite](../../suite/index.md) with few clicks.
+
+## Opening the ABP Suite
+
+> Please **stop the application** in ABP Studio's *Solution Runner* panel, if it's currently running, because ABP Suite will make changes in the solution and it might need to build the solution in some steps and running the solution prevents to build it.
+
+After creating the solution in the previous part, now you can open the ABP Suite and start generating CRUD pages. You can select the *ABP Suite -> Open* command on the main menu to open ABP Suite:
+
+![opening the ABP Suite](./images/abp-suite-opening.png)
+
+After clicking the related command, pre-integrated browser of ABP Studio should open, then you can start generating entities and all related codes with a few configurations:
+
+![](./images/studio-browser-suite.png)
+
+## Creating the Book Entity
+
+Let's create a `Book` entity with some properties. First, type `Book` for the *Name* field and leave the other options as is. ABP Suite automatically calculates proper values for the rest of the inputs for you:
+
+![](./images/suite-book-entity-1.png)
+
+ABP Suite sets:
+
+* Entity type as **master** (ABP Suite allows you to establish [master-child relationship](../../suite/creating-master-detail-relationship.md)),
+* Base class as **FullAuditedAggregateRoot** ([see other possible values](../../framework/architecture/domain-driven-design/entities.md)),
+* Primary key type as **Guid**,
+* Plural name, database name, namespace, page title, menu item and more...
+
+You can change the menu-item value as **book** to show a proper icon in the generated UI, and also enable **code customization**, **creating unit & integration tests**, and other options as you wish:
+
+![](./images/suite-book-entity-2.png)
+
+After, specifying the entity metadata, open the *Properties* tab and create the properties shown in the following figure:
+
+![](./images/suite-book-entity-3.png)
+
+Here the details:
+
+* `Name` is **required**, it's a **string** property and maximum length is **128**.
+* `Type` is an **enum** and the enum file path is *\Acme.BookStore.Domain.Shared\Books\BookType.cs* (we will create the file, in the next section).
+* `PublishDate` is a **DateTime** property and **not nullable**.
+* `Price` is a **float** property and **required**.
+
+You can leave the other configurations as default.
+
+> ABP Suite allows you to define properties with a great range of options, for example, you can specify the property type as *string*, *int*, *float*, *Guid*, *DateTime*, and even *File* (for file upload) and also you can set any options while defining your properties, such as specifying it as *required*, or *nullable*, setting *max-min length*, *default value* and more...
+
+While defining the properties, you defined a *Type* property with the type of *enum*. ABP Suite asks for an enum path to read the enum file, and set the namespace, and enum name in the generated code. 
+
+For that purpose, you should create a `BookType` enum in the `Acme.BookStore.Domain.Shared` project under the **Books** folder as follows:
+
+```csharp
+namespace Acme.BookStore.Books;
+
+public enum BookType
+{
+    Undefined,
+    Adventure,
+    Biography,
+    Dystopia,
+    Fantastic,
+    Horror,
+    Science,
+    ScienceFiction,
+    Poetry
+}
+```
+
+Then, you can specify the enum path for the `Type` property in ABP Suite like in the following figure:
+
+![](./images/suite-book-entity-4.png)
+
+> After you select the enum file, ABP Suite automatically sets the namespace and enum name, and lists your enum values in the next section. You can change these values, but for now, you can leave as is.
+
+After that, you can click the **Save and Generate** button to start the code generation process:
+
+![](./images/suite-book-entity-5.png)
+
+ABP Suite will generate the necessary code for you. It generates:
+
+* `Book` entity (also `BookBase` class, which is allow you customizing the generated entity),
+* Repository implementation (`EfCoreBookRepository` class),
+* `BookManager` domain service,
+* Input & Output **DTOs** and **application service** implementations (`IBookAppService` & `BookAppService`),
+* **Unit & integration tests**,
+* A new **migration** (and also applies to the database),
+* All related **permission**, **object mapping** and **navigation menu item** configurations,
+* and all required **UI components and pages**.
+
+It will take some time to complete the process. After the process is completed, you will see a success message, you can click the *Ok* button, and build & start the application by clicking the *Run -> Build & Start* button in the *Solution Runner* panel:
+
+![](./images/suite-book-entity-6.png)
+
+After the application is started, you can right-click and *Browse* on the application to open it in the ABP Studio's pre-integrated browser. You can see the Books page in the following figure with a single record:
+
+![](./images/suite-book-pages-1.png)
+
+On this page, you can create a new book, update an existing book, delete a book, export all records (or the filtered records) to excel, filter the records by using the advanced filter section, bulk delete multiple records and so on.
+
+## Summary
+
+In this part, you've created a new entity named `Book` and generated the necessary code for it with [ABP Suite](../../suite/index.md) with a few clicks. ABP Suite generated the all code for you, including the **entity**, **application service**, **database relations**, **unit & integration tests**, **UI** and **defined the custom hooks for code customization**.
diff --git a/docs/en/tutorials/book-store-with-abp-suite/part-03.md b/docs/en/tutorials/book-store-with-abp-suite/part-03.md
@@ -0,0 +1,79 @@
+# Web Application Development (with ABP Suite) Tutorial - Part 3: Creating the Authors
+````json
+//[doc-params]
+{
+    "UI": ["MVC"],
+    "DB": ["EF"]
+}
+````
+````json
+//[doc-nav]
+{
+  "Previous": {
+    "Name": "Creating the Books",
+    "Path": "tutorials/book-store-with-abp-suite/part-02"
+  },
+  "Next": {
+    "Name": "Book to Author Relation",
+    "Path": "tutorials/book-store-with-abp-suite/part-04"
+  }
+}
+````
+
+In the previous part, you have created the `Book` entity and in this part, you will create a new entity named `Author` and generate all necesssary code via [ABP Suite](../../suite/index.md) with few clicks. After creating the `Author` entity, you will be establishing [one-to-many relationship](../../suite/generating-crud-page.md#step-by-step-creating-a-navigation-property-with-1-to-many-relationship) with *Book* and *Author* entities, in the next part.
+
+## Creating the Author Entity
+
+After generating the all necessary code for the `Book` entity, and testing the *Books* page, by building & starting the application, now you can continue with creating the `Author` entity.
+
+> Before, creating the `Author` entity, please **stop the application** in ABP Studio's *Solution Runner* panel, because ABP Suite will make changes in the solution and it might need to build the solution in some steps and running the solution prevents to build it.
+
+Click the entity selection box in the top right of the *CRUD page generation* page, and select the *-New entity-*:
+
+![](/images/suite-author-new-entity.png)
+
+Then, you can type `Author` for the *Name* field and leave the other options as is (you can change the menu icon as **pen** for a proper menu icon, and/or other options, if you wish). ABP Suite automatically calculates proper values for the rest of the inputs for you:
+
+![](/images/suite-author-entity-1.png)
+
+ABP Suite sets:
+
+* Entity type as **master** (ABP Suite allows you to establish [master-child relationship](../../suite/creating-master-detail-relationship.md)),
+* Base class as **FullAuditedAggregateRoot** ([see other possible values](../../framework/architecture/domain-driven-design/entities.md)),
+* Primary key type as **Guid**,
+* Plural name, database name, namespace, page title, menu item and more...
+* Also, it enables **code customization**, **UI code generation**, **unit & integration test generation** and **bulk delete** by default.
+
+After, specifying the entity metadata, open the *Properties* tab and create the properties shown in the following figure:
+
+![](./images/suite-author-entity-2.png)
+
+Here the details:
+
+* `Name` is **required**, it's a **string** property, and it's a **textarea**. Minimum length is **2** and maximum length is **128**.
+* `BirthDate` is a **DateTime** property and **not nullable**.
+* `ShortBio` is a **string** property, it's **required**, maximum length is **256**. 
+
+You can leave the other configurations as default.
+
+> **Note:** All properties are marked as **filterable** by default, and they appear in the advanced filter section because of that. You can set any properties you want as **not filterable** and then the related property will be removed from the advanced filter section and code will be generated accordingly.
+
+You can click the **Save and Generate** button to start the code generation process:
+
+![](./images/suite-book-entity-5.png)
+
+ABP Suite will generate the necessary code for you. It will take some time to complete the process. After the process is completed, you will see a success message, you can click the *Ok* button, and build & start the application by clicking the *Run -> Build & Start* button in the *Solution Runner* panel:
+
+![](./images/suite-book-entity-6.png)
+
+After the application is started, you can right-click and *Browse* on the application to open it in the ABP Studio's pre-integrated browser and try to add a new author:
+
+![](./images/suite-author-pages-1.png)
+
+As you can see, the *Name* field is **required**, the *Birth Date* field shows a datepicker, and the *Short Bio* field is also **required** and it's a **textarea**. You just configured how you want your properties with some options (for example, setting the short bio as **textarea** and **required**), and ABP Suite generated code according that.
+
+## Summary
+
+In this part, you've created a new entity named `Author` and generated the necessary code for it with [ABP Suite](../../suite/index.md) with a few clicks. ABP Suite generated the all code for you, including the **entity**, **application service**, **database relations**, **unit & integration tests**, **UI** and **defined the custom hooks for code customization**.
+
+In the next part, you will establish [one-to-many relation](../../suite/generating-crud-page.md) between the `Book` and `Author` entities.