Skip to main content

Email Templates

This guide provides all the necessary information for creating email templates for the plugin, focusing on required files, available data, and practical examples.

For detailed information on organizing templates, refer to the File Structure Documentation.

Templates are essential for defining the emails sent to recipients and form submitters. At least one plain text file (mail.text.php) is required for each email form. If a reply.text.php file exists, it will enable automated responses to the submitter.

HTML templates are optional but can be included to provide richer email formatting. When both plain text and HTML templates are available, the plugin automatically generates multipart emails.

Data Available in Templates

1. Form Data ($form)

Contains the user-submitted form data. Certain system fields (e.g., timestamp, csrf, submit, gdpr) are automatically excluded.

For example:

<?= $form->name() ?> // Outputs the value of the 'name' field
<?= $form->email() ?> // Outputs the value of the 'email' field

<?php foreach ($form->data() as $field => $value) {} ?> // Helper to loop the form data

2. Email Content ($email)

Includes configuration values from emails:content defined in the form blueprint file.

For example:

<?= $email->subject() ?> // Outputs the subject line from the configuration
<?php if ($email->footer()->isNotEmpty()): ?>
    <?= $email->footer() ?> // Outputs the footer text if it is defined
<?php endif; ?>

The footer field is reserved and allows CMS users to define custom footer text.

The subject field is reserved and will be provided by the blueprint.

3. Language Code ($languageCode)

The current language code (e.g., en, de) is passed to the template. This can be useful for conditional logic or formatting based on the user’s language.

For example:

<?php if ($languageCode === 'de'): ?>
    Hallo <?= $form->name() ?>, danke für deine Nachricht!
<?php else: ?>
    Hello <?= $form->name() ?>, thank you for your message!
<?php endif; ?>

Example Templates

mail.text.php

New inquiry from <?= $form->name() ?>

<?php
foreach ($form->data() as $field => $value) {
    if (empty($value)) continue;
    
    if (is_array($value)) {
        $value = implode(', ', $value);
    }
    
    echo ucfirst($field) . ': ' . $value . "\n\n";
}
?>

reply.html.php

<html>
  <head>
    <style>
      body {
        font-family: Arial, sans-serif;
        color: #333;
      }

      h1 {
        color: #007bff;
      }
    </style>
  </head>
  <body>
    <title><?= $email->subject() ?></title>
    <h1><?= $email->greetings() ?></h1>
    <p><?= $email->message() ?></p>
    <p><strong><?= $form->message() ?></strong></p>

    <?php if ($email->footer()->isNotEmpty()): ?>
      <footer><?= $email->footer() ?></footer>
    <?php endif; ?>
  </body>
</html>

Running composer inspect <template-id> gives you information about all available attributes.

Form data snippets

These snippets are intended as a drop-in replacement for manually iterating over $form->data() in your templates. They are also used by the default fallback templates.

<?php
  // for html templates
  snippet('emails/data-html', ['form' => $form]);

  // for text templates
  snippet('emails/data-text', ['form' => $form]);
?>

Both snippets iterate over $form->data() and render all fields (arrays are converted to comma-separated lists).