EmailTemplating-group-12 2.0.0

Email Templating Library - Documentation

1.0 Introduction

The Dynamic Email Template Library is a simple and flexible tool that lets developers easily create and send emails using customizable templates. With this library, you can define templates and fill them with dynamic content like user information, system data, or even receipts. It's built using object-oriented programming, which makes it easy to work with and extend for different use cases.

This library is perfect for developers who want to send personalized emails, whether it's for notifications, updates, receipts, or even marketing emails. It saves time by automating the process of creating email content, allowing you to focus on the logic and data behind your emails rather than worrying about formatting.

In short, this library helps you quickly set up dynamic email templates and send out tailored emails, like receipts or other personalized content, to each recipient with ease.

1.1 Installation

Download the NuGet package from the NuGet package manager, available in Visual Studio 2022. See here for the full release: https://www.nuget.org/packages/EmailTemplating-group-12/1.0.0

1.2 Framework structure:

EmailTemplating
├── Utility
│   ├── FunctionProcessor.cs
│   └── RegexReplacer.cs
├── TemplateBuilder.cs

2.0 Basic Usage

Initialize the TemplateBuilder class to get started. In this example we call it builder:

TemplateBuilder builder = new TemplateBuilder();

Create a .txt file containing the whole message, with placeholders. Placeholders are identified using these signs: [ PlaceholderName ]

Then create a string to store the placeholder data. This needs to be in Json format:

string jsonData = @"
{
  "Name": "Karen",
  "Phone number": "10000"
}";

Now you can call this method from TemplateBuilder using the .txt file path and the string you just made:

builder.GenerateEmailFromFile(string filePath, string jsonData)

Alternatively you can send the text directly as a string:

builder.GenerateEmail(string message, string jsonData)

2.1 Using C# objects instead of Json

You can create a C# object instead of a JSON string:

var messageToSend = @"Here is the sum of [numberList]: [!SumUpList! numberList]";
var numberListObjectData = new {
    var numberList = new List<string> {"12","90","83","32","9832"}
};
builder.GenerateEmail(message, numberListObjectData);

2.2 Using functions

A function is called like this: [!FunctionName! args]

Available functions:

• TwoDimensionalList: Takes two arrays as arguments.
• SumUpList: Takes an array of numbers as an argument.
• FormatCurrency: Takes a number and a currency type.
• TotalSumOfListAfterDiscount: Percentage discount and array of numbers.
• TotalNumberAfterDiscount: Percentage discount and a single number.
• RegisterFunction: Create custom functions.

Example:

string message = “[Sender] has sent you [!FormatCurrency! Amount Exchange].”;
string jsonData = @"
{
  "Sender": "John",
  "Amount": "460.30",
  "Exchange": "USD"
}";

Expected output: John has sent you $460.30.

2.3 Optional exception throwing

Use this method to disable exceptions:

templateBuilder.EnableOptionalExceptions(false);

When disabled, errors return placeholders like [Missing: key], [Invalid List Data], etc.

You can use the throwOnError parameter when defining custom functions to respect this setting.

3.0 Creating your own functions

Use the FunctionProcessor.RegisterFunction method:

FunctionProcessor.RegisterFunction("AddTwoNumbers", (args, data, throwOnError) => {
    var number1 = int.Parse(data[args[0]].GetString());
    var number2 = int.Parse(data[args[1]].GetString());
    return (number1 + number2).ToString();
});

3.1 A more complex example

string messageToSend = @"This function is called [name], and multiplies a value by two. [value] * 2 = [!TimesTwo! value]";

var myData = new {
    name = "TimesTwo",
    value = "50"
};

FunctionProcessor.RegisterFunction("TimesTwo", (args, data, throwOnError) => {
    if (args.Length != 1) {
        if (throwOnError)
            throw new ArgumentException("TimesTwo requires exactly 1 parameter.");
        return "[Invalid TimesTwo arguments]";
    }

    var number = data[args[0]].GetString();

    if (!double.TryParse(number, out double tall)) {
        if (throwOnError)
            throw new InvalidDataException("The number was not successfully parsed.");
        return "[Invalid value]";
    }
    return (tall * 2).ToString();
});

var templateBuilder = new TemplateBuilder();
string result = templateBuilder.GenerateEmail(messageToSend, myData);

4.0 API-reference

TemplateBuilder

• GenerateEmail: message and json data to RegexReplacer.
• GenerateEmailFromFile: Reads a template file.

RegexReplacer

• ProcessTemplate: Replaces placeholders and handles functions.

FunctionProcessor

• ProcessFunction: Dispatches the function based on arguments.
• GenerateTwoDimenionsalList: Combines lists into formatted string.
• SumUpList: Sums numeric values.
• ReadTemplateFromFile: Reads template.
• FormatCurrency: Formats value to currency.
• TotalSumOfListAfterDiscount: Discount on sum.
• TotalNumberAfterDiscount: Discount on single number.

Examples

string message = "Here's the price list:\n[!TwoDimensionalList! Products Prices]";
string jsonData = @"
{
  "Products": ["Milk", "Bread", "Eggs"],
  "Prices": ["20", "15", "30"]
}";
// Output: Milk 20 \n Bread 15 \n Eggs 30

string message = "The total is [!SumUpList! Items].";
string jsonData = @"
{
  "Items": ["100", "200", "50"]
}";
// Output: The total is 350.

string message = "After a discount, you only pay [!TotalNumberAfterDiscount! Discount Item].";
string jsonData = @"
{
  "Discount": "10",
  "Item": "100"
}";
// Output: After a discount, you only pay 90.