Email templates

Folio::EmailTemplate allows accounts to edit and customize the text inside of mailers coded to do so.

An email template consists of the following fields:

field	type	description
mailer	string	class name of mailer
action	string	name of the mailer action
subject_*	string	traco-translated email subject
body_html_*	text	traco-translated rich text content, editable via redactor in console
body_text_*	text	traco-translated plain text content
required_keywords	jsonb	array of keywords which must be included within body_html_* and body_text_* fields usually something like a password reset URL; can also be used in subject
optional_keywords	jsonb	array of keywords which can be used within body/subject fields usually something like user email, order payment URL; can also be used in subject
title	string	title used in console lists

Email templates are created by programmers and can only be viewed and edited in console (create/destroy actions are not implemented).

Translations

To translate subject/body fields, add more fields for the traco gem. No more work is needed (except for adding non-cs/en translations to the data file). Example migration:

class AddEmailTemplatesTranslations < ActiveRecord::Migration[6.0]
  def change
    add_column :folio_email_templates, :subject_cs, :string
    add_column :folio_email_templates, :body_html_cs, :text
    add_column :folio_email_templates, :body_text_cs, :text
  end
end

Adding email templates

To add an email template, add/update data/email_templates_data.yml in your repository and run the generator. Example format:

- mailer: MyProject::OrderMailer
  action: confirmed_notifier
  optional_keywords:
    - USER_EMAIL
    - ROOT_URL
    - DOMAIN
  required_keywords:
    - MY_PROJECT_ORDER_PAYMENT_URL
  title_cs: Objednávky - potvrzena
  title_en: Orders - confirmed
  subject_cs: Objednávka byla potvrzena
  subject_en: Your order was confirmed
  body_html_cs: |
    <p>Dobrý den,</p>
    <p>vaše objednávka bude vyřízena po zaplacení</p>
    <p class="redactor-component folio-redactor-button" data-redactor-type="button"><a class="btn btn-primary" href="{MY_PROJECT_ORDER_PAYMENT_URL}">Zaplatit objednávku</a></p>
  body_html_en: |
    <p>Hello!</p>
    <p>Your order will be dispatched after payment</p>
    <p class="redactor-component folio-redactor-button" data-redactor-type="button"><a class="btn btn-primary" href="{MY_PROJECT_ORDER_PAYMENT_URL}">Pay the order</a></p>
  body_text_cs: |
    Dobrý den,

    vaše objednávka bude vyřízena po zaplacení. Pro zaplacení použijte následující odkaz:

    {MY_PROJECT_ORDER_PAYMENT_URL}
  body_text_en: |
    Hello!

    Your order will be dispatched after payment. Pay the order using the following link:

    {MY_PROJECT_ORDER_PAYMENT_URL}

Seeding email templates

Email templates need to be seeded as they are just regular Rails models. To do so, use the folio:email_templates:idp_seed rake task:

$ rake folio:email_templates:idp_seed
Adding email template for Devise::Mailer#reset_password_instructions
Adding email template for Devise::Mailer#invitation_instructions
Adding email template for Folio::LeadMailer#notification_email
Adding email template for MyProject::OrderMailer#confirmed_notifier

The rake task reads data/email_templates_data.yml from your repository and lib/generators/folio/email_templates/templates/email_templates_data.yml from folio.

The rake task doesn't overwrite existing records, so you can use it to add new templates as your app grows (hence the idp_ - idempotent). As data/email_templates_data.yml is read first, you can use it to override folio default templates.

$ rake folio:email_templates:idp_seed
Skipping existing email template for Devise::Mailer#reset_password_instructions
Skipping existing email template for Devise::Mailer#invitation_instructions
Skipping existing email template for Folio::LeadMailer#notification_email
Skipping existing email template for MyProject::OrderMailer#confirmed_notifier

Mailer usage

If your mailer inherits from Folio::ApplicationMailer or includes the Folio::MailerEmailTemplates module, using the templates is as simple as using the email_template_mail method and passing data:

class MyProject::UserMailer < Folio::ApllicationMailer
  def confirmed_notifier(order)
    email_template_mail(
      USER_EMAIL: order.user.email,
      MY_PROJECT_ORDER_PAYMENT_URL: whatever_payment_url(order),
      ROOT_URL: root_url,
      DOMAIN: Folio::Site.instance.domain
    )
  end
end