Merge pull request #57 from Lombiq/issue/SNOW-23

SNOW-23: Adding email template management and deferred email sending

Extensions/Emails/Extensions/EmailSenderShellScopeExtensions.cs

@@ -0,0 +1,41 @@
+using System.Collections.Generic;
+using System.Linq;
+using Lombiq.HelpfulExtensions.Extensions.Emails.Models;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Logging;
+using OrchardCore.Email;
+using OrchardCore.Environment.Shell.Scope;
+
+namespace Lombiq.HelpfulExtensions.Extensions.Emails.Extensions
+{
+    public static class EmailSenderShellScopeExtensions
+    {
+        /// <summary>
+        /// Sends an HTML email after the current shell scope has ended. If any errors occur during the process they
+        /// will be logged.
+        /// </summary>
+        /// <param name="parameters">Parameters required for sending emails (e.g., recipients, subject, CC).</param>
+        public static void SendEmailDeferred(this ShellScope shellScope, EmailParameters parameters) =>
+            shellScope.AddDeferredTask(async scope =>
+            {
+                var smtpService = scope.ServiceProvider.GetService<ISmtpService>();
+                var result = await smtpService.SendAsync(new MailMessage
+                {
+                    Sender = parameters.Sender,
+                    To = parameters.To?.Join(","),
+                    Cc = parameters.Cc?.Join(","),
+                    Bcc = parameters.Bcc?.Join(","),
+                    Subject = parameters.Subject,
+                    ReplyTo = parameters.ReplyTo,
+                    Body = parameters.Body,
+                    IsBodyHtml = true,
+                });
+
+                if (!result.Succeeded)
+                {
+                    var logger = scope.ServiceProvider.GetService<ILogger<ShellScope>>();
+                    logger.LogError("Email sending was unsuccessful: {0}", result.Errors.Select(error => error.ToString()).Join());
+                }
+            });
+    }
+}

Extensions/Emails/Models/EmailParameters.cs

@@ -0,0 +1,15 @@
+using System.Collections.Generic;
+
+namespace Lombiq.HelpfulExtensions.Extensions.Emails.Models
+{
+    public class EmailParameters
+    {
+        public string Sender { get; set; }
+        public IEnumerable<string> To { get; set; }
+        public IEnumerable<string> Cc { get; set; }
+        public IEnumerable<string> Bcc { get; set; }
+        public string Subject { get; set; }
+        public string Body { get; set; }
+        public string ReplyTo { get; set; }
+    }
+}

Extensions/Emails/Services/IEmailTemplateService.cs

@@ -0,0 +1,18 @@
+using System.Threading.Tasks;
+
+namespace Lombiq.HelpfulExtensions.Extensions.Emails.Services
+{
+    /// <summary>
+    /// Service for managing email templates.
+    /// </summary>
+    public interface IEmailTemplateService
+    {
+        /// <summary>
+        /// Renders an email template content identified by its ID.
+        /// </summary>
+        /// <param name="emailTemplateId">ID of the email template.</param>
+        /// <param name="model">Optional model used as replacements in the email template.</param>
+        /// <returns>Rendered email template.</returns>
+        Task<string> RenderEmailTemplateAsync(string emailTemplateId, object model = null);
+    }
+}

Extensions/Emails/Services/ShapeBasedEmailTemplateService.cs

@@ -0,0 +1,28 @@
+using System.Threading.Tasks;
+using Lombiq.HelpfulLibraries.Libraries.Shapes;
+using Lombiq.HelpfulLibraries.Libraries.Utilities;
+using OrchardCore.DisplayManagement;
+
+namespace Lombiq.HelpfulExtensions.Extensions.Emails.Services
+{
+    public class ShapeBasedEmailTemplateService : IEmailTemplateService
+    {
+        private readonly IShapeFactory _shapeFactory;
+        private readonly IShapeRenderer _shapeRenderer;
+
+        public ShapeBasedEmailTemplateService(IShapeFactory shapeFactory, IShapeRenderer shapeRenderer)
+        {
+            _shapeFactory = shapeFactory;
+            _shapeRenderer = shapeRenderer;
+        }
+
+        public async Task<string> RenderEmailTemplateAsync(string emailTemplateId, object model = null)
+        {
+            ExceptionHelpers.ThrowIfNull(emailTemplateId, nameof(emailTemplateId));
+
+            var shape = await _shapeFactory.CreateAsync($"EmailTemplate__{emailTemplateId}", Arguments.From(model ?? new { }));
+
+            return await _shapeRenderer.RenderAsync(shape);
+        }
+    }
+}

Extensions/Emails/Startup.cs

@@ -0,0 +1,25 @@
+using System;
+using Lombiq.HelpfulExtensions.Extensions.Emails.Services;
+using Lombiq.HelpfulLibraries.Libraries.Shapes;
+using Microsoft.AspNetCore.Builder;
+using Microsoft.AspNetCore.Routing;
+using Microsoft.Extensions.DependencyInjection;
+using OrchardCore.Modules;
+
+namespace Lombiq.HelpfulExtensions.Extensions.Emails
+{
+    [Feature(FeatureIds.Emails)]
+    public class Startup : StartupBase
+    {
+        public override void ConfigureServices(IServiceCollection services)
+        {
+            services.AddShapeRenderer();
+            services.AddScoped<IEmailTemplateService, ShapeBasedEmailTemplateService>();
+        }
+
+        public override void Configure(IApplicationBuilder app, IEndpointRouteBuilder routes, IServiceProvider serviceProvider)
+        {
+            // No need for anything here yet.
+        }
+    }
+}

FeatureIds.cs

@@ -9,6 +9,7 @@ public static class FeatureIds
         public const string Flows = FeatureIdPrefix + nameof(Flows);
         public const string ShapeTracing = FeatureIdPrefix + nameof(ShapeTracing);
         public const string Widgets = FeatureIdPrefix + nameof(Widgets);
+        public const string Emails = FeatureIdPrefix + nameof(Emails);
         public const string Security = FeatureIdPrefix + nameof(Security);
     }
 }

Manifest.cs

@@ -69,3 +69,14 @@
     Category = "Security",
     Description = "Adds a content type definition setting and authorization handler for richer security options."
 )]
+
+[assembly: Feature(
+    Id = Emails,
+    Name = "Lombiq Helpful Extensions - Emails",
+    Category = "Messaging",
+    Description = "Adds shape-based email template rendering and helpful email sending services.",
+    Dependencies = new[]
+    {
+        "OrchardCore.Email",
+    }
+)]

Readme.md

@@ -85,6 +85,37 @@ _contentDefinitionManager.AlterTypeDefinition("Page", type => type
 You can also enable it by going to the content type editor on the admin side and checking the _Strict Securable_ checkbox.
 
 
+### Emails and Email Templates
+
+#### Email Templates
+
+Provides a shape-based email template rendering service. The email templates are represented by email template IDs that are also used to identify the corresponding shape using the following pattern: `EmailTemplate__{EmailTemplateID}`. E.g., for the `ContactUs` email template you need to create a shape with the `EmailTemplate__ContactUs` shape type.
+
+In the email template shapes use the `Layout__EmailTemplate` as the `ViewLayout` to wrap it with a simple HTML layout.
+
+To extend the layout you can override the `EmailTemplate_LayoutInjections` shape and inject content to the specific zones provided by the layout to activate it in every email template. E.g.,
+
+```html
+<zone name="Footer">
+    Best,<br>
+    My Awesome Team
+</zone>
+```
+To add inline styles include:
+```html
+<zone name="Head">
+    <style>
+        /* CSS code... */
+    </style>
+</zone>
+```
+
+#### Deferred email sending
+
+Use the `ShellScope.Current.SendEmailDeferred()` for sending emails. It'll send emails after the shell scope has ended without blocking the request.
+
+
+
 ## Contributing and support
 
 Bug reports, feature requests, comments, questions, code contributions, and love letters are warmly welcome, please do so via GitHub issues and pull requests. Please adhere to our [open-source guidelines](https://lombiq.com/open-source-guidelines) while doing so.

Views/EmailTemplate.LayoutInjections.cshtml

@@ -0,0 +1 @@
+@* Override this shape to add generic injections email templates (e.g., header, footer, etc.). *@

Views/EmailTemplate.Title.cshtml

@@ -0,0 +1 @@
+@* Override this shape to add a title to the email templates. *@

Views/Layout-EmailTemplate.cshtml

@@ -0,0 +1,45 @@
+@{
+    const string blockName = "emailTemplate";
+}
+
+<!DOCTYPE html>
+<html lang="@Orchard.CultureName()">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width" initial-scale="1">
+    <!--[if !mso]>
+        <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <![endif]-->
+    <title>
+        <shape type="EmailTemplate_Title"></shape>
+    </title>
+
+    @await RenderSectionAsync("Head", required: false)
+
+    <shape type="EmailTemplate_LayoutInjections" prop-layoutModel="@Model"></shape>
+</head>
+<body>
+
+<span class="preheader" style="display: none; max-height: 0px; overflow: hidden;">
+    @await RenderSectionAsync("Preheader", required: false)
+</span>
+
+<div class="@(blockName)">
+    <div class="@(blockName)__header">
+        @await RenderSectionAsync("Header", required: false)
+    </div>
+
+    <div class="@(blockName)__content">
+        @await RenderSectionAsync("BeforeContent", required: false)
+        @await RenderBodyAsync()
+        @await RenderSectionAsync("AfterContent", required: false)
+    </div>
+
+    <div class="@(blockName)__footer">
+        @await RenderSectionAsync("Footer", required: false)
+    </div>
+</div>
+
+
+</body>
+</html>