[4.0] Adding a mail templating system

[Hackwar]

This PR adds a way to modify the mails that are send by the system in a GUI and with a larger range of possibilities than with the current system of simple translation strings. Extensions have to register the mails that they want to send and then can use an API to render those mails.

Registering a mail template

An extension has to add its templates via MailTemplate::addTemplate() during installation or whenever it is doing its setup. This inserts a row for each mail template into #__mail_templates, with a template_id, an empty language field, translation strings for subject, body and optionally htmlbody and in the params field the available tags in the template. The template_id has to be of the format {extension}.{sub-identifier}, for example "com_config.test_mail". This is not restricted to components, but it requires a translation file in the administrator language folder.
If there is no modified mail template, the translated translation strings are used to send the mails.

Editing mail templates

The GUI is located in com_mails and is in the System menu in the backend below the global configuration item. All the templates are listed in that view and you can then click on the respective flag to edit the template for that language. You can enable or disable editing the different fields. The idea behind this is, that you can revert changes to the templates by going back to the original translation strings.
Next to the editors, you have the available tags, which can be inserted into the text by clicking on them. These also work in the subject, but have not been listed here separately.

Sending a mail

To send a mail, the code could look like this:

$mailer = new MailTemplate('com_config.test_mail', $user->getParam('language', $app->get('language')), $mail);
$mailer->addTemplateData(array('sitename' => $app->get('sitename'), 'method' => Text::_('COM_CONFIG_SENDMAIL_METHOD_' . strtoupper($mail->Mailer))));
$mailer->addRecipient($app->get('mailfrom'), $app->get('fromname'));
$mailer->send();

You create a MailTemplate object with the ID of your mail template and the language that you want this in, then add the data that should be replaced in the template as associative array and the recipient and then send it.

Features

1. Attachments
   You can attach files to your templates both statically when editing the template in the backend, as well as dynamically when sending the mail. The fields in the backend only show up when a valid path is inserted in the components configuration.
2. Plaintext & HTML mails
   Mails can be created as plaintext and HTML mails and also HTML with plaintext as fallback. Again a feature that can be selected in the components configuration.
3. Alternative mail settings
   Each template can be send via its own mailing settings, so you can set your own sending address and even your own SMTP settings.
4. Send copies of each mail
   Each mail can be send to another recipient via BCC for archiving or error checking purposes.
5. Nested templates
   A template can contain nested templates. Tags are an associative array of key-value-pairs. If the value is an array containing arrays, then the system will look for a part with {key}...{/key} and repeat that for every array in the array... I guess you catch what I'm trying to say. This can be nested infinitely deep.

How to test

Right now there is one template in the system for the test mail in the global configuration. You can modify the template for your language (install additional languages and create content languages for more languages in the templates) and then test it by clicking the test button in the mail settings.

I've rewritten this PR to include features that were previously only advertised but not included and did some more cleanup work.

I'm looking forward to your feedback.

Credits

This PR is supported by Showcast.de, where we have been using a similar system for quite some time now.

[Fedik]

that a cool feature!

[laoneo]

Instead of using a table, can we not work with plugin events to collect the available mail templates? It would make the thing more dynamic as often the strings are not static.
As components, which do have that functionality already self made, in their submenu and custom fields and categories are there too, would it be possible to offer mail template menu links for a component. The idea behind it is that people install a component and then do set it up. So it would be good when they do not have to leave the context of the component and do navigate away from it to set up the mails.

Beside that I really like that feature!

[Hackwar]

@laoneo I thought about several ways how to do this, but storing the templates in a table is the only thing that doesn't escalate into a horrible abomination of system. If you are talking about the available tags: You can already extend those via a plugin event when sending the mails and I'm working on adding the event when rendering the tags.

[Hackwar]

Ok, I did some more work and you should be able to save the changed templates now. Unfortunately I have some issues with the sessions and I'm getting kicked out of my installation on each click... idk. Anyway, it would be nice to get some feedback from you guys now.

[Fedik]

When editing a template, somehow I got a broken editor, not sure if it related to the PR.

Sending cannot test currently, have to fix my email config.

[Hackwar]

The broken editor is a general issue when you have 2 different editors on the same page. That is something that we have to look into in another issue.

[brianteeman]

Pretty sure that was resolved in J3

[bees4ever]

Having here the "Pizza-Bugs-and-Fun" with @roland-d I tried to get this PR tested. However, I had a clean installation of Joomla 4 and applied the patch. First, the extension didn't get corrected installed, i.e. the mysql DB was not updated correctly, when I opened http://localhost/joomla-cms3/administrator/index.php?option=com_mails&view=templates locally this error appeard.

I updated the DB myself but then this error appeared:

What can I do to get the patch run?

Thanks

[roland-d]

@Hackwar I sent PR Hackwar#33 to fix the SQL errors.

[Hackwar]

thx @roland-d

[Schmidie64]

You should add to the test instructions that you have to delete the autoload_psr4.php file (/ libraries) and the Javascript files have to be rebuilt (npm run build: js)

[wilsonge]

Merging this as a starting point as the basics work. I fully accept there needs to be some work here as we move through getting 4.0 to stable. Personally for example the way if you enable html mails don't show the text at all for the sample mail is confusing (although having dived through the code I think I finally understand the logic of why). So let's start with this get some user testing done as it ends up in the nightlies and see how things go.

Thanks @Hackwar

[micker]

hello thanks for this great feature a question, no plan to use with new workflow system ?
link transition action to a specific email template will be a great function
both feature will be improve and polished
thanks @Hackwar

[Hackwar]

No, right now the workflow is not implemented here. I'm open to improve this in the future; for 4.0 I would keep it the way it is and postpone this to 4.1 or similar.

[micker]

ok cool ! thanks i will be a great function !!!