Example email module

The following example module demonstrates how to customize the email template Swarm uses when sending notifications for comments.

  1. Create a folder called Example in the module folder.

  2. Create the file Module.php within module/Example and edit it to contain: 

    <?php

namespace Example;
use Zend\Mvc\MvcEvent;

/**
 * Automatically uses any custom email templates found under this
 * module's view/mail folder (e.g. Example/view/mail/commit-html.phtml).
 *
 * Valid templates include:
 *
 *   commit-html.phtml (HTML version of commit notification)
 *   commit-text.phtml (text version of commit notification)
 *  comment-html.phtml (HTML version of comment notification)
 *  comment-text.phtml (text version of comment notification)
 *   review-html.phtml (HTML version of review notification)
 *   review-text.phtml (text version of review notification)
 *
 * Note: you need to provide custom templates for both HTML and text;
 * if you do not provide both, it is possible that the search for
 * customized templates only finds the non-customized versions, making
 * it appear that this module is not working.
 */
class Module
{
    public function onBootstrap(MvcEvent $event)
    {
        $application = $event->getApplication();
        $services    = $application->getServiceManager();
        $events      = $services->get('queue')->getEventManager();

        $events->attach(
            '*',
            function ($event) {
                $mail = $event->getParam('mail');
                if (!$mail || !isset($mail['htmlTemplate'], $mail['textTemplate'])) {
                    return;
                }

                $html = __DIR__ . '/view/mail/' . basename($mail['htmlTemplate']);
                $text = __DIR__ . '/view/mail/' . basename($mail['textTemplate']);

                if (file_exists($html)) {
                    $mail['htmlTemplate'] = $html;
                }
                if (file_exists($text)) {
                    $mail['textTemplate'] = $text;
                }

                $event->setParam('mail', $mail);
            },
            -199
        );
    }
}

    This file achieves several things. It:

    • makes the Example folder a recognized module.

    • declares the module's namespace, which matches the module's folder name Example.

    • provides an onBootstrap() method that allows the module's configuration to be established immediately after the module is loaded

    • attaches to events, looking for mail events. When such an event is encountered, it provides local paths for HTML and text-only view scripts.

    • declares an event priority of -199. Since, email delivery events are processed with a priority of -200, this module's templates should override any that may have been set elsewhere, and this occurs just prior to email delivery.

  3. Create a folder called view in the module/Example folder.

  4. Create a folder called mail in the module/Example/view folder.

  5. Create the file comment-html.phtml within module/Example/view/mail and edit it to contain: 

    <?php
    $user       = $activity->get('user');
    $userLink   = $user
                ? $this->qualifiedUrl('user', array('user' => $user))
                : null;
    $targetLink = $activity->getUrl($this->plugin('qualifiedUrl'));
?>
<html>
  <body style="font-family: sans-serif; background-color: #eee; padding: 1em;">
    <div style="background-color: #fff; border: 1px solid #ccc; padding: 1em;">
      <div style="font-size: 115%;">
        <?php if ($user): ?>
          <a style="text-decoration: none;" href="<?php echo $userLink ?>">
            <?php echo $this->escapeHtml($user) ?>
          </a>
        <?php endif; ?>
        <?php echo $this->escapeHtml($activity->get('action')) ?>
        <a style="text-decoration: none;" href="<?php echo $targetLink ?>">
          <?php echo $this->escapeHtml($activity->get('target'))?>
        </a>
      </div>
      <br/>
      <?php
          // if the comment has file context, show it.
          $comment = $event->getParam('comment');
          $context = $comment
                   ? $comment->getFileContext()
                   : array('content' => null, 'line' => null);
          if (is_array($context['content']) && $context['line']) {
              $line = $context['line'] - count($context['content']) + 1;
              echo '<div style="font-family: monospace; white-space: nowrap;'
                  . ' padding: .5em 1em; overflow-x: auto; color: #444;'
                  . ' border: 1px solid #ddd; background-color: #f7f7f7;">';
              foreach ((array) $context['content'] as $i => $content) {
                  echo '<div><span style="color: #999;">'
                      . str_pad($line + $i,
                                strlen($context['line']),
                                "0",
                                STR_PAD_LEFT
                        )
                      . '.</span>&nbsp;'
                      . $this->preformat($content)
                             ->setLinkify(false)
                             ->setEmojify(false)
                             ->setWordWrap(900)
                      . "</div>\n";
              }
              echo '</div><br/>';
          }
      ?>
      <div style="padding-bottom: .5em;">
      <?php
          echo $this->preformat($activity->get('description'))
                    ->setBaseUrl($this->qualifiedUrl())
                    ->setEmojify(false)
                    ->setWordWrap(900)
      ?>
    </div>
  </div>
</body>
</html>

    This is a view script that provides the content for the HTML portion of the comment notification email. Note that it is considered best practice to use inline CSS for styling emails.

  6. Create the file comment-text.phtml within module/Example/view/mail and edit it to contain: 

    <?php
    echo trim($activity->get('user')
        . ' commented on '
        . $activity->get('target'));

    // if the comment has file context, show it.
    $comment = $event->getParam('comment');
    $context = $comment
             ? $comment->getFileContext()
             : array('content' => null);
    if (is_array($context['content'])) {
        echo "\n\n> " . $this->wordWrap(
            implode("\n> ", $context['content']), 900
        );
    }

    echo "\n\n" . trim($this->wordWrap($activity->get('description'), 900));
    echo "\n\n" . $activity->getUrl($this->plugin('qualifiedUrl'));
?>

    This is a view script that provides the content for the text-only portion of the comment notification email.

If you need to customize any other types of Swarm notification email messages, locate the view scripts (both HTML and text) and copy them into module/Example/view/mail, maintaining the existing filenames, then modify the new files as desired.

Note

If you do not copy both the HTML and text templates, it is possible for the search for customized templates to only find non-customized versions, making it appear that your module is not working.