Merge branch 'master' into dev

Author: ebicoglu

docs/en/Deployment-Angular-Docker.md

@@ -0,0 +1,12 @@
+# Publishing to Docker Containers
+
+ASP.NET Zero solution has a **build folder** which contains a PowerShell script to **build & publish** your solution to the **output** folder. 
+
+It also contains **Docker** files to run your application inside Docker containers. You can customize the default run configuration according to your requirements. 
+
+In your `aspnet-core\docker\ng\` folder, you will see;
+
+* `up.ps1`  which starts the Docker container with the configuration defined in `docker-compose.yml`
+* `down.ps1`  which shuts down the Docker container with the configuration defined in `docker-compose.yml`
+
+![docker-folder-angular](images\docker-folder-angular.jpg)

docs/en/Step-by-step-publish-to-azure-angular.md renamed to docs/en/Deployment-Angular-Publish-Azure.md

@@ -0,0 +1,31 @@
+# Deployment
+
+## About Deployment
+
+If you have merged Angular UI project into ASP.NET Core project then you  only need to publish your .Host project. After publish .Host project, you should copy files that are in .Host/wwwroot/dist folder to publish_folder/wwwroot. 
+
+For example: Move files in `.Host/wwwroot/dist` to `C:\inetpub\wwwroot\my-website\wwwroot`
+
+We are using [angular-cli](https://cli.angular.io/) for development & deployment. Angular CLI has it's own build command that can be used to build your application:
+
+```
+ng build --prod
+```
+
+This command uses **dist** folder as output. Just remember to change **assets/appconfig.json** file with your own configuration.
+
+## AOT
+
+Angular CLI uses **[AOT](https://angular.io/docs/ts/latest/cookbook/aot-compiler.html) (Ahead of Time)** compilation by default. You can add --no-aot parameter
+to the `ng build` command to disable it. But we recommend AOT feature since it has significant performance gain.
+
+*Be aware that, if you don't configure email settings, some functions like new tenant registration may not work.*
+
+# Next
+
+* [Publishing to Azure](Deployment-Angular-Publish-Azure)
+* [Publishing to IIS](Deployment-Angular-Publish-IIS)
+* [Publishing to Docker](Deployment-Angular-Docker)
+
+
+

docs/en/Step-by-step-angular-publish-to-iis.md renamed to docs/en/Deployment-Angular-Publish-IIS.md

@@ -0,0 +1,12 @@
+# Publishing to Docker Containers
+
+ASP.NET Zero solution has a **build folder** which contains a PowerShell script to **build & publish** your solution to the **output** folder. 
+
+It also contains **Docker** files to run your application inside Docker containers. You can customize the default run configuration according to your requirements. 
+
+In your `aspnet-core\docker\mvc\` folder, you will see;
+
+* `up.ps1`  which starts the Docker container with the configuration defined in `docker-compose.yml`
+* `down.ps1`  which shuts down the Docker container with the configuration defined in `docker-compose.yml`
+
+![docker-folder-angular](images\docker-folder-core-mvc.jpg)

docs/en/Deployment-Angular.md

@@ -1,4 +1,4 @@
-# Step By Step Publish To IIS
+# Publishing to IIS
 
 Publishing ASP.NET Zero Core MVC project is no different to any other ASP.NET Core Applications.
 
@@ -23,4 +23,5 @@ Publishing ASP.NET Zero Core MVC project is no different to any other ASP.NET Co
 
 <img src="images/iis-core-publish-configure-app-pool.png">
 
-Check [Host ASP.NET Core on Windows with IIS](https://docs.microsoft.com/en-us/aspnet/core/host-and-deploy/iis/index?view=aspnetcore-2.1) document for more detail.
+For more information see [Host ASP.NET Core on Windows with IIS](https://docs.microsoft.com/en-us/aspnet/core/host-and-deploy/iis/index?view=aspnetcore-2.1) document
+

docs/en/Step-by-step-publish-to-azure-core-mvc.md renamed to docs/en/Deployment-Mvc-Core-Azure.md

@@ -0,0 +1,12 @@
+# Deployment & Publish
+
+Publishing ASP.NET Zero is not different than any other solution. You can use Visual Studio as you normally  do. 
+
+Notice that, if you don't configure email settings, some functions (like new tenant registration) may not work as expected.
+
+## Next
+
+* [Publishing to Azure](Deployment-Mvc-Core-Azure)
+* [Publishing to IIS](Deployment-Mvc-Core-IIS)
+* [Publishing to Docker Containers](Deployment-Mvc-Core-Docker)
+

docs/en/Deployment-Mvc-Core-Docker.md

@@ -0,0 +1,94 @@
+# Adding AddPhone and DeletePhone Methods
+
+We are adding two more methods to IPersonAppService interface as shown
+below:
+
+```csharp
+Task DeletePhone(EntityDto<long> input);
+Task<PhoneInPersonListDto> AddPhone(AddPhoneInput input);
+```
+
+We could create a new, separated IPhoneAppService. It's your choice.
+But, we can consider Person as an aggregate and add phone related
+methods here. AddPhoneInput DTO is shown below:
+
+```csharp
+public class AddPhoneInput
+{
+    [Range(1, int.MaxValue)]
+    public int PersonId { get; set; }
+
+    [Required]
+    public PhoneType Type { get; set; }
+
+    [Required]
+    [MaxLength(PhoneConsts.MaxNumberLength)]
+    public string Number { get; set; }
+}
+```
+
+We used PhoneConsts.MaxNumberLength for Number field. You should create
+this consts in **.Core.Shared**.
+
+```csharp
+public class PhoneConsts
+{
+    public const int MaxNumberLength = 16;
+}
+```
+
+Now, we can implement these methods:
+
+```csharp
+[AbpAuthorize(AppPermissions.Pages_Tenant_PhoneBook_EditPerson)]
+public async Task DeletePhone(EntityDto<long> input)
+{
+    await _phoneRepository.DeleteAsync(input.Id);
+}
+
+[AbpAuthorize(AppPermissions.Pages_Tenant_PhoneBook_EditPerson)]
+public async Task<PhoneInPersonListDto> AddPhone(AddPhoneInput input)
+{
+    var person = _personRepository.Get(input.PersonId);
+    await _personRepository.EnsureCollectionLoadedAsync(person, p => p.Phones);
+
+    var phone = ObjectMapper.Map<Phone>(input);
+    person.Phones.Add(phone);
+
+    //Get auto increment Id of the new Phone by saving to database
+    await CurrentUnitOfWork.SaveChangesAsync();
+
+    return ObjectMapper.Map<PhoneInPersonListDto>(phone);
+}
+```
+
+Then we add configuration for AutoMapper into CustomDtoMapper.cs like below:
+
+```csharp
+configuration.CreateMap<AddPhoneInput, Phone>();
+```
+
+(Note: We injected **IRepository&lt;Phone, long&gt;** in the constructor
+and set to \_phoneRepository field, as similar to \_personRepository)
+
+**DeletePhone** method is simple. It only deletes phone with given id.
+
+**AddPhone** method **gets** the person from database and add new phone
+to person.Phones collection. Then is **save changes**. Saving changes
+causes inserting new added phone to database and get its **Id**.
+Because, we are returning a DTO that contains newly created phone
+informations including Id. So, it should be assigned before mapping in
+the last line. (Notice that; normally it's not needed to call
+CurrentUnitOfWork.SaveChangesAsync. It's automatically called at the end
+of the method. We called it in the method since we need to save entity
+and get its Id immediately. See [UOW
+document](https://aspnetboilerplate.com/Pages/Documents/Unit-Of-Work#DocAutoSaveChanges)
+for more.)
+
+There may be different approaches for AddPhone method. You can directly
+work with a **phone repository** to insert new phone. They all have
+different pros and cons. It's your choice.
+
+## Next
+
+- [Edit Mode for Phone Numbers](Developing-Step-By-Step-Angular-Edit-Mode-Phone-Numbers)

docs/en/Step-by-step-core-publish-to-iis.md renamed to docs/en/Deployment-Mvc-Core-IIS.md

@@ -0,0 +1,50 @@
+# Adding a New Menu Item
+
+Let's begin from UI and create a new page named "**Phone book**".
+
+## Defining a Menu Item
+
+Open **src\\app\\shared\\layout\\nav\\app-navigation.service.ts** in the client side (**Acme.PhoneBookDemo.AngularUI**) which defines menu items in the application. Create new menu item as shown below (You can add it right after the dashboard menu item).
+
+```csharp
+new AppMenuItem("PhoneBook", null, "flaticon-book", "/app/main/phonebook")
+```
+
+**PhoneBook** is the menu name (will localize below), **null** is for permission name (will set it later), **flaticon-book** is just an arbitrary icon class (from [this set](http://keenthemes.com/metronic/preview/?page=components/icons/flaticon&demo=default)) and **/phonebook** is the Angular route.
+
+If you run the application, you can see a new menu item on the left menu, but it won't work (it redirects to default route) if you click to the menu item, since we haven't defined the Angular route yet.
+
+## Localize Menu Item Display Name
+
+Localization strings are defined in **XML** files in **.Core** project in server side as shown below:
+
+<img src="D:/Github/documents/docs/en/images/localization-files-4.png" alt="Localization files" class="img-thumbnail" />
+
+Open PhoneBookDemo.xml (the **default**, **English** localization dictionary) and add the following line:
+
+```xml
+<text name="PhoneBook">Phone Book</text>
+```
+
+If we don't define "PhoneBook"s value for other localization dictionaries, default value is shown in all languages. For example, we can define it also for Turkish in `PhoneBookDmo-tr.xml` file:
+
+```xml
+<text name="PhoneBook">Telefon Rehberi</text>
+```
+
+Note: Any change in server side (including change localization texts) requires recycle of the server application. We suggest to use Ctrl+F5 if you don't need to debugging for a faster startup. In that case, it's
+enough to make a re-build to recycle the application.
+
+## Angular Route
+
+Angular has a powerful URL routing system. ASP.NET Zero has defined routes in a few places (for modularity, see [main menu & layout](Features-Angular-Main-Menu-Layout.md)). We want to add phone book page to the main module. So, open **src\\app\\main\\main-routing.module.ts** in the client side and add a new route just below to the dashboard:
+
+```json
+{ path: 'phonebook', component: PhoneBookComponent }
+```
+
+We get an error since we haven't defined PhoneBookComponent yet. Also, we ignored permission for now (will implement later).
+
+## Next
+
+- [Creating the PhoneBook Component](Developing-Step-By-Step-Angular-Creating-PhoneBook-Component)

docs/en/Deployment-Mvc-Core.md

@@ -0,0 +1,8 @@
+# Adding Phone Numbers
+
+Until now, we did not even mention about phone numbers. It's time to
+extend our domain to support **multiple phone numbers** for a person.
+
+## Next
+
+- [Creating Phone Entity](Developing-Step-By-Step-Angular-Creating-Phone-Entity)

docs/en/Developing-Step-By-Step-Angular-Adding-AddPhone-DeletePhone-Methods.md

@@ -0,0 +1,127 @@
+# Authorization For Phone Book
+
+At this point, anyone can enter phone book page since no authorization
+defined. We will define two permission:
+
+- A permission to **enter phone book page**.
+- A permission to **create new person** (which is a child permission
+  of first one, as naturally).
+
+## Permission for Entering Phone Book Page
+
+### Define the permission
+
+Go to **AppAuthorizationProvider** class in the server side and add a new permission as shown below (you can add just below the dashboard permission):
+
+```csharp
+pages.CreateChildPermission(AppPermissions.Pages_Tenant_PhoneBook, L("PhoneBook" | localize), multiTenancySides: MultiTenancySides.Tenant);
+```
+
+A permission should have a unique name. We define permission names as constant strings in **AppPermissions** class. It's a simple constant string:
+
+```csharp
+public const string Pages_Tenant_PhoneBook = "Pages.Tenant.PhoneBook";
+```
+
+Unique name of this permission is "**Pages.Tenant.PhoneBook**". While you can set any string (as long as it's unique), it's suggested to use that convention. A permission can have a localizable display name: "**PhoneBook**" here. (See "Adding a New Page" section for more about localization, since it's very similar). Lastly, we set this as a **tenant** level permission.
+
+### Add AbpAuthorize attribute
+
+**AbpAuthorize** attribute can be used as **class level** or **method level** to protect an application service or service method from unauthorized users. Since all server side code is located in `PersonAppService` class, we can declare a class level attribute as shown below:
+
+```csharp
+[AbpAuthorize(AppPermissions.Pages_Tenant_PhoneBook)]
+public class PersonAppService : PhoneBookAppServiceBase, IPersonAppService
+{
+    //...
+}
+```
+
+Admin role has every static permission by default but those permissions can be reversible on user interface for this role. Go to Roles page, edit role named "admin", go to Permissions tab and revoke "Phone Book" permission and save.
+
+Now, let's try to enter Phone Book page by clicking the menu item without required permission:
+
+<img src="D:/Github/documents/docs/en/images/phonebook-permission-error.png" alt="Permission error" class="img-thumbnail" width="505" height="412" />
+
+We get an error message. This exception is thrown when any method of `PersonAppService` is called without required permission.
+
+### Guard Angular Route
+
+We got an exception about permission. Server did not send the data but we can still enter the page. To prevent it, open **main-routing.module.ts** and change the route definition like that:
+
+```json
+{ path: 'phonebook', component: PhoneBookComponent, data: { permission: 'Pages.Tenant.PhoneBook' } }
+```
+
+**AuthRouteGuard** class automatically checks route permission data and prevents entering to the view if specified permission is not granted. Try to click Phone Book menu!
+
+### Hide Unauthorized Menu Item
+
+While user can not enter to the page, the menu item still there! We should also **hide** the Phone book **menu item**. It's easy, open **app-navigation-service.ts** and add change PhoneBook menu definition as shown below:
+
+```typescript
+new AppMenuItem("PhoneBook", 'Pages.Tenant.PhoneBook', "flaticon-book", "/app/main/phonebook")
+```
+
+### Grant permission
+
+So, how we can enter the page now? Simple, go to **Role Management** page and edit **admin** role:
+
+<img src="D:/Github/documents/docs/en/images/role-permissions-with-phonebook1.png" alt="Role permissions" class="img-thumbnail" />
+
+We see that a **new permission** named "**Phone book**" added to **permissions** tab. So, we can check it and save the role. After saving, we need to **refresh** the whole page to refresh permissions for the current user. We could also grant this permission to a specific user. Now, we can enter the Phone book page again.
+
+## Permission for Create New Person
+
+While a permission for a page is useful and probably always needed, we may want to define additional permissions to perform some **specific actions** on a page, like creating a new person.
+
+### Define the Permission
+
+Defining a permission is similar (in the `AppAuthorizationProvider` class):
+
+```csharp
+var phoneBook = pages.CreateChildPermission(AppPermissions.Pages_Tenant_PhoneBook, L("PhoneBook" | localize), multiTenancySides: MultiTenancySides.Tenant);
+phoneBook.CreateChildPermission(AppPermissions.Pages_Tenant_PhoneBook_CreatePerson, L("CreateNewPerson" | localize), multiTenancySides: MultiTenancySides.Tenant);
+```
+
+First permission was defined before. In the second line, we are creating a child permission of first one. Remember to create a constant in `AppPermissions` class:
+
+```csharp
+public const string Pages_Tenant_PhoneBook_CreatePerson = "Pages.Tenant.PhoneBook.CreatePerson";
+```
+
+### Add AbpAuthorize Attribute
+
+This time, we're declaring **AbpAuthorize** attribute just for **CreatePerson** method:
+
+```csharp
+[AbpAuthorize(AppPermissions.Pages_Tenant_PhoneBook_CreatePerson)]
+public async Task CreatePerson(CreatePersonInput input)
+{
+    //...
+}
+```
+
+### Hide Unauthorized Button
+
+If we run the application and try to create a person, we get an authorization error after clicking the save button. But, it's good to **completely hide Create New Person button** if we don't have the permission. It's very simple:
+
+Open the **phonebook.component.html** view and add the permission **Pages.Tenant.PhoneBook.CreatePerson** condition as shown below:
+
+```html
+<button *ngIf="'Pages.Tenant.PhoneBook.CreatePerson' | permission" class="btn btn-primary" (click)="createPersonModal.show()"><i class="fa fa-plus"></i> {{l("CreateNewPerson" | localize)}}</button>
+```
+
+In this way, the "Create New Person" button does not rendered in server and user can not see this button.
+
+### Grant permission
+
+To see the button again, we can go to role or user manager and grant related permission as shown below:
+
+<img src="D:/Github/documents/docs/en/images/user-permissions-phonebook1.png" alt="User specific permissions" class="img-thumbnail" />
+
+As shown above, **Create new person** permission is a child permission of the **Phone book**. Remember to refresh page to get permissions updated.
+
+## Next
+
+- [Deleting a Person](Developing-Step-By-Step-Angular-Deleting-Person)