Шаблоны писем в Joomla. Вступление

С недавнего времени (с выходом Joomla 4) в CMS Joomla появился замечательный функционал - шаблоны писем. Эти шаблоны позволяют администратору настроить "под себя" все системные уведомления, которые отсылает CMS как пользователям, так и администраторам.

В предыдущих версиях Joomla, все это было реализовано через языковые переменные, что было крайне неудобно и максимально ограничивало администратора в "творческом полёте", именно администратора или контент менеджера, которые ни чего не понимают в разработке и им было практически невозможно поменять дизайн писем без привлечения разработчика. Слава Богу, это в прошлом!

На данный момент (Joomla 5) функционал шаблонов писем значительно расширен (и это, конечно же, не предел). Теперь администратор из админ. панели может отредактировать в удобном HTML редакторе (TinyMCE) любое системное письмо, которое отправляет Joomla. Может добавить любой текст, изображения, файлы - это круто!

Так же CMS позволяет вставлять необходимые переменные в тело письма (имя пользователя, почту, имя сайта и т.д.) так, как нужно в конкретном случае. Поддерживается редактирование для разных языков, то есть предусмотрена полная мультиязычность, как и в остальном функционале Joomla.

И все это предлагается "под капотом" Joomla и отлично работает!

Но, как это всегда бывает, стандартного функционала может не хватить для определенных задач. Именно об этом и пойдет речь в этой статье.

Не хватает переменных...

В каждом наборе переменных, любого шаблона письма, содержится необходимый минимум, который Joomla предлагает "из коробки".

Естественно, что для каждого конкретного случая этот набор должен быть скорректирован и доработан. СMS Joomla предоставляет нам такую возможность с помощью использования плагинов.

Ко мне обратился заказчик, с просьбой расширить список переменных в шаблонах, а, конкретно, добавить поля пользователей в шаблон письма об успешной активации пользователя. Далее я расскажу, как я это реализовал.

Спасибо, Бро!

Успешной реализации задачи очень помог Сергей Толкачев. В своем посте на Хабре он описал триггеры событий, которые позволяют добавить новые переменные к шаблонам писем.

И в целом, моя статья, это только расширенное описание поста Сергея. За что ему огромное спасибо!

Кстати, не забудем поблагодарить и заказчика расширения, который спонсировал все это производство, а так же дал согласие на публикацию решения в свободном доступе - это веб студия Креативные Бизнес Системы.

Триггеры для плагина

И так... Задача поставлена: добавить в шаблоны писем переменные, которые будут содержать значения полей пользователей.

Для решения нам нужно:

1. Вывести переменные, в нашем случае это поля пользователей, в шаблоны писем в панели администратора Joomla. Для этого в Joomla предусмотрен триггер BeforeRenderingMailTemplateEvent.

2. Передать новые переменные в письмо администратору. Для этого предусмотрен триггер onMailBeforeRendering.

Давайте рассмотрим каждое событие отдельно.

onMailBeforeTagsRendering

Это событие поможет нам добавить переменные (шорт-коды) в шаблон письма в панели администратора.

В моем случае нужно добавить к стандартным переменным поля пользователя. В качестве шорт-кодов будем использовать имя (не заголовок) полей.

Для получения всех полей пользователей используем

use \Joomla\Component\Fields\Administrator\Helper\FieldsHelper;
$user_fields = FieldsHelper::getFields('com_users.user', true);

Вся функция будет выглядеть так

    public function onMailBeforeTagsRendering(Event $event): void
    {
        $template = $event->getArgument(1); //получаем весь объект 
        $tags =  $template->params['tags']; //получаем стандартные шорт-коды
        $user_fields = FieldsHelper::getFields('com_users.user', true); //получаем все поля пользователя
        $newtags = [];
        foreach($user_fields as $field) {
            $newtags[] = $field->name; //формируем массив с полями по имени поля
        }
        $tags = array_merge($tags, $newtags); //добавляем поля пользователя к стандартным шорт-кодам
        $template->params['tags'] = $tags;// добавляем все в объект
    }

Теперь в шаблонах писем, в переменных, у нас отображаются и шорт-коды полей пользователей.

Но этого еще не достаточно, нужно еще "заставить" Joomla понимать, какие данные отправлять, используя эти шорт-коды.

onMailBeforeRendering

Это событие позволит нам научить Joomla понимать новые шорт-коды и корректно отправлять данные по ним в письма.

Аргументом $event для этой функции является экземпляр класса BeforeRenderingMailTemplateEvent

подключаем

use Joomla\CMS\Event\Mail\BeforeRenderingMailTemplateEvent;

У меня стояла задача, передать поля пользователей в письме администратору о необходимости активации нового пользователя, поэтому следующий код будет немного не стандартный, но очень хорошо подойдет для примера

    public function onMailBeforeRendering(BeforeRenderingMailTemplateEvent $event): void
    {
        $templateId = $event->getTemplateId(); //id шаблона, как контекст
        $app = Factory::getApplication();

        if($templateId == 'com_users.registration.admin.verification_request') { //нужный мне шаблон письма
            $activiti = $app->input->get('token', '', 'string');//получение токена (ключа активации), который содержится в ссылке на активацию
            $db = Factory::getContainer()->get(DatabaseInterface::class); //подключаем базу
            $db->setQuery("SELECT `id` FROM `#__users` WHERE `activation` = '{$activiti}'");
            $user_id =  $db->loadResult(); //получаем id пользователя, что бы передать его поля
       } 
        $user_fields = FieldsHelper::getFields('com_users.user', ['id' => $user_id], true); //получаем все поля пользователя
        $template = $event->getTemplate();//получаем весь объект письма
        foreach($user_fields as $field) {
            $data[$field->name] = $field->value; //получаем поля пользователя в нужном нам виде по имени поля
        }
        $template->addTemplateData($data);// передаем в объект новый массив шорт-кодов
    }

Давайте подробно рассмотрим $data - массив, который передает данные о новых переменных (шорт-кодах).

$template = $event->getTemplate();//получаем весь объект письма
$data = [
  'field_name' => 'field_vale',
];
$template->addTemplateData($data);// передаем в объект новый массив шорт-кодов

Теперь в шаблоне письма используем {field_name}, чтобы в самом письме получить field_value.

Всю логику разобрали. Далее соберем все в системный плагин, который позволит реализовать нужный функционал.

Системный плагин ShortMail

Структура плагина

- language
-- en-GB
--- plg_system_shortmail.ini
--- plg_system_shortmail.sys.ini
- services
-- provider.php
- src
-- Extension
--- Shortmail.php
- shortmail.xml

Файл манифеста shortmail.xml

<?xml version="1.0" encoding="utf-8"?>
<extension type="plugin" group="system" method="upgrade">
    <name>plg_system_shortmail</name>
    <author>Alexandr Novikov</author>
    <creationDate>2025-01-20</creationDate>
    <copyright>(C) 2025 Alexandr Novikov. All rights reserved.</copyright>
    <license>GNU General Public License version 2 or later</license>
    <authorEmail>support@joomlab.ru</authorEmail>
    <authorUrl>https://joomlab.ru</authorUrl>
    <version>1.0.0</version>
    <description><![CDATA[Дополнительные поля пользователей в шаблоне письма]]></description>
    <namespace path="src">joomLab\Plugin\System\Shortmail</namespace>
    <files>
        <folder plugin="shortmail">services</folder>
        <folder>src</folder>
        <folder>language</folder>
    </files>
    <languages folder="language">
        <language tag="en-GB">en-GB/plg_system_shortmail.ini</language>
        <language tag="en-GB">en-GB/plg_system_shortmail.sys.ini</language>
    </languages>
    <config>
        <fields name="params">
            <fieldset name="basic">
                <!-- Add your plugin parameters here -->
            </fieldset>
        </fields>
    </config>
</extension>

provider.php

<?php
/**
 * @package     joomLab.Plugin
 * @subpackage  System.Shortmail
 *
 * @copyright   (C) 2025 Alexandr Novikov. All rights reserved.
 * @license     GNU General Public License version 2 or later; see LICENSE.txt
 */

\defined('_JEXEC') or die;

use Joomla\CMS\Extension\PluginInterface;
use Joomla\CMS\Factory;
use Joomla\CMS\Plugin\PluginHelper;
use Joomla\DI\Container;
use Joomla\DI\ServiceProviderInterface;
use Joomla\Event\DispatcherInterface;
use joomLab\Plugin\System\Shortmail\Extension\Shortmail;

return new class () implements ServiceProviderInterface {
    public function register(Container $container): void
    {
        $container->set(
            PluginInterface::class,
            function (Container $container) {
                $plugin = new Shortmail(
                    $container->get(DispatcherInterface::class),
                    (array) PluginHelper::getPlugin('system', 'shortmail')
                );
                $plugin->setApplication(Factory::getApplication());
                return $plugin;
            }
        );
    }
}

shortmail.php

<?php
/**
 * @package     joomLab.Plugin
 * @subpackage  System.Shortmail
 *
 * @copyright   (C) 2025 Alexandr Novikov. All rights reserved.
 * @license     GNU General Public License version 2 or later; see LICENSE.txt
 */

namespace joomLab\Plugin\System\Shortmail\Extension;

defined('_JEXEC') or die;

use Joomla\CMS\Plugin\CMSPlugin;
use Joomla\Event\SubscriberInterface;
use Joomla\Event\Event;
use Joomla\CMS\Event\Mail\BeforeRenderingMailTemplateEvent;
use Joomla\Database\DatabaseInterface;
use \Joomla\Component\Fields\Administrator\Helper\FieldsHelper;
use Joomla\CMS\Factory;

class Shortmail extends CMSPlugin implements SubscriberInterface
{
    protected $autoloadLanguage = true;

    public static function getSubscribedEvents(): array
    {
        return [
            'onMailBeforeRendering' => 'onMailBeforeRendering',
            'onMailBeforeTagsRendering' => 'onMailBeforeTagsRendering'
        ];
    }

    public function onMailBeforeRendering(BeforeRenderingMailTemplateEvent $event): void
    {
        $templateId = $event->getTemplateId();
        $app = Factory::getApplication();
        $activiti = '1';
        if($templateId == 'com_users.registration.admin.verification_request') {
            $activiti = $app->input->get('token', '', 'string');
            $db = Factory::getContainer()->get(DatabaseInterface::class);
            $db->setQuery("SELECT `id` FROM `#__users` WHERE `activation` = '{$activiti}'");
            $user_id =  $db->loadResult();
       }
        $user_fields = FieldsHelper::getFields('com_users.user', ['id' => $user_id], true);
        $template = $event->getTemplate();
        foreach($user_fields as $field) {
            $data[$field->name] = $field->value;
        }
        $template->addTemplateData($data);
    }
    public function onMailBeforeTagsRendering(Event $event): void
    {
        $template = $event->getArgument(1);
        $tags =  $template->params['tags'];
        $user_fields = FieldsHelper::getFields('com_users.user', true);
        $newtags = [];
        foreach($user_fields as $field) {
            $newtags[] = $field->name;
        }
        $tags = array_merge($tags, $newtags);
        $template->params['tags'] = $tags;
    }

}

Контекст

Чуть не забыл про контекст. Структура шаблонов писем отличается от общей структуры CMS, где, помимо триггеров, в основном используется еще и $context для вывода плагина в нужном месте компонента.

В шаблонах писем вместо контекста используется template_id

$templateId = $event->getTemplateId();
//com_users.registration.admin.verification_request

Используя template_id вы сможете добавить в разные шаблоны писем свои наборы полей.

Заключение

С помощью этого плагина вы сможете добавить в шаблоны писем поля пользователя. А на примере этого плагина вы сможете добавить в свои шаблоны писем абсолютно любые переменные (шорт-коды), при чем в разных шаблонах они могут быть разные!

Удачи!