diff --git a/docs/en/Community-Articles/2020-09-09-Replacing-Email-Template-and-Sending-Emails/POST.md b/docs/en/Community-Articles/2020-09-09-Replacing-Email-Template-and-Sending-Emails/POST.md new file mode 100644 index 0000000000..fa5806c488 --- /dev/null +++ b/docs/en/Community-Articles/2020-09-09-Replacing-Email-Template-and-Sending-Emails/POST.md @@ -0,0 +1,364 @@ +# Replacing Email Template and Sending Emails + +## Introduction + +Hi, in this step by step article, I will show you how you can replace the existing templates and how you can send emails by using the replaced templates. + +## Creating the Solution + +Before starting to development, we need to create a solution named `TemplateReplace` (or whatever you want). We can download a new startup template by using [ABP CLI](https://docs.abp.io/en/abp/latest/CLI) : + +````bash +abp new TemplateReplace +```` + +Our project boilerplate will be ready after the download is finished. Then, open the solution in the Visual Studio (or your favorite IDE). + +Run the `TemplateReplace.DbMigrator` application as below to create the database and seed initial data (which creates the admin user, admin role, permissions etc.). + +![db-migrator-1](db-migrator-1.jpg) + +* Left click to `TemplateReplace.DbMigrator` and choose the `Debug`. + +![db-migrator-2](db-migrator-2.jpg) + +* After that, click the `Start new instance` option to start the database migrations. + +![db-migrator-3](db-migrator-3.jpg) + +Then we can run the `TemplateReplace.Web` project to see our application working. + +> _Default login credentials for admin: username is **admin** and password is **1q2w3E\***_ + +## Starting the Development + +First thing we need to do is, creating a email service to sending emails. ABP Framework provides `IEmailSender` service that is used to send emails. + +### Step - 1 + +Create an `Email` folder in the `TemplateReplace.Application.Contracts` project and add a interface named `IEmailService` inside of it : + +```csharp +using System.Threading.Tasks; + +namespace TemplateReplace.Email +{ + public interface IEmailService + { + Task SendAsync(); + } +} +``` + +### Step - 2 + +Create an `Email` folder in the `TemplateReplace.Application` project and add a class named `EmailService` inside of it to implement the `IEmailService` interface. + +```csharp +using System.Threading.Tasks; +using Volo.Abp.DependencyInjection; +using Volo.Abp.Emailing; +using Volo.Abp.Emailing.Templates; +using Volo.Abp.TextTemplating; + +namespace TemplateReplace.Email +{ + public class EmailService : IEmailService, ITransientDependency + { + private readonly IEmailSender _emailSender; + private readonly ITemplateRenderer _templateRenderer; + + public EmailService(IEmailSender emailSender, ITemplateRenderer templateRenderer) + { + _emailSender = emailSender; + _templateRenderer = templateRenderer; + } + + public async Task SendAsync() + { + var emailBody = await _templateRenderer.RenderAsync( + StandardEmailTemplates.Message, + new + { + message = "This is email body..." + } + ); + + await _emailSender.SendAsync( + "from_email@abp.io", + "target_email@abp.io", + "Subject", + emailBody + ); + + return emailBody; + } + } +} +``` + +* ABP framework provides a strong and flexible [text templating system](https://docs.abp.io/en/abp/latest/Text-Templating). So, we can use the text templating system to create dynamic email contents. + +* To create an email content, we need to inject `ITemplateRenderer` and use the `RenderAsync` method to render a template. + +* We've used `StandardEmailTemplates.Message` as standart email template. This provides us a standard and simple message template to send mails. + +* The resulting email body should be like shown below: +```html + + + + + + + This is email body... + + +``` + +### Step - 3 + +* Now we need to create a user interface to be able to see the standard email template. To do this quickly, open your existing `Index.cshtml.cs` in your `TemplateReplace.Web` project. It's under the **Pages** folder. And copy-paste the below content. + +```csharp +using TemplateReplace.Email; + +namespace TemplateReplace.Web.Pages +{ + public class IndexModel : TemplateReplacePageModel + { + private readonly IEmailService _emailService; + public string EmailBody { get; set; } + + public IndexModel(IEmailService emailService) + { + _emailService = emailService; + } + + public async void OnGet() + { + if(CurrentUser.IsAuthenticated) + { + EmailBody = await _emailService.SendAsync(); + } + } + } +} +``` + +* Then, open your `Index.cshtml` file and set the content as below. + +```html +@page +@using Microsoft.AspNetCore.Mvc.Localization +@using TemplateReplace.Localization +@using Volo.Abp.Users +@model TemplateReplace.Web.Pages.IndexModel +@inject IHtmlLocalizer L +@inject ICurrentUser CurrentUser +@section styles { + + + +} +@section scripts { + + + +} +
+

@L["Welcome"]

+
+
+

@L["LongWelcomeMessage"]

+
+
+
+ abp.io + @if (!CurrentUser.IsAuthenticated) + { + @L["Login"] + } +
+ + +``` + +* After all of this, we can run the `TemplateReplace.Web` application and logged in to see the standard email template. + +![standard-template](standard-template.jpg) + +* As we see above, `StandardEmailTemplates.Message` template works as expected. But we need to be sure about the mail has been sent or not. To achieve this, we can examine the **logs**. So, open the `Logs` folder (It's under **TemplateReplace .Web** folder). Inside of this folder, there is a file named `logs.txt`. When we open this file and examine the lines, we can see our email details as below (target email address, subject of mail and email body). + +![email-details](email-details.jpg) + +### Step - 4 + +* So far we've sent mail by using standard email template of ABP. But we can want to replace the email template with the new one. We can achieve this by following [the documentation](https://docs.abp.io/en/abp/latest/Text-Templating#replacing-the-existing-templates). + +* First thing we need to do is creating our new **email template**. So, create a folder named `Templates` and add `EmailLayout.cshtml` file inside of it. And copy-paste the below content. + +```html + + + + + + + + +
+ + + + + +
+ + +``` + +* Then we need to make the template file as "Embedded Resource". We can do this as below. + +* First left click to **EmailLayout.cshtml** and choose `Properties`. + +![embedded-resource](embedded-resource.jpg) + +* Then be sure about build action is **Embedded resource**. + +![embedded-resource-2](embedded-resource-2.jpg) + +### Step - 5 (Replacing the Email Template) + +* To replace the current email template with our new email template, we need to override it. To achieve this, create a class in `TemplateReplace.Web` and fill it with the below content. + +```csharp +using Volo.Abp.DependencyInjection; +using Volo.Abp.Emailing.Templates; +using Volo.Abp.TextTemplating; + +namespace TemplateReplace.Web +{ + public class EmailTemplateDefinitionProvider : TemplateDefinitionProvider, ITransientDependency + { + public override void Define(ITemplateDefinitionContext context) + { + var emailLayoutTemplate = context.GetOrNull(StandardEmailTemplates.Message); + + emailLayoutTemplate + .WithVirtualFilePath( + "/Templates/EmailLayout.cshtml", + isInlineLocalized: true + ); + } + } +} +``` + +* In here we've created a template definition provider class that gets the email layout template and changes the virtual file path for the template. + +* This approach allows us to locate templates in any folder instead of the folder defined by the depended module. + +### Step - 6 + +* Lastly, we need to configure the [virtual file system](https://docs.abp.io/en/abp/latest/Virtual-File-System). To do this open your `TemplateReplaceWebModule` in `TemplateReplace.Web` and update the `ConfigureVirtualFileSystem` method as below. + +```csharp +//... +private void ConfigureVirtualFileSystem(IWebHostEnvironment hostingEnvironment) +{ + if (hostingEnvironment.IsDevelopment()) + { + Configure(options => + { + options.FileSets.AddEmbedded(); //to replace the standard email template + + //... + }); + } +} +//... +``` + +* And now when we start the application, we need to see the new email template like as below. + +![email-last](email-last.jpg) + +## Text Template Management + +![template-definitions](template-definitions.png) + +* ABP Commercial's [Text Template Management](https://commercial.abp.io/modules/Volo.TextTemplateManagement) module is really fascinating. It makes it super easy to stores and edits template contents. We can list all templates on a page, editing them, localizing them, and so on. + +![inline-content](inline-content.png) + +* ABP Commercial's text template management module, allows us to modify a template through the UI. + +* I highly recommend you to [check it out](https://commercial.abp.io/modules/Volo.TextTemplateManagement). + +## References + +* [Text Templating](https://docs.abp.io/en/abp/latest/Text-Templating) +* [Emailing](https://docs.abp.io/en/abp/latest/Emailing) +* [Virtual File System](https://docs.abp.io/en/abp/latest/Virtual-File-System) \ No newline at end of file diff --git a/docs/en/Community-Articles/2020-09-09-Replacing-Email-Template-and-Sending-Emails/db-migrator-1.jpg b/docs/en/Community-Articles/2020-09-09-Replacing-Email-Template-and-Sending-Emails/db-migrator-1.jpg new file mode 100644 index 0000000000..8a0c4c345b Binary files /dev/null and b/docs/en/Community-Articles/2020-09-09-Replacing-Email-Template-and-Sending-Emails/db-migrator-1.jpg differ diff --git a/docs/en/Community-Articles/2020-09-09-Replacing-Email-Template-and-Sending-Emails/db-migrator-2.jpg b/docs/en/Community-Articles/2020-09-09-Replacing-Email-Template-and-Sending-Emails/db-migrator-2.jpg new file mode 100644 index 0000000000..4adc9614c3 Binary files /dev/null and b/docs/en/Community-Articles/2020-09-09-Replacing-Email-Template-and-Sending-Emails/db-migrator-2.jpg differ diff --git a/docs/en/Community-Articles/2020-09-09-Replacing-Email-Template-and-Sending-Emails/db-migrator-3.jpg b/docs/en/Community-Articles/2020-09-09-Replacing-Email-Template-and-Sending-Emails/db-migrator-3.jpg new file mode 100644 index 0000000000..16b365b8a5 Binary files /dev/null and b/docs/en/Community-Articles/2020-09-09-Replacing-Email-Template-and-Sending-Emails/db-migrator-3.jpg differ diff --git a/docs/en/Community-Articles/2020-09-09-Replacing-Email-Template-and-Sending-Emails/email-details.jpg b/docs/en/Community-Articles/2020-09-09-Replacing-Email-Template-and-Sending-Emails/email-details.jpg new file mode 100644 index 0000000000..df23bcc8e0 Binary files /dev/null and b/docs/en/Community-Articles/2020-09-09-Replacing-Email-Template-and-Sending-Emails/email-details.jpg differ diff --git a/docs/en/Community-Articles/2020-09-09-Replacing-Email-Template-and-Sending-Emails/email-last.jpg b/docs/en/Community-Articles/2020-09-09-Replacing-Email-Template-and-Sending-Emails/email-last.jpg new file mode 100644 index 0000000000..dbe974417b Binary files /dev/null and b/docs/en/Community-Articles/2020-09-09-Replacing-Email-Template-and-Sending-Emails/email-last.jpg differ diff --git a/docs/en/Community-Articles/2020-09-09-Replacing-Email-Template-and-Sending-Emails/embedded-resource-2.jpg b/docs/en/Community-Articles/2020-09-09-Replacing-Email-Template-and-Sending-Emails/embedded-resource-2.jpg new file mode 100644 index 0000000000..81592fb69a Binary files /dev/null and b/docs/en/Community-Articles/2020-09-09-Replacing-Email-Template-and-Sending-Emails/embedded-resource-2.jpg differ diff --git a/docs/en/Community-Articles/2020-09-09-Replacing-Email-Template-and-Sending-Emails/embedded-resource.jpg b/docs/en/Community-Articles/2020-09-09-Replacing-Email-Template-and-Sending-Emails/embedded-resource.jpg new file mode 100644 index 0000000000..9d437790b1 Binary files /dev/null and b/docs/en/Community-Articles/2020-09-09-Replacing-Email-Template-and-Sending-Emails/embedded-resource.jpg differ diff --git a/docs/en/Community-Articles/2020-09-09-Replacing-Email-Template-and-Sending-Emails/inline-content.png b/docs/en/Community-Articles/2020-09-09-Replacing-Email-Template-and-Sending-Emails/inline-content.png new file mode 100644 index 0000000000..cbbf188f37 Binary files /dev/null and b/docs/en/Community-Articles/2020-09-09-Replacing-Email-Template-and-Sending-Emails/inline-content.png differ diff --git a/docs/en/Community-Articles/2020-09-09-Replacing-Email-Template-and-Sending-Emails/standard-template.jpg b/docs/en/Community-Articles/2020-09-09-Replacing-Email-Template-and-Sending-Emails/standard-template.jpg new file mode 100644 index 0000000000..68f4dc4834 Binary files /dev/null and b/docs/en/Community-Articles/2020-09-09-Replacing-Email-Template-and-Sending-Emails/standard-template.jpg differ diff --git a/docs/en/Community-Articles/2020-09-09-Replacing-Email-Template-and-Sending-Emails/template-definitions.png b/docs/en/Community-Articles/2020-09-09-Replacing-Email-Template-and-Sending-Emails/template-definitions.png new file mode 100644 index 0000000000..aaf46b353e Binary files /dev/null and b/docs/en/Community-Articles/2020-09-09-Replacing-Email-Template-and-Sending-Emails/template-definitions.png differ