Completed initial version of the TODO app tutorial.

6 years ago · 88bf958dec
3 changed files with 362 additions and 0 deletions
--- a/docs/en/Tutorials/Todo/Index.md
+++ b/docs/en/Tutorials/Todo/Index.md
@ -0,0 +1,362 @@
+# Quick Tutorial
+
+````json
+//[doc-params]
+{
+    "UI": ["MVC", "Blazor", "BlazorServer", "NG"],
+    "DB": ["EF", "Mongo"],
+}
+````
+
+This is a single-part, quick tutorial to build a simple TODO application with the ABP Framework. Here, a sample screenshot from the final application:
+
+![todo-list](todo-list.png)
+
+### Source Code
+
+You can find source code of the example application [here](https://github.com/abpframework/abp-samples/tree/master/TodoApp).
+
+## Creating a New Solution
+
+Please create a new solution, named `TodoApp`, by following the [Getting Started](../../Getting-Started.md) document.
+
+**TODO: Instead, we can create the solution here!**
+
+## Domain Layer
+
+This application has a single [entity](../../Entities.md) and we are starting by creating it. Create a new `TodoItem` class inside the *TodoApp.Domain* project:
+
+````csharp
+using System;
+using Volo.Abp.Domain.Entities;
+
+namespace TodoApp
+{
+    public class TodoItem : BasicAggregateRoot<Guid>
+    {
+        public string Text { get; set; }
+    }
+}
+````
+
+`BasicAggregateRoot` is one the simplest base class to create root entities, and `Guid` is the primary key (`Id`) of the entity here.
+
+## Database Integration
+
+Next step is to setup the [Entity Framework Core](../../Entity-Framework-Core.md) configuration. Open the `TodoAppDbContext` class in the `EntityFrameworkCore` folder of the *TodoApp.EntityFrameworkCore* project and add a new `DbSet` property to this class:
+
+````csharp
+public DbSet<TodoItem> TodoItems { get; set; }
+````
+
+Then open the `TodoAppDbContextModelCreatingExtensions` class in the same folder and add a mapping configuration for the `TodoItem` class as shown below:
+
+````csharp
+public static void ConfigureTodoApp(this ModelBuilder builder)
+{
+    Check.NotNull(builder, nameof(builder));
+
+    builder.Entity<TodoItem>(b =>
+    {
+        b.ToTable("TodoItems");
+    });
+}
+````
+
+We've mapped `TodoItem` entity to a `TodoItems` table in the database.
+
+**TODO: DB MIGRATIONS**
+
+Now, we can use ABP repositories to save and retrieve todo items, as we'll do in the next section.
+
+## Application Layer
+
+An [Application Service](../../Application-Services.md) is used to perform use cases of the application. We need to perform the following use cases;
+
+* Get the list of todo items
+* Create a new todo item
+* Delete an existing todo item
+
+We can start by defining an interface for the application service. Create a new `ITodoAppService` interface in the *TodoApp.Application.Contracts* project, as shown below:
+
+````csharp
+using System;
+using System.Collections.Generic;
+using System.Threading.Tasks;
+using Volo.Abp.Application.Services;
+
+namespace TodoApp
+{
+    public interface ITodoAppService : IApplicationService
+    {
+        Task<List<TodoItemDto>> GetListAsync();
+        Task<TodoItemDto> CreateAsync(string text);
+        Task DeleteAsync(Guid id);
+    }
+}
+````
+
+`GetListAsync` and `CreateAsync` methods return `TodoItemDto`. Applications Services typically gets and returns DTOs ([Data Transfer Objects](../../Data-Transfer-Objects.md)) instead of entities. So, we should define the DTO class here. Create a new `TodoItemDto` class inside the *TodoApp.Application.Contracts* project:
+
+````csharp
+using System;
+
+namespace TodoApp
+{
+    public class TodoItemDto
+    {
+        public Guid Id { get; set; }
+        public string Text { get; set; }
+    }
+}
+````
+
+This is a very simple DTO class that matches to our `TodoItem` entity. We are ready to implement the `ITodoAppService`. Create a `TodoAppService` class inside the *TodoApp.Application* project, as shown below:
+
+````csharp
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Threading.Tasks;
+using Volo.Abp.Application.Services;
+using Volo.Abp.Domain.Repositories;
+
+namespace TodoApp
+{
+    public class TodoAppService : ApplicationService, ITodoAppService
+    {
+        private readonly IRepository<TodoItem, Guid> _todoItemRepository;
+
+        public TodoAppService(IRepository<TodoItem, Guid> todoItemRepository)
+        {
+            _todoItemRepository = todoItemRepository;
+        }
+        
+        // TODO: Implement the methods
+    }
+}
+````
+
+This class inherits from the `ApplicationService` class of the ABP Framework and implements the `ITodoAppService` that was defined before. ABP provides default generic [repositories](../../Repositories.md) for the entities. We can use them to perform the fundamental database operations. This class [injects](../../Dependency-Injection.md) `IRepository<TodoItem, Guid>`, which is the default repository for the `TodoItem` entity. We will use it to implement the use cases described before.
+
+Let's start by implementing the `GetListAsync` method:
+
+````csharp
+public async Task<List<TodoItemDto>> GetListAsync()
+{
+    var items = await _todoItemRepository.GetListAsync();
+    return items
+        .Select(item => new TodoItemDto
+        {
+            Id = item.Id,
+            Text = item.Text
+        }).ToList();
+}
+````
+
+We are simply getting the complete `TodoItem` list from database, mapping them to `TodoItemDto` objects and returning as the result.
+
+Next method is `CreateAsync` and we can implement it as shown below:
+
+````csharp
+public async Task<TodoItemDto> CreateAsync(string text)
+{
+    var todoItem = await _todoItemRepository.InsertAsync(
+        new TodoItem {Text = text}
+    );
+
+    return new TodoItemDto
+    {
+        Id = todoItem.Id,
+        Text = todoItem.Text
+    };
+}
+````
+
+Repository's `InsertAsync` method inserts the given `TodoItem` to database and returns the same `TodoItem` object. It also sets the `Id`, so we can use it on the returning object. We are simply returning a `TodoItemDto` by creating from the new `TodoItem` entity.
+
+Finally, we can simple implement the `DeleteAsync` as the following code block:
+
+````csharp
+public async Task DeleteAsync(Guid id)
+{
+    await _todoItemRepository.DeleteAsync(id);
+}
+````
+
+The application service is ready to be used from the UI layer.
+
+## User Interface Layer
+
+It is time to show the todo items on the UI! Before starting to write the code, it would be good to remember what we are trying to build. Here, a sample screenshot from the final UI:
+
+![todo-list](todo-list.png)
+
+> **We will keep the UI side minimal for this tutorial to make the tutorial simple and focused. See the [web application development tutorial](../Part-1.md) to build real-life pages with all aspects.**
+
+### Index.cshtml.cs
+
+Open the `Index.cshtml.cs` file in the `Pages` folder of the *TodoApp.Web* project and replace with the following content:
+
+````csharp
+using System.Collections.Generic;
+using System.Threading.Tasks;
+
+namespace TodoApp.Web.Pages
+{
+    public class IndexModel : TodoAppPageModel
+    {
+        public List<TodoItemDto> TodoItems { get; set; }
+
+        private readonly ITodoAppService _todoAppService;
+
+        public IndexModel(ITodoAppService todoAppService)
+        {
+            _todoAppService = todoAppService;
+        }
+
+        public async Task OnGetAsync()
+        {
+            TodoItems = await _todoAppService.GetListAsync();
+        }
+    }
+}
+````
+
+This class uses the `ITodoAppService` to get the list of todo items and assign the the `TodoItems` property. We will use it to render the todo items on the razor page.
+
+### Index.cshtml
+
+Open the `Index.cshtml` file in the `Pages` folder of the *TodoApp.Web* project and replace with the following content:
+
+````xml
+@page
+@model TodoApp.Web.Pages.IndexModel
+@section styles {
+    <abp-style src="/Pages/Index.css" />
+}
+@section scripts {
+    <abp-script src="/Pages/Index.js" />
+}
+<div class="container">
+    <abp-card>
+        <abp-card-header>
+            <abp-card-title>
+                TODO LIST
+            </abp-card-title>
+        </abp-card-header>
+        <abp-card-body>
+            
+            <!-- FORM FOR NEW TODO ITEMS -->
+            <form id="NewItemForm" class="form-inline">
+                <input id="NewItemText" type="text" class="form-control mr-2" placeholder="enter text...">
+                <button type="submit" class="btn btn-primary">Submit</button>
+            </form>
+            
+            <!-- TODO ITEMS LIST -->
+            <ul id="TodoList">
+                @foreach (var todoItem in Model.TodoItems)
+                {
+                    <li data-id="@todoItem.Id">
+                        <i class="fa fa-trash-o"></i> @todoItem.Text
+                    </li>
+                }
+            </ul>
+        </abp-card-body>
+    </abp-card>
+</div>
+````
+
+We are using ABP's [card tag helper](../../UI/AspNetCore/Tag-Helpers/Cards.md) to create a simple card view. You could directly use the standard bootstrap HTML structure, however the ABP [tag helpers]() make it much easier and type safe.
+
+This page imports a CSS and a JavaScript file, so we should also create them.
+
+### Index.js
+
+Open the `Index.js` file in the `Pages` folder of the *TodoApp.Web* project and replace with the following content:
+
+````js
+$(function () {
+    
+    // DELETING ITEMS /////////////////////////////////////////
+    $('#TodoList').on('click', 'li i', function(){
+        var $li = $(this).parent();
+        var id = $li.attr('data-id');
+        
+        todoApp.todo.delete(id).then(function(){
+            $li.remove();
+            abp.notify.info('Deleted the todo item.');
+        });
+    });
+    
+    // CREATING NEW ITEMS /////////////////////////////////////
+    $('#NewItemForm').submit(function(e){
+        e.preventDefault();
+        
+        var todoText = $('#NewItemText').val();        
+        todoApp.todo.create(todoText).then(function(result){
+            $('<li data-id="' + result.id + '">')
+                .html('<i class="fa fa-trash-o"></i> ' + result.text)
+                .appendTo($('#TodoList'));
+            $('#NewItemText').val('');
+        });
+    });
+});
+````
+
+In the first part, we are registering to click events of the trash icons near to the todo items, deleting the related item on the server and showing a notification on the UI. Also, we are removing the deleted item from DOM, so we don't need to refresh the page.
+
+In the second part, we are creating a new todo item on the server. If it succeed, we are then manipulating DOM to insert a new `<li>` element to the todo list. In this way, no need to refresh the whole page after creating a new todo item.
+
+The interesting part here is how we communicate with the server. It seems we are just calling some JavaScript functions like `todoApp.todo.delete(id)` and `todoApp.todo.create(todoText)`.
+
+#### Dynamic JavaScript Proxies & Auto API Controllers
+
+ `todoApp.todo.delete(...)` and `todoApp.todo.create(...)` functions are dynamically created by the ABP Framework, thanks to the [Dynamic JavaScript Client Proxy](../../UI/AspNetCore/Dynamic-JavaScript-Proxies.md) system. These functions perform HTTP API calls to the server and return a promise, so you can register a callback to the `then` function as we've done above.
+
+However, you may ask that we haven't created any API Controller, so how server handles these requests? This question brings us the [Auto API Controller](../../API/Auto-API-Controllers.md) feature of the ABP Framework. It automatically converts the application services to API Controllers by conventions.
+
+If you open the [Swagger UI](https://swagger.io/tools/swagger-ui/) by entering the `/swagger` URL in your application, you can see the TODO API:
+
+![todo-api](todo-api.png)
+
+### Index.css
+
+As the final touch, open the `Index.css` file in the `Pages` folder of the *TodoApp.Web* project and replace with the following content:
+
+````css
+#TodoList{
+    list-style: none;
+    margin: 0;
+    padding: 0;
+}
+
+#TodoList li {
+    padding: 5px;
+    margin: 5px 0px;
+    border: 1px solid #cccccc;
+    background-color: #f5f5f5;
+}
+
+#TodoList li i
+{
+    opacity: 0.5;
+}
+
+#TodoList li i:hover
+{
+    opacity: 1;
+    color: #ff0000;
+    cursor: pointer;
+}
+````
+
+This is a simple styling for the todo page. We believe that you can do much better :)
+
+## Conclusion
+
+In this tutorial, we've build a very simple application to warm up to the ABP Framework. If you are looking to build a serious application, please check the [web application development tutorial](../Part-1.md) which covers all the aspects of a real-life web application development.
+
+## Source Code
+
+You can find source code of the example application [here](https://github.com/abpframework/abp-samples/tree/master/TodoApp).
--- a/docs/en/Tutorials/Todo/todo-api.png
+++ b/docs/en/Tutorials/Todo/todo-api.png
--- a/docs/en/Tutorials/Todo/todo-list.png
+++ b/docs/en/Tutorials/Todo/todo-list.png