diff --git a/CHANGELOG.md b/CHANGELOG.md --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,9 @@ # Revision history for mjml-hamlet +## 0.1.0.1 -- 2026-10-31 + +* README: a worked example with screenshots of the rendered email. + ## 0.1.0.0 -- 2026-10-31 * First version. diff --git a/README.md b/README.md --- a/README.md +++ b/README.md @@ -3,26 +3,82 @@ [MJML](https://mjml.io) email templates written in Hamlet's syntax and checked at compile time. Rendering goes through the [`mjml`](https://github.com/kronor-io/mjml/tree/main/mjml) package, so there is no Node.js involved at build time or at runtime. For what MJML is and -a full example with screenshots, see the [repository README](https://github.com/kronor-io/mjml#readme). +what it is for, see the [repository README](https://github.com/kronor-io/mjml#readme). +An order confirmation: data goes in with `#{...}`, `$forall` repeats a row +per item, `$maybe` adds the tracking button only when there is a link, and +`^{footer}` embeds a piece shared by every email. + ```haskell +{-# LANGUAGE OverloadedRecordDot #-} {-# LANGUAGE QuasiQuotes #-} -import Text.Mjml.Hamlet (mjml, renderMjml) +import Data.Text (Text) +import Text.Mjml (MjmlError, Node) +import Text.Mjml.Hamlet (SafeUrl, mjml, renderMjml) -shipped :: Order -> Either MjmlError Text -shipped order = +data Order = Order + { reference :: Text + , customer :: Text + , items :: [Item] + , total :: Text + , trackingUrl :: Maybe SafeUrl + } + +data Item = Item {name :: Text, quantity :: Int, price :: Text} + +confirmation :: Order -> Either MjmlError Text +confirmation order = renderMjml [mjml| - - - Your order #{order.reference} is on its way - $forall line <- order.lines - #{line.name} × #{line.quantity} - $maybe url <- order.trackingUrl - Track it + + + Order #{order.reference} + Thanks for your order, #{order.customer} + + + + + + + + Thanks, #{order.customer}! + We have received order #{order.reference} and will tell you when it ships. + $forall item <- order.items + + + + #{item.quantity} × #{item.name} + + #{item.price} + + + + Total #{order.total} + $maybe url <- order.trackingUrl + Track your parcel + ^{footer} |] + +-- A piece shared by every email, embedded above with ^{footer}. +footer :: [Node] +footer = + [mjml| + + + + You are receiving this email because you placed an order with us. + |] ``` + +The result, on a desktop client and on a phone: + +![The order confirmation in a desktop mail client](https://raw.githubusercontent.com/kronor-io/mjml/eab39e4062d3a98055c8295a80d50395f502d6f8/docs/confirmation-desktop.png) + +![The same email on a phone: narrower, with item names and prices still side by side](https://raw.githubusercontent.com/kronor-io/mjml/eab39e4062d3a98055c8295a80d50395f502d6f8/docs/confirmation-mobile.png) + +`mj-group` keeps each item and its price side by side on the phone; plain +columns would stack. ## Syntax diff --git a/mjml-hamlet.cabal b/mjml-hamlet.cabal --- a/mjml-hamlet.cabal +++ b/mjml-hamlet.cabal @@ -1,6 +1,6 @@ cabal-version: 3.0 name: mjml-hamlet -version: 0.1.0.0 +version: 0.1.0.1 synopsis: MJML email templates in Hamlet syntax, checked at compile time description: A quasiquoter for MJML documents written with Hamlet's indentation-based