Skip to content

About

Osysharp.EmailTemplates — an Osy# package. mail that looks designed — a layout with preview line, logo and footer, headings, text, buttons, pictures and receipt lines, in the app's own theme — and the mail blocks staff arrange in a mail's region.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

5 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Osysharp.EmailTemplates — mail that looks designed, rendered from data

Use case

Your app sends mail about something a person did: an order confirmation, a shipping notice, a refund, a code to redeem, a reminder. This package makes that mail look like it came from a designed product instead of a script — a branded page with a clear headline, the lines of a receipt with their amounts, one obvious button, and a footer with the sender's address — and it fills it from your data.

It renders on the server, in the app's own theme, into HTML every mail client lays out (tables, every style inline, no script, no web font) and a plain-text twin that says the same thing. It formats mail; it does not send it — hand the result to whatever sends your mail (Osysharp.Resend, or any provider).

A receipt rendered with Osysharp.EmailTemplates

A shop's receipt, photographed by osy test --pixels from this package's own tests.

Install and use

app Shop {
  use Osysharp.EmailTemplates@0;
  model "model/**/*.osy";
}

A mail is an [Email] component with a subject =>. Calling it from any function — a workflow step included — answers a RenderedEmail with Subject, Html and Text:

using Osysharp.EmailTemplates;

[Email]
public component OrderConfirmation(Order order) {
  subject => $"Your order {order.Reference}";
  render {
    EmailLayout("Grounds & Grapes", preview: $"Order {order.Reference} is reserved for you",
                address: "Storgatan 1, 111 22 Stockholm") {
      EmailHeading($"Thank you, {order.CustomerName}");
      EmailText("Your order is reserved and on its way to being packed.");
      EmailTable() {
        foreach (var line in order.Lines) {
          EmailRow($"{line.Quantity} × {line.Name}", Money(line.Price * line.Quantity), detail: line.Size);
        }
        EmailTotal("Total", Money(order.Total));
      }
      EmailButton("See your order", $"https://shop.example.com/orders/{order.Reference}");
    }
  }
}

void SendConfirmation(Order order) {
  var mail = OrderConfirmation(order);
  new ResendMailer { ApiKey = Secret.ResendApiKey, From = "Shop <shop@example.com>" }.Send(new EmailMessage {
    To = [order.Email], Subject = mail.Subject, Html = mail.Html, Text = mail.Text,
  });
}

What it ships

part what it draws
EmailLayout(brand, preview?, logo?, address?, unsubscribe?, footer?) { … } the frame: the app's own page in a 600-pixel column, with the brand (or its logo) at the top, the mail inside, and a footer with the sender's address and — for a mail a reader signed up to — an unsubscribe link
EmailHeading(text) the headline, in the theme's display face
EmailText(text) a paragraph; a line break is kept
EmailNote(text) small print in the muted colour
EmailButton(label, href) the one thing to do next — a button that is a link in every client, Outlook included
EmailImage(src, alt, width?) a picture by address; a path is sent as the app's absolute address
EmailCode(code) a code to type or read out — a gift code, a return code — large and spaced
EmailDivider() a rule
EmailTable() { … } a receipt's lines — EmailRows and an EmailTotal
EmailRow(label, value, detail?) one line: what it is (and a detail under it) and what it costs
EmailTotal(label, value) the line a receipt ends on, bold, under a rule

Every colour, size and face is a theme token (Colors.Primary, FontSize.Title, Radius.Md), and the renderer writes the app's value for each into the mail — so a shop whose brand is orange sends orange buttons.

The mail blocks — what staff arrange

A mail's words that staff own are a Region of blocks (use Osysharp.Blocks; in the app), arranged at the page desk (Osysharp.PageBuilder) like a page's — a draft, published, in each language, with the mail itself previewed beside it. The kit ships the everyday blocks, each an [Email] part marked [Block] whose words fill the mail's {placeholders}:

block staff fill in
EmailWords — Words a paragraph in Markdown
EmailHeadline — Heading and words a heading and a paragraph under it
EmailPicture — Picture a photograph (one the app ships, or an upload) and what it shows
EmailAction — Button what it says and where it goes
EmailQuote — Quote what somebody said, who, and one of the theme's grounds
EmailSmallPrint — Small print a quiet line at the foot
[Email]
public component Welcome(Member member) {
  subject => $"Welcome, {member.Name}";
  placeholders { member.name => member.Name; }
  render {
    EmailLayout("The Rowing Club") {
      Region("welcome", allow: [EmailWords, EmailPicture, EmailQuote], sample: WelcomeSample) {
        EmailWords(words: "Welcome aboard, **{member.name}**.");
      }
    }
  }
}

An app that arranges nothing uses them as ordinary parts and needs no Osysharp.Blocks.

Make it yours

Each part is an ordinary [Email] component, so a different button is a component of your own written the same way, over the platform's email atoms (Stack, Row, Box, Text, Link, Image, Divider, Spacer, Markdown, Preview). osy get EmailButton copies this one into your app to start from.

The reference: osy docs ui-email (the [Email] render target) and osy docs ui-email-templates-kit (this package).

Source

model/Parts.osy (the parts) and model/Blocks.osy (the mail blocks) — two files of Osy#.

Examples

Taken from this package's own tests, which compile and run on every release.

using Osysharp.Blocks;

[Test]
void the_code_s_arrangement_is_the_mail_until_staff_change_it() {
  var mail = ThanksMail(Ada("Ada"));
  Assert.Contains("Thank you, <strong>Ada</strong> — order <span style=\"white-space:nowrap;\">GG-2001</span> is on its way to being packed.", mail.Html);
  Assert.Contains("Thank you, Ada — order GG-2001 is on its way", mail.Text);
  // The block handed the sale from the mail: its lines.
  Assert.Contains("1 × Paper filters", mail.Text);
  Assert.Contains("29.00 kr", mail.Text);
  Assert.Equal(2, mail.Placeholders.Count);
  Assert.False(mail.IsPreview);
}

From tests/blocks.test.osy.

[Test]
void TheReceiptSaysWhatWasBought_InBothTheHtmlAndTheText() {
  var mail = SaleReceipt(ASale());
  Assert.Equal("Your receipt GG-1042", mail.Subject);
  foreach (var words in new List<string> { "Thank you, Ada", "2 × Ethiopia Yirgacheffe", "250 g", "178.00 kr",
                                            "1 × Paper filters", "29.00 kr", "Total", "207.00 kr", "See your order",
                                            "GIFT-7Q2K", "Questions? Reply to this mail." }) {
    Assert.Contains(words, mail.Text);
  }
  Assert.Contains("See your order: https://shop.example.com/orders/GG-1042", mail.Text);
  Assert.Contains("207.00&nbsp;kr", mail.Html);                 // an amount and its currency never part
}

From tests/receipt.test.osy.

using Osysharp.Blocks;

[Test]
void staff_words_published_in_the_region_are_the_mail_without_a_deploy() {
  var draft = EditRegion(MainVersion().Id, "thanks", "");
  Assert.Equal("", SaveBlockValue(WordsIn(draft), "en", new BlockValue { Name = "words", Text = "Welcome back, {customer.name}! We are on it." }));
  // A draft is nobody's mail yet.
  Assert.Contains("on its way to being packed", ThanksMail(Ada("Ada")).Text);
  Assert.Equal("", PublishRegion(draft));
  var mail = ThanksMail(Ada("Ada"));
  Assert.Contains("Welcome back, Ada! We are on it.", mail.Text);
  Assert.DoesNotContain("on its way to being packed", mail.Html);
}

From tests/blocks.test.osy.

Learn more

Licence

MIT — see LICENSE.

About

Osysharp.EmailTemplates — an Osy# package. mail that looks designed — a layout with preview line, logo and footer, headings, text, buttons, pictures and receipt lines, in the app's own theme — and the mail blocks staff arrange in a mail's region.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors