Ogham ThymeLeaf v2 integration

Use ThymeLeaf v2 as template engine in Ogham

License	License The Apache License, Version 2.0
Categories	Categories Leaf Data Databases
GroupId	GroupId fr.sii.ogham
ArtifactId	ArtifactId ogham-template-thymeleaf-v2
Last Version	Last Version 3.0.0
Release Date	Release Date Jan 12, 2021
Type	Type jar
Description	Description Ogham ThymeLeaf v2 integration Use ThymeLeaf v2 as template engine in Ogham

Download ogham-template-thymeleaf-v2

Filename	Size
ogham-template-thymeleaf-v2-3.0.0.pom
ogham-template-thymeleaf-v2-3.0.0.jar	19 KB
ogham-template-thymeleaf-v2-3.0.0-sources.jar	16 KB
ogham-template-thymeleaf-v2-3.0.0-javadoc.jar	123 KB
Browse

How to add to project

Apache Maven

<!-- https://jarcasting.com/artifacts/fr.sii.ogham/ogham-template-thymeleaf-v2/ -->
<dependency>
    <groupId>fr.sii.ogham</groupId>
    <artifactId>ogham-template-thymeleaf-v2</artifactId>
    <version>3.0.0</version>
</dependency>

Gradle Groovy

// https://jarcasting.com/artifacts/fr.sii.ogham/ogham-template-thymeleaf-v2/
implementation 'fr.sii.ogham:ogham-template-thymeleaf-v2:3.0.0'

Gradle Kotlin

// https://jarcasting.com/artifacts/fr.sii.ogham/ogham-template-thymeleaf-v2/
implementation ("fr.sii.ogham:ogham-template-thymeleaf-v2:3.0.0")

Apache Buildr

'fr.sii.ogham:ogham-template-thymeleaf-v2:jar:3.0.0'

Apache Ivy

<dependency org="fr.sii.ogham" name="ogham-template-thymeleaf-v2" rev="3.0.0">
  <artifact name="ogham-template-thymeleaf-v2" type="jar" />
</dependency>

Groovy Grape

@Grapes(
@Grab(group='fr.sii.ogham', module='ogham-template-thymeleaf-v2', version='3.0.0')
)

Scala SBT

libraryDependencies += "fr.sii.ogham" % "ogham-template-thymeleaf-v2" % "3.0.0"

Leiningen

[fr.sii.ogham/ogham-template-thymeleaf-v2 "3.0.0"]

Dependencies

compile (1)

Group / Artifact	Type	Version
fr.sii.ogham : ogham-template-thymeleaf-common	jar	3.0.0

test (1)

Group / Artifact	Type	Version
fr.sii.ogham : ogham-test-utils	jar	3.0.0

Project Modules

There are no modules declared in this project.

Ogham

Table of Contents

Resources


site	site	site
code	code	code
showcase	showcase	showcase

Introduction

Existing libraries

Several libraries for sending email already exist:

These libraries help you send an email but if you want to use a templated content, you will have to manually integrate a template engine.

These libraries also provide only implementations based on Java Mail API. But in some environments, you might NOT want to send the email through SMTP but to use an external service (like SendGrid for example). Furthermore, those libraries are bound by design to frameworks or libraries that you might not want to use in your own context.

So, now you would want to find a sending library with a high level of abstraction to avoid binding issues with any template engine, design framework or sender service… Is email the only possible message type ? No, so why not sending SMS, Tweet or anything the same way ?

The Ogham module

This module is designed for handling any kind of message the same way. It also provides several implementations for the same message type. It selects the best implementation based on the classpath or properties for example. You can easily add your own implementation.

It also provides templating support and integrates natively several template engines. You can also add your own.

It is framework and library agnostic and provides bridges for common frameworks integration (Spring, JSF, …).

When using the module to send email based on an HTML template, the templating system let you design your HTML like a standard HTML page. It automatically transforms the associated resources (images, css files…) to be usable in an email context (automatic inline css, embed images…). You don’t need to write your HTML specifically for email.

Quick start

Standalone

pom.xml

...
    <dependency>
      <groupId>fr.sii.ogham</groupId>
      <artifactId>ogham-all</artifactId>
      <version>3.0.0</version>
    </dependency>
...

View code of an example pom.xml

build.gradle

...
dependencies {
    implementation 'fr.sii.ogham:ogham-all:3.0.0'
}

This will include:

Sending email through SMTP server (using Jakarta Mail, formely JavaMail)
Sending email through SendGrid
Sending SMS through SMPP server (using Cloudhopper)
Sending SMS through OVH SMS API
FreeMarker template engine available for building message contents
ThymeLeaf template engine available for building message contents

ℹ️	Java version compatibility Ogham is compatible with Java 8 and up to Java 15 (included).

With Spring Boot

Getting started with Spring Boot

pom.xml

...
        <dependency>
            <groupId>fr.sii.ogham</groupId>
            <artifactId>ogham-spring-boot-starter-all</artifactId>
            <version>3.0.0</version>
        </dependency>

...

build.gradle

...

dependencies {
    implementation 'fr.sii.ogham:ogham-spring-boot-starter-all:3.0.0'
...
}

This will include:

Sending email through SMTP server (using JavaMail)
Sending email through SendGrid
Sending SMS through SMPP server (using Cloudhopper)
Sending SMS through OVH SMS API
FreeMarker template engine available for building message contents
ThymeLeaf template engine available for building message contents
Support of Spring Boot auto-detection mechanism and configuration properties

You can combine Ogham with existing Spring Boot dependencies:

Ogham adapts itself to Spring Boot features

pom.xml
...
        <dependency>
            <groupId>fr.sii.ogham</groupId>
            <artifactId>ogham-spring-boot-starter-all</artifactId>    
            <version>3.0.0</version>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-freemarker</artifactId>   
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-thymeleaf</artifactId>    
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-mail</artifactId>         
        </dependency>
...
Add Ogham starter for Spring Boot to benefit for all Ogham features in your Spring Boot application.

Import FreeMarker starter as usual. Ogham will adapt to additional FreeMarker provided by Spring Boot.

Import Thymeleaf starter as usual. Ogham will adapt to additional Thymeleaf provided by Spring Boot.

Import Mail starter as usual. Ogham will adapt to use mail features provided by Spring Boot.
build.gradle
...

dependencies {
    implementation 'fr.sii.ogham:ogham-spring-boot-starter-all:3.0.0'   // (1)

    implementation 'org.springframework.boot:spring-boot-starter-freemarker'      // (2)
    implementation 'org.springframework.boot:spring-boot-starter-thymeleaf'       // (3)
    implementation 'org.springframework.boot:spring-boot-starter-mail'            // (4)
...
}
Add Ogham starter for Spring Boot to benefit for all Ogham features in your Spring Boot application.

Import FreeMarker starter as usual. Ogham will adapt to additional FreeMarker provided by Spring Boot.

Import Thymeleaf starter as usual. Ogham will adapt to additional Thymeleaf provided by Spring Boot.

Import Mail starter as usual. Ogham will adapt to use mail features provided by Spring Boot.

Ogham will auto-configure to use Spring Boot additions and support Spring Boot configuration properties like spring.mail.host for example.

Ogham is compatible with following Spring Boot versions:

1.4.x (currently automatically tested against 1.4.7.RELEASE, see note below)
1.5.x (currently automatically tested against 1.5.22.RELEASE)
2.1.x (currently automatically tested against 2.1.18.RELEASE)
2.2.x (currently automatically tested against 2.2.12.RELEASE)
2.3.x (currently automatically tested against 2.3.7.RELEASE)
2.4.x (currently automatically tested against 2.4.1.RELEASE)

ℹ️	Java version compatibility Ogham is compatible with Java 8 and up to Java 15 (included). However, Spring Boot may not be compatible with some Java versions (depending on Spring Boot version).

❗	Java 7 Java 7 support has been dropped since Ogham 3.0.0. Therefore, Ogham is no more tested with Spring Boot 1.3.x

❗

Spring Boot 1.4.x and WireMock

Latest WireMock versions are not compatible with Spring Boot 1.4.x. So if you are using Spring Boot 1.4.x, also using ogham-test-utils for writing tests and want to use WireMock in one of your test, you may experience ClassNotFoundException. This is due to different org.apache.httpcomponents versions.

In this case, just use a different version of WireMock by manually adding the dependency com.github.tomakehurst:wiremock-jre8:2.23.2:test. This will force to use a previous WireMock version that is compatible with Spring Boot 1.4.x.

Select the features you need

Importing ogham-all dependency or ogham-spring-boot-starter-all dependency is easy but may import dependencies that you don’t need. For example, you may only need FreeMarker but not Thymeleaf. Or you may only need to send emails through SMTP but never use SendGrid.

See how to select features.

Usage

ℹ️	All samples with templates are using ThymeLeaf as template engine. For FreeMarker samples, take a look at FreeMarker section.

Send Email

ℹ️	The samples are available in the sample-standard-usage sub-project. All samples shown bellow are using SMTP for sending email. See Sending email through SendGrid to know how to send email using SendGrid HTTP API.

First email using an existing SMTP server

❔	This sample demonstrates a basic usage of Ogham. This sample doesn’t show real improvement compared to other libraries. However, it is a the base for understanding the other samples.

Explanations & sample

This sample shows how to send a basic email.

The first lines configure the properties that will be used by the sender. Then you must create the service. You can use the MessagingBuilder to help you to create the service. Finally, the last line sends the email. The specified email is really basic. It only contains the subject, the textual content and the receiver address. The sender address is automatically added to the email by the service based on configuration properties.

Java

...
public class BasicSample {

    public static void main(String[] args) throws MessagingException {
        // configure properties (could be stored in a properties file or defined
        // in System properties)
        Properties properties = new Properties();
        properties.put("mail.smtp.host", "<your server host>");
        properties.put("mail.smtp.port", "<your server port>");
        properties.put("ogham.email.from.default-value", "<email address to display for the sender user>");
        // Instantiate the messaging service using default behavior and
        // provided properties
        MessagingService service = MessagingBuilder.standard()      // (1)
                .environment()
                    .properties(properties)                         // (2)
                    .and()
                .build();                                           // (3)
        // send the email using fluent API
        service.send(new Email()                                    // (4)
                        .subject("BasicSample")
                        .body().string("email content")
                        .to("[email protected]"));
    }

}

Use the standard builder (predefined behavior)
Register the custom properties
Create a MessagingService instance
Send an email with a subject and a simple body. The sender address is automatically set using ogham.email.from.default-value property

Source code of the sample.

The construction of the email is done using a fluent API in order to chain calls and to have a more readable code.

Properties are directly provided in the code. You can instead use a configuration file.

💡	Email address format Ogham supports the personal information in email address. The format is `personal <address>`. For example, the address with personal `Ogham Test <[email protected]>` will result in `[email protected]` as email address and `Ogham Test` as personal.

Use an HTML template for email body

❔	This sample demonstrates templating integration to easily externalize the email content from the source code.

Explanations & sample

This sample shows how to send an email with a content following a template engine language.

Java

...
public class HtmlTemplateSample {
    public static void main(String[] args) throws MessagingException {
        // configure properties (could be stored in a properties file or defined
        // in System properties)
        Properties properties = new Properties();
        properties.setProperty("mail.smtp.host", "<your server host>");
        properties.setProperty("mail.smtp.port", "<your server port>");
        properties.setProperty("ogham.email.from.default-value", "<email address to display for the sender user>");
        // Instantiate the messaging service using default behavior and
        // provided properties
        MessagingService service = MessagingBuilder.standard()                           // (1)
                .environment()
                    .properties(properties)                                              // (2)
                    .and()
                .build();                                                                // (3)
        // send the email using fluent API
        service.send(new Email()                                                         // (4)
                        .subject("HtmlTemplateSample")
                        .body().template("classpath:/template/thymeleaf/simple.html",    // (5)
                                                    new SimpleBean("foo", 42))           // (6)
                        .to("[email protected]"));
    }

    public static class SimpleBean {
...
    }
}

Use the standard builder (predefined behavior)
Register the custom properties
Create a MessagingService instance
Send an email with an explicit subject. The sender address is automatically set using ogham.email.from.default-value property
Indicate the path to the HTML template file (in the classpath)
Use any bean object for replacing variables in template

Source code of the sample.

ThymeLeaf template

<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">                <!--(1)-->
    <head>
        <meta charset="utf-8" />
    </head>
    <body>
        <h1 class="title" th:text="${name}"></h1>        <!--(2)-->
        <p class="text" th:text="${value}"></p>            <!--(3)-->
    </body>
</html>

Include the ThymeLeaf namespace
Use the name attribute value in the template
Use the value attribute value in the template

Source code of the HTML template

Using a template is straightforward. Instead of providing a string as body (using body().string(…)), you change to body().template(…, …). The template method requires two pieces of information:

The path to the template
The variables to evaluate in the template

The path to the template is a string that may contain a lookup prefix. The lookup prefix is used to indicate where to search the template (from file system, from classpath or anywhere else). Here we explicitly ask to load the template from classpath (using prefix classpath:). If no lookup is defined, classpath is used by default. See Resource resolution section for more information.

The variables are any object you are using in your application. No need to convert your object to a particular format. Directly use what you want.

Use HTML title as email subject

❔	This sample demonstrates that you can use a single source for both the body and the subject (same variables and same context). This is particularly useful for internationalization.

Explanations & sample

This sample is a variant of the previous one. It allows you to directly use the HTML title as subject of your email. It may be useful to use variables in the subject too, to mutualize the code and to avoid to create a new file or to use a different evaluation syntax or context just for one line.

Java

...
    public static void main(String[] args) throws MessagingException {
        // configure properties (could be stored in a properties file or defined
        // in System properties)
        Properties properties = new Properties();
        properties.setProperty("mail.smtp.host", "<your server host>");
        properties.setProperty("mail.smtp.port", "<your server port>");
        properties.setProperty("ogham.email.from.default-value", "<email address to display for the sender user>");
        // Instantiate the messaging service using default behavior and
        // provided properties
        MessagingService service = MessagingBuilder.standard()
                .environment()
                    .properties(properties)
                    .and()
                .build();
        // send the email using fluent API (do not specify subject)
        // subject is set to null to let automatic mechanism to read the title
        // of the HTML and use it as subject of your email
        service.send(new Email()                                                                    // (1)
                        .body().template("classpath:/template/thymeleaf/simpleWithSubject.html",
                                                    new SimpleBean("foo", 42))
                        .to("[email protected]"));
    }

    public static class SimpleBean {
...
    }
}

Subject is no more in Java code

Source code of the sample

ThymeLeaf template

<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
    <head>
        <title>Subject of the email - [[${name}]]</title>                <!--(1)-->
        <meta charset="utf-8" />
    </head>
    <body>
        <h1 class="title" th:text="${name}"></h1>
        <p class="text" th:text="${value}"></p>
    </body>
</html>

The subject is defined in the template and can use same evaluation context (SimpleBean).

ℹ️	The subject of the email will be `Subject of the email - Welcome foo !`

Source code of the HTML template

For text templates, the subject is automatically used (like for HTML title) if the first line starts with Subject: (spaces can be added after colon). Other lines are used as content of the email.

Java

...
public class TextTemplateWithSubjectSample {
    public static void main(String[] args) throws MessagingException {
        // configure properties (could be stored in a properties file or defined
        // in System properties)
        Properties properties = new Properties();
        properties.setProperty("mail.smtp.host", "<your server host>");
        properties.setProperty("mail.smtp.port", "<your server port>");
        properties.setProperty("ogham.email.from.default-value", "<email address to display for the sender user>");
        // Instantiate the messaging service using default behavior and
        // provided properties
        MessagingService service = MessagingBuilder.standard()
                .environment()
                    .properties(properties)
                    .and()
                .build();
        // send the email using fluent API (do not specify subject)
        // subject is set to null to let automatic mechanism to read the title
        // of the first line if prefixed by "Subject:" and use it as subject of your email
        service.send(new Email()                                                                       // (1)
                        .body().template("classpath:/template/freemarker/simpleWithSubject.txt.ftl",
                                                    new SimpleBean("foo", 42))
                        .to("[email protected]"));
    }

    public static class SimpleBean {
...
    }
}

Subject is no more in Java code

Source code of the sample

Text template

Subject: Welcome ${name} !
Hello ${name},

Foo bar ${value}

ℹ️	The subject of the email will be `Welcome foo !`

Source code of the text template

HTML body with CSS and images

❔	This sample demonstrates that you can reference resources like CSS files or images as usual without worrying about technical concerns and limitations for such resources in email context.

Explanations & sample

When you develop a Web application, you can use HTML for the content and CSS for layout and theming. HTML and CSS can use images to make a beautiful Web page. Each concern is separated in a different file. This is a good practice.

However, writing an HTML email is totally different. Indeed, email clients are not as evolved as Web browsers. Even worse, some clients disable some features on purpose (like GMail that prevents using style tag). To make an email work on several clients, you should follow these rules:

<img> tags that use local images must be embedded
Use XHTML instead of HTML
Remove HTML comments (except conditional comments used to target Outlook)
Add border=0 on all images to avoid an ugly border
Do not write shortcut CSS values (padding: 4px 4px 4px 4px; instead of padding: 4px)
Padding is not supported on some clients so you must use margins instead (adding a parent just for the layout)
Background images on body should be moved on another node
CSS3 properties are not supported
Images must have alt attribute
…

There are many other rules but the developer should not be constrained and should be able to write its HTML and CSS like as usual in Web browsers. Ogham simplifies image and CSS integration and is able to partially rewrite the HTML.

Java

...
    public static void main(String[] args) throws MessagingException {
        // configure properties (could be stored in a properties file or defined
        // in System properties)
        Properties properties = new Properties();
        properties.setProperty("mail.smtp.host", "<your server host>");
        properties.setProperty("mail.smtp.port", "<your server port>");
        properties.setProperty("ogham.email.from.default-value", "<email address to display for the sender user>");
        // Instantiate the messaging service using default behavior and
        // provided properties
        MessagingService service = MessagingBuilder.standard()
                .environment()
                    .properties(properties)
                    .and()
                .build();
        // send the email using fluent API
        // Note that the extension of the template is not given. This version
        // automatically takes the provided path and adds the '.html' extension
        // for the HTML template and '.txt.ftl' for text template
        service.send(new Email()
                        .body().template("classpath:/template/withImagesAndCss/resources",    // (1)
                                                            new SimpleBean("foo", 42))        // (2)
                        .to("[email protected]"));
    }

    public static class SimpleBean {
...
    }
}

The path to the templates (/template/withImagesAndCss/resources.html for the main body, /template/withImagesAndCss/resources.txt.ftl for the text alternative)
The template context

Source code of the sample

ThymeLeaf template

<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>HtmlWithImagesAndCssTemplateSample</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<link href="css/layout.css" rel="stylesheet" />                                                            <!--(1)-->
<link href="css/theme.css" rel="stylesheet" />                                                            <!--(2)-->
</head>
<body>
    <header>
        <img src="images/h1.gif" alt="Creating Email Magic" />                                            <!--(3)-->
    </header>
    <div class="content">
        <span th:text="${name}">name</span>
        <p th:text="${value}">value</p>
        <div class="left">
            <img src="images/left.gif" data-inline-image="base64" />                                    <!--(4)-->
            <p class="text">
                Lorem ipsum dolor sit amet, consectetur adipiscing elit. In
                tempus adipiscing felis, sit amet blandit ipsum volutpat sed. Morbi
                porttitor, eget accumsan dictum, nisi libero ultricies ipsum, in
                posuere mauris neque at erat.
            </p>
        </div>
        <div class="right">
            <img src="images/right.gif" data-inline-image="attach" />                                    <!--(5)-->
            <p class="text">
                Lorem ipsum dolor sit amet, consectetur adipiscing elit. In
                tempus adipiscing felis, sit amet blandit ipsum volutpat sed. Morbi
                porttitor, eget accumsan dictum, nisi libero ultricies ipsum, in
                posuere mauris neque at erat.
            </p>
        </div>
    </div>
    <footer>
        <div class="social">
            <a href="http://www.twitter.com/">
                <img src="images/tw.gif" alt="Twitter" />                                                <!--(6)-->
            </a>
            <a href="http://www.facebook.com/">
                <img src="images/fb.gif" alt="Facebook" data-inline-image="skip" />                        <!--(7)-->
            </a>
        </div>
        <div class="sender-info">
            &reg; Someone, somewhere 2013<br />
            <a href="#" class="white" data-inline-styles="skip">Unsubscribe</a> to this newsletter instantly    <!--(8)-->
        </div>
    </footer>
</body>
</html>

The CSS is parsed by Ogham and applied directly on the HTML (using style attribute)
The CSS is parsed by Ogham and applied directly on the HTML (using style attribute). The CSS may contain rules that override some rules of other CSS files (like in a browser)
The image is automatically embedded (the path is replaced by a Content-ID (or CID) and the image is attached to the email using ContentDisposition.INLINE with the Content-ID header). The content type is automatically determined
The image is converted to a base64 string. The src attribute of the image is updated using data URI scheme. The content type is automatically determined
Same as <3>
Same as <3>
The image is not inlined by Ogham. This can be useful to embed it manually.

Source code of the HTML template

CSS

layout.css

body {
    margin: 10px auto 30px auto;
    width: 600px;
}

header {
    padding: 40px 30px;
}

header img {
    display: block;
    margin: auto;
}


.content {
    padding: 40px 30px;
}

.left,
.right {
    width: 250px;
    display: inline-block;
}

.left {
    margin-right: 36px;
}

footer {
    padding: 30px;
}

footer .sender-info,
footer .social {
    text-align: center;
}
footer .social a {
    display: inline-block;
}
footer .sender-info {
    margin-top: 20px;
}

theme.css

body {
    border: 1px solid #ccc;
}

header {
    background: #70bbd9;
}

.content {
    text-align: justify;
}

footer {
    color:#ffffff;
    font-family:Arial, sans-serif;
    font-size:14px;
    background: #ee4c50;
}

footer .social a {
    color:#ffffff;
}

.white {
    color: #fff;
}

Sent HTML

Here is the list of supported transformations:

✓ <img> tags that use local images are embedded (using cid reference)
✓ <img> tags that use local images are embedded (using base64 data URI)
✓ Inline CSS rules using style attribute
✓ background images that use local images are embedded (using cid reference)
✓ background images that use local images are embedded (using base64 data URI)
❏ Use XHTML instead of HTML
❏ Tables used for layout explicitly set default values
❏ Remove HTML comments (except conditional comments used to target Outlook)
❏ Add border=0 on all images to avoid an ugly border
❏ Do not write shortcut CSS values (padding: 4px 4px 4px 4px; instead of padding: 4px)
❏ Padding is not supported on some clients so you must use margins instead (adding a parent just for the layout)
❏ Background images on body should be moved on another node
❏ Images must have alt attribute

A working preview of the HTML body (text alternative)

❔	Have you never received an email with strange characters in a textual preview ? This sample demonstrates how to easily provide a text alternative that is used as textual preview.

Explanations & sample

Sending an email with HTML content and text content might be really important, at least for smartphones. When a smartphone receives an email, it displays the sender, the subject and also a preview of the message, using the text alternative. If the message is only HTML, the preview might be unreadable.

Java

...
public class HtmlAndTextSample {
    private static String html = "<!DOCTYPE html>"
                                + "<html>"
                                +     "<head><meta charset=\"utf-8\" /></head>"
                                +     "<body>"
                                +         "<h1 class=\"title\">Hello World</h1>"
                                +         "<p class=\"text\">Foo bar</p>"
                                +     "</body>"
                                + "</html>";
    private static String text = "Hello World !\r\n"
                                + "Foo bar";

    public static void main(String[] args) throws MessagingException {
        // configure properties (could be stored in a properties file or defined
        // in System properties)
        Properties properties = new Properties();
        properties.put("mail.smtp.host", "<your server host>");
        properties.put("mail.smtp.port", "<your server port>");
        properties.put("ogham.email.from.default-value", "<email address to display for the sender user>");
        // Instantiate the messaging service using default behavior and
        // provided properties
        MessagingService service = MessagingBuilder.standard()
                .environment()
                    .properties(properties)
                    .and()
                .build();
        // send the email using the fluent API
        service.send(new Email()
                        .subject("HtmlAndTextSample")
                        .text().string(text)              // (1)
                        .html().string(html)              // (2)
                        .to("[email protected]"));
    }
}

Explicitly set the textual content (used as alternative body). The alternative body is used when the email client doesn’t support HTML or as a preview of the email.
Explicitly set the HTML content (used as main body)

ℹ️	The call order between `text()` and `html()` doesn’t matter (unlike using `.content(new MultiContent(…))`).

ℹ️	The underlying `Content` is a `MultiContent`.

Source code of the sample

Obviously, you can use templates too. Even better, the following sample shows the shorthand version that avoids specifying twice the path to the templates (a single path without extension for both HTML and text template files).

Java

...
public class HtmlAndTextTemplateSample {
    public static void main(String[] args) throws MessagingException {
        // configure properties (could be stored in a properties file or defined
        // in System properties)
        Properties properties = new Properties();
        properties.setProperty("mail.smtp.host", "<your server host>");
        properties.setProperty("mail.smtp.port", "<your server port>");
        properties.setProperty("ogham.email.from.default-value", "<email address to display for the sender user>");
        // Instantiate the messaging service using default behavior and
        // provided properties
        MessagingService service = MessagingBuilder.standard()
                .environment()
                    .properties(properties)
                    .and()
                .build();
        // send the email using fluent API
        // Note that the extension of the template is not given. This version
        // automatically takes the provided path and adds the '.html' extension
        // for the HTML template and '.txt' for text template
        service.send(new Email()
                        .subject("HtmlAndTextTemplateSample")
                        .body().template("classpath:/template/thymeleaf/simple",          // (1)
                                                            new SimpleBean("foo", 42))    // (2)
                        .to("[email protected]"));
    }

    public static class SimpleBean {
...
    }
}

The body contains two parts (main body and alternative body) because there are two templates (one for HTML located at /template/thymeleaf/simple.html and one for text located at /template/thymeleaf/simple.txt). Only a single path is specified for both template files (without extension).
The object used for evaluation as usual when using templates (same object used for both HTML and text)

ℹ️	The underlying `Content` is a `MultiTemplateContent`.

Source code of the sample

Text template

Text template located in src/main/resources/template/thymeleaf/simple.txt

[[${name}]] [[${value}]]

Source code of the text template

HTML template

HTML template located at src/main/resources/template/thymeleaf/simple.html

<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">                <!--(1)-->
    <head>
        <meta charset="utf-8" />
    </head>
    <body>
        <h1 class="title" th:text="${name}"></h1>        <!--(2)-->
        <p class="text" th:text="${value}"></p>            <!--(3)-->
    </body>
</html>

Source code of the HTML template

Ogham will automatically determine file extensions to append according to the kind of message you are sending. For email, Ogham will search a HTML and a text file by default:

Using ThymeLeaf, the file extensions are .html and .txt (configurable).
Using FreeMarker, Ogham will search files with extensions .html.ftl and .txt.ftl (configurable).

If you are using body() (or explicitly using content(new MultiTemplateContent(…))) and you only provide one template (only HTML for example). Ogham will not fail by default (configurable). Therefore, you can start your code with only a HTML template and add the text template later when you need it. That way, your Java code doesn’t require any change.

It is possible to mix templates in the same application. Even better, you can use a template engine that is better suited for HTML like Thymeleaf and FreeMarker that is better for textual version for the same email. Just write your templates with the engine you want.

Java

...
public class HtmlAndTextMixedTemplateEnginesSample {
    public static void main(String[] args) throws MessagingException {
        // configure properties (could be stored in a properties file or defined
        // in System properties)
        Properties properties = new Properties();
        properties.setProperty("mail.smtp.host", "<your server host>");
        properties.setProperty("mail.smtp.port", "<your server port>");
        properties.setProperty("ogham.email.from.default-value", "<email address to display for the sender user>");
        // Instantiate the messaging service using default behavior and
        // provided properties
        MessagingService service = MessagingBuilder.standard()
                .environment()
                    .properties(properties)
                    .and()
                .build();
        // send the email using fluent API
        // Note that the extension of the template is not given. This version
        // automatically takes the provided path and adds the '.html' extension
        // for the HTML template and '.txt.ftl' for text template
        service.send(new Email()
                        .subject("HtmlAndTextMixedTemplateEnginesSample")
                        .body().template("classpath:/template/mixed/simple",                // (1)
                                                            new SimpleBean("foo", 42))      // (2)
                        .to("[email protected]"));
    }

    public static class SimpleBean {
...
    }
}

The body contains two parts (main body and alternative body) because there are two templates (one for HTML located at /template/thymeleaf/simple.html and one for text located at /template/thymeleaf/simple.txt.ftl). Only a single path is specified for both template files (without extension). The HTML template uses Thymeleaf while the text template uses FreeMarker.
The object used for evaluation as usual when using templates (same object used for both HTML and text)

Source code of the sample

Text template

Text template located in src/main/resources/template/mixed/simple.txt.ftl

${name} ${value}

Source code of the text template

HTML template

HTML template located at src/main/resources/template/mixed/simple.html

<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
    <head>
        <meta charset="utf-8" />
    </head>
    <body>
        <h1 class="title" th:text="${name}"></h1>
        <p class="text" th:text="${value}"></p>
    </body>
</html>

Source code of the HTML template

You can notice that the Java code has not changed at all (only the path for the sample). The aim is to use the template engine that best suits your needs.

Attach files to the email

❔	This sample demonstrates how to send files with the email.

Explanations & sample

Java

...
    public static void main(String[] args) throws MessagingException, IOException {
        // configure properties (could be stored in a properties file or defined
        // in System properties)
        Properties properties = new Properties();
        properties.put("mail.smtp.host", "<your server host>");
        properties.put("mail.smtp.port", "<your server port>");
        properties.put("ogham.email.from.default-value", "<email address to display for the sender user>");
        // Instantiate the messaging service using default behavior and
        // provided properties
        MessagingService service = MessagingBuilder.standard()
                .environment()
                    .properties(properties)
                    .and()
                .build();
        // send the email using fluent API
        service.send(new Email()
                        .subject("WithAttachmentSample")
                        .body().string("content of the email")
                        .to("[email protected]")
                        .attach().resource("classpath:/attachment/test.pdf")            // (1)
                        .attach().stream("from-stream.pdf", loadInputStream()));        // (2)
    }

    private static InputStream loadInputStream() {
        return WithAttachmentSample.class.getResourceAsStream("/attachment/test.pdf");
    }
}

Attach a PDF file that exists in the classpath to the email. The name of the attachment uses the name of the file
Use an InputStream and name the attachment

Source code of the sample

Attaching a file to the email is quite simple. You just need to provide the path to the file. The file is loaded from classpath but could also be loaded from file system or anywhere else (see resource resolution section). In case you are using a file, the name of the attachment displayed in the email is automatically determined (test.pdf in the example).

It is often not possible to handle files directly. In that case you will use InputStream or byte[]. In that case, you need to name the attachment explicitly.

In both cases, the mimetype is automatically determined (application/pdf in this case). Mimetype is really important to ensure that the recipient(s) will be able to download or view the files correctly. It is possible to explicitly set the content type of the attachment if the automatic behavior doesn’t fit your needs.

The file content is linked to the email using ContentDisposition.ATTACHMENT.

❗	If you are using `InputStream`, you need to close the stream after sending the email.

💡	You can also add a custom description for any attachment but in this case use `Attachment` class.

💡

You can link a file to the email body using embed() instead of attach(). To make the link, the email body must contain an explicit reference using a Content-ID (or CID). The linked attachment must provide the Content-ID header with the same CID (automatically set by Ogham). The embedded attachment disposition is automatically set to ContentDisposition.INLINE.

Other email features

See user guide to read about the many other features.

Send SMS

ℹ️

The samples are available in the sample-standard-usage sub-project.

All samples shown bellow are using SMPP for sending SMS. The SMPP protocol is the standard way to send SMS. Only a subset of SMPP properties are used in following samples. The whole list of SMPP properties is available in advanced configuration.

See Sending SMS through OVH to know how to send SMS using OVH HTTP API.

First SMS using an existing SMPP server

❔	This sample demonstrates a basic usage of Ogham for sending SMS. It is a the base for understanding the other samples.

Explanations & sample

This sample defines two properties mandatory (system ID and password) by this protocol in order to use it.

Java

...
public class BasicSample {
    public static void main(String[] args) throws MessagingException {
        // configure properties (could be stored in a properties file or defined
        // in System properties)
        Properties properties = new Properties();
        properties.setProperty("ogham.sms.smpp.host", "<your server host>");                                 // (1)
        properties.setProperty("ogham.sms.smpp.port", "<your server port>");                                 // (2)
        properties.setProperty("ogham.sms.smpp.system-id", "<your server system ID>");                       // (3)
        properties.setProperty("ogham.sms.smpp.password", "<your server password>");                         // (4)
        properties.setProperty("ogham.sms.from.default-value", "<phone number to display for the sender>");  // (5)
        // Instantiate the messaging service using default behavior and
        // provided properties
        MessagingService service = MessagingBuilder.standard()                                               // (6)
                .environment()
                    .properties(properties)                                                                  // (7)
                    .and()
                .build();                                                                                    // (8)
        // send the sms using fluent API
        service.send(new Sms()                                                                               // (9)
                        .message().string("sms content")
                        .to("+33752962193"));
    }

}

Configure the SMPP server host
Configure the SMPP server port
The SMPP system ID
The SMPP password
The phone number of the sender
Use the standard builder (predefined behavior)
Register the custom properties
Create a MessagingService instance
Send a SMS with a simple message. The sender phone number is automatically set using ogham.sms.from.default-value property

Source code of the sample.

The construction of the SMS is done using a fluent API in order to chain calls and to have a more readable code.

Properties are directly provided in the code. You can instead use a configuration file.

Use a template for SMS content

❔	This sample demonstrates templating integration to easily externalize the SMS content from the source code.

Explanations & sample

This sample shows how to send a SMS with a content following a template engine language.

Java

...
public class TemplateSample {
    public static void main(String[] args) throws MessagingException {
        // configure properties (could be stored in a properties file or defined
        // in System properties)
        Properties properties = new Properties();
        properties.setProperty("ogham.sms.smpp.host", "<your server host>");
        properties.setProperty("ogham.sms.smpp.port", "<your server port>");
        properties.setProperty("ogham.sms.smpp.system-id", "<your server system ID>");
        properties.setProperty("ogham.sms.smpp.password", "<your server password>");
        properties.setProperty("ogham.sms.from.default-value", "<phone number to display for the sender>");
        // Instantiate the messaging service using default behavior and
        // provided properties
        MessagingService service = MessagingBuilder.standard()                              // (1)
                .environment()
                    .properties(properties)                                                 // (2)
                    .and()
                .build();                                                                   // (3)
        // send the sms using fluent API
        service.send(new Sms()                                                              // (4)
                        .message().template("classpath:/template/thymeleaf/simple.txt",     // (5)
                                                    new SimpleBean("foo", 42))              // (6)
                        .to("+33752962193"));
    }

    public static class SimpleBean {
...
    }
}

Use the standard builder (predefined behavior)
Register the custom properties
Create a MessagingService instance
Send a SMS with message that comes from the evaluated template. The sender address is automatically set using ogham.sms.from.default-value property
Indicate the path to the template file (in the classpath)
Use any bean object for replacing variables in template

Source code of the sample.

ThymeLeaf template

[[${name}]] [[${value}]]

Source code of the template

Using a template is straightforward. Instead of providing a string content (using .message().string(…)), you call .message().template(…, …). The template method requires two pieces of information:

The path to the template
The variables to evaluate in the template

The path to the template is a string with a lookup prefix. The lookup prefix is used to indicate where to search the template (from file system, from classpath or anywhere else). Here we explicitly ask to load the template from classpath (using prefix classpath:). If no lookup is defined, classpath is used by default. See Resource resolution section for more information.

The variables are any object you are using in your application. No need to convert your object to a particular format. Directly use what you want.

Send a long SMS

❔	This sample demonstrates that you don’t have to handle these kind of technical concerns.

Explanations & sample

As you may know, SMS stands for Short Message Service. Basically, the messages are limited to a maximum of 160 characters if character encoding is using 7bits. Using a 8-bit character encoding decreases the limit to 140 characters and 70 characters for a 16-bit encoding. If needed, the library will split your messages into several parts the right way to be recomposed by clients later (according to the message encoding). Therefore, you don’t need to handle the split of messages in your code:

Java

...
public class LongMessageSample {
    public static void main(String[] args) throws MessagingException {
        // configure properties (could be stored in a properties file or defined
        // in System properties)
        Properties properties = new Properties();
        properties.setProperty("ogham.sms.smpp.host", "<your server host>");
        properties.setProperty("ogham.sms.smpp.port", "<your server port>");
        properties.setProperty("ogham.sms.smpp.system-id", "<your server system ID>");
        properties.setProperty("ogham.sms.smpp.password", "<your server password>");
        properties.setProperty("ogham.sms.from.default-value", "<phone number to display for the sender>");
        // Instantiate the messaging service using default behavior and
        // provided properties
        MessagingService service = MessagingBuilder.standard()
                .environment()
                    .properties(properties)
                    .and()
                .build();
        String longMessage = "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad "
                            + "minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehender"
                            + "it in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui o"
                            + "fficia deserunt mollit anim id est laborum.";
        // send the sms using fluent API
        service.send(new Sms()
                        .message().string(longMessage)
                        .to("+33752962193"));
    }

}

Source code of the sample.

ℹ️

Message length depends on encoding

Larger content (concatenated SMS, multipart or segmented SMS, or "long SMS") can be sent using multiple messages, in which case each message will start with a User Data Header (UDH) containing segmentation information. Since UDH is part of the payload, the number of available characters per segment is lower: 153 for 7-bit encoding, 134 for 8-bit encoding and 67 for 16-bit encoding. The receiving handset is then responsible for reassembling the message and presenting it to the user as one long message. While the standard theoretically permits up to 255 segments, 6 to 8 segment messages are the practical maximum.

ℹ️	Default encoding By default, Ogham sends the SMS using 8-bit encoding.

Other SMS features

Ogham provides many other features.

Testing

Include test utilities

Getting started

Add ogham-test-utils dependency to your pom.xml
<dependency>
    <groupId>fr.sii.ogham</groupId>
    <artifactId>ogham-test-utils</artifactId>
    <version>3.0.0</version>
    <scope>test</scope>
</dependency>
View code of an example pom.xml
Add ogham-test-utils to your build.gradle
dependencies {
    testImplementation 'fr.sii.ogham:ogham-test-utils:3.0.0'
}

This will include:

JUnit to run tests (JUnit 4 and Junit 5)
Mockito for mocking Java code
Hamcrest for assertions
GreenMail for mocking a SMTP server
jSMPP for mocking a SMPP server
WireMock for mocking HTTP server
Spockframework for writing very very readable unit tests
and some utilities that may be useful

💡	You can configure Eclipse to provide autocompletion for static imports.

Testing emails

Explanations & sample

To test your application emails, you can start a local SMTP server. You can then use Ogham to make assertions on your email (right recipients, right sender, right body…). Ogham uses GreenMail as local SMTP server.

Java

...
public class EmailTestSample {
    private MessagingService oghamService;

    @Rule
    public final GreenMailRule greenMail = new GreenMailRule(SMTP);              // (1)

    @Before
    public void setUp() throws IOException {
        oghamService = MessagingBuilder.standard()
                .environment()
                    .properties()
                        .set("ogham.email.from.default-value", "Sender Name <[email protected]>")
                        .set("mail.smtp.host", SMTP.getBindAddress())            // (2)
                        .set("mail.smtp.port", String.valueOf(SMTP.getPort()))   // (3)
                        .and()
                    .and()
                .build();
    }

    @Test
    public void simple() throws MessagingException, javax.mail.MessagingException {
        // @formatter:off
        oghamService.send(new Email()
                                .subject("Simple")
                                .body().string("string body")
                                .to("Recipient Name <[email protected]>"));
        assertThat(greenMail).receivedMessages()                                 // (4)
            .count(is(1))                                                        // (5)
            .message(0)                                                          // (6)
                .subject(is("Simple"))                                           // (7)
                .from()
                    .address(hasItems("[email protected]"))                     // (8)
                    .personal(hasItems("Sender Name")).and()                     // (9)
                .to()
                    .address(hasItems("[email protected]"))                       // (10)
                    .personal(hasItems("Recipient Name")).and()                  // (11)
                .body()
                    .contentAsString(is("string body"))                          // (12)
                    .contentType(startsWith("text/plain")).and()                 // (13)
                .alternative(nullValue())                                        // (14)
                .attachments(emptyIterable());                                   // (15)
        // @formatter:on
    }
}

Declare and initialize the GreenMail JUnit rule to start a local SMTP server
Get the local SMTP server host address and configure Ogham to use this value
Get the local SMTP server port and configure Ogham to use this value
Entry point for declaring assertion on received emails using a fluent API
Assert that one and only one email has been received
Access the first received message for declaring assertions for that message using fluent API
Assert that the subject of the first message is exactly Simple string
Assert that the sender email address is exactly [email protected]
Assert that the sender name is exactly Sender Name
Assert that the recipient email address is exactly [email protected]
Assert that the recipient name is exactly Recipient Name
Assert that the body of the received email is exactly string body
Assert that the mimetype of the body of the received email starts with text/plain
Assert that received email has no alternative content
Assert that received email has no attachment

Source code of the sample.

Testing SMS

Explanations & sample

To test your application SMS, you can start a local SMPP server. You can then use Ogham to make assertions on you SMS (recipient phone number, sender phone number and message). Ogham uses jSMPP as local SMPP server.

Java

...
public class SmsTestSample {
    private MessagingService oghamService;

    @Rule
    public final SmppServerRule<SubmitSm> smppServer = new JsmppServerRule();    // (1)

    @Before
    public void setUp() throws IOException {
        oghamService = MessagingBuilder.standard()
                .environment()
                    .properties()
                        .set("ogham.sms.from.default-value", "+33603040506")
                        .set("ogham.sms.smpp.host", "localhost")                 // (2)
                        .set("ogham.sms.smpp.port", smppServer.getPort())        // (3)
                        .and()
                    .and()
                .build();
    }

    @Test
    public void simple() throws MessagingException {
        // @formatter:off
        oghamService.send(new Sms()
                            .message().string("sms content")
                            .to("0601020304"));
        assertThat(smppServer).receivedMessages()                                // (4)
            .count(is(1))                                                        // (5)
            .message(0)                                                          // (6)
                .content(is("sms content"))                                      // (7)
                .from()
                    .number(is("+33603040506"))                                  // (8)
                    .and()
                .to()
                    .number(is("0601020304"));                                   // (9)
        // @formatter:on
    }
}

Declare and initialize the JUnit rule that encapsulates jSMPP for starting a local SMPP server in tests (you can set a different port than the default one)
Configure Ogham to use localhost for SMPP host
Get the local SMPP server port and configure Ogham to use this value
Entry point for declaring assertion on received SMS using a fluent API
Assert that one and only one SMS has been received
Access the first received message for declaring assertions for that message using fluent API
Assert that the received message text is exactly sms content
Assert that the sender phone number is +33603040506
Assert that the recipient phone number is 0601020304

Source code of the sample.

More testing features

Ogham provides many other tool features:

Advanced configuration

See advanced configuration in full documentation

Extend

See how to extend Ogham in full documentation

Tips

See tips in full documentation

Support developer

I am currently the single developer on this project for several years. I have many ideas for this project to ease other developer work.

You can help me by either contributing or by making a donation.

Thank you !

Groupe SII

Versions

Version
3.0.0 Jan 12, 2021

Ogham ThymeLeaf v2 integration

License

Categories

GroupId

ArtifactId

Last Version

Release Date

Type

Description

Download ogham-template-thymeleaf-v2

How to add to project

Dependencies

compile (1)

test (1)

Project Modules

Ogham

Resources

Introduction

Existing libraries

The Ogham module

Quick start

Standalone

With Spring Boot

Select the features you need

Usage

Send Email

First email using an existing SMTP server

Use an HTML template for email body

Use HTML title as email subject

HTML body with CSS and images

A working preview of the HTML body (text alternative)

Attach files to the email

Other email features

Send SMS

First SMS using an existing SMPP server

Use a template for SMS content

Send a long SMS

Other SMS features

Testing

Include test utilities

Testing emails

Testing SMS

More testing features

Advanced configuration

Extend

Tips

Support developer

Groupe SII

Versions