Email templates & customization

Introduction

Since 2023.3, we’ve introduced a template system for all emails sent by the application. This allows us to automatically use the logos and colors set for the application in the email content. The main purpose is to avoid modifications by the project team since most of the time, all the email contents were only modified to apply the project logo or to change colors.

1/ Template system with velocity and Notification api

All the emails listed above are created with velocity and Notification api com.wedia.email.Notification

Velocity allows us to import files into other files with #parse script element. This way we can create a generic template and use it for all the email contents. Template files have been added under __default/email/provided :

• footer.html

• footer_account_registration.html

• footer_cart.html

• footer_service_status.html

• header.html

• style.html

• template.html

footer.html is the generic footer which will be present in all the emails. the other footers are added according to the email type.

header.html is the generic header, which will be present in all the emails, it will contain the logo set for the FO login page (UI configuration checklist). If no logo has been set, there will be a fallback to the default wedia logo

style.html : css content applied to all the emails. It will also use the colors set for portal from wedia-config. If no colors are set, there will be a fallback to the default application colors.

template.html is the main file, it will use style, header and one of the footers. It will also include a body : the actual email content.

Here is an example of how is the new template system applied to our existing emails :

Let’s take collaborate.html from WXM_CART2 :

• Before the template system, all the mail content and template was inside WXM_CART2/res/email/collaborate.html

• With the template system :

  • New file added : WXM_CART2/res/email/bodies/collaborate.html

  • Modification of the existing html template WXM_CART2/res/email/collaborate.html

    • #set($style = "#parse('./style.html')")
      #set($header = "#parse('./header.html')")
      #set($footer = "#parse('./footer_cart.html')")
      #set($primaryColor = $Tools.getPrimaryColor())
      #set($pluginBundle = $Tools.getBundle("_plugins/WXM_CART2/config/plugin", $locale))
      #set($body = "#parse('./bodies/collaborate.html')")
      #parse('./template.html')

• We can see that all the needed content has been parsed into variables with #parse. Theses variables are then used by template.html

Some tools have been added to Notification api to help us retrieve bundle values and colors.

2/ Customization

Customization is still possible and at multiple levels. It depends on what has to be modified:

• We can change the header to add a custom title for example :

To do this we have to copy the existing header.html from __default/email/provided to __perso/email/project . Then we can add our custom title. After this modification all the emails sent by the application will use the “project” header.

• We can change the generic footer by overriding footer.html under the project folder. If, only the text part has to be changed, we can edit the value of email_template_footer_part_one key of bov3/wcm bundle.

• We can also change the specific footers by overriding them under the project folder.

• We can also add new specific files as headers, footers, or styles. In this case, the email HTML file needs to be updated to use the newly added specific header, footer, or style.

• All bodies content can be changed by overriding them under the project folder and by placing them under the correct file tree structure.

  • Example with cart share email :

    • I’ll create a file named share.html which will contain the main body of my email. I’ll then place it under __perso/email/project/bodies/ . Then when a board is shared, my body content will be used inside the template with the header and the footer.

• All bodies content can be changed by overriding them under the customization folder defined in the plugins (WXM_CART2 and PACKAGED_RegistrationEmails)

  • Example with cart share email :

    • I’ll create a file named share.html which will contain the main body of my email. I’ll then place it under __perso/emailTest/ in a new folder called bodies. This path has also been set in the params of WXM_CART2. Then when a board is shared, my body content will be used inside the template with the header and the footer.

3/ Backward compatibility

The old customization methods are still available !

If a project has already custom emails, made by the old method (plugin param with a path to a folder which contains the customizations), then it’s customization will take priority over the recently added template system.

The developed behaviour will not be altered by an upgrade. This is allowed by the multiple roots offered by Notification api.

4/ Usefull I18n Keys

Generic footer : bov3/wcm/ email_template_footer_part_one

Cart mail footer : bov3/wcm/ email_template_footer_cart

Account registration mail footer : bov3/wcm/ email_template_footer_registration

Registration emails :

account_email_verification.html

Email subject: PACKAGED_RegistrationEmails bundle from key: email.account_email_verification.subject

Translatable text inside the template (from PACKAGED_RegistrationEmails bundle)

title Title inside the email (email.account_email_verification.title)

body Body text of the email (email.account_email_verification.body)

reason Why user is receiving this email (email.account_email_verification.reason)

buttonLabel Label of the button (email.account_email_verification.verify)

buttonUrl URL of the button

account_pending.html

Email subject: PACKAGED_RegistrationEmails bundle from key: email.account_pending.subject

Translatable text inside the template (from PACKAGED_RegistrationEmails bundle)

title Title inside the email (email.account_pending.title)

body Body text of the email (email.account_pending.body)

reason Why user is receiving this email (email.account_pending.reason)

account_request.html

Email subject: PACKAGED_RegistrationEmails bundle from key: email.account_request.subject

Translatable text inside the template (from PACKAGED_RegistrationEmails bundle)

title Title inside the email (email.account_pending.title)

body Body text of the email (email.account_pending.body)

reason Why user is receiving this email (email.account_pending.reason)

buttonLabel Label of the button to review the account request (email.account_request.button)

buttonUrl Url of the button

user The email of the user requesting access

account_welcome.html

Email subject: PACKAGED_RegistrationEmails bundle from key: email.account_welcome.subject

Translatable text inside the template (from PACKAGED_RegistrationEmails bundle)

title Title inside the email (email.account_welcome.title)

body Body text of the email (email.account_welcome.body)

reason Why user is receiving this email (email.account_welcome.reason)

buttonLabel Label of the button to access the application(email.account_welcome.button)

buttonUrl Url of the button

user The email of the user requesting access

Cart / Boards emails :

collaborate.html

Email subject: WXM_CART2 bundle from key: email.collaborate.subject

Translatable text inside the template (from WXM_CART2 bundle)

body Body text of the email (email.collaborate.body)

buttonText Label of the button to access the application(email.collaborate.access-button)

download-zip.html

Email subject: WXM_CART2 bundle from key: email.download-zip.subject

Translatable text inside the template (from WXM_CART2 bundle)

body Body text of the email (email.download-zip.body or email.download-zip.body-downloadedBy)

share.html

Email subject: WXM_CART2 bundle from key: email.share.subject

Translatable text inside the template (from WXM_CART2 bundle)

title Title inside the email (email.share.body.title)

bodyTextWithSender Body text of the email (email.share.body.text-with-sender)

bodyTextNoSender Body text of the email (email.share.body.text-no-sender)

bodyTextWithExpires Additionnal text for the email body (email.share.body.text-with-expires)

bodyTextWithSharePwd Additionnal text for the email body (email.share.body.text-with-sharePwd)

buttonText Label of the button to access the application(email.collaborate.access-button)

sharezip.html

Email subject: WXM_CART2 bundle from key: email.sharezip.subject

Translatable text inside the template (from WXM_CART2 bundle)

title Title inside the email (email.sharezip.body.title)

bodyTextWithSender Body text of the email (email.sharezip.body.text-with-sender)

bodyTextNoSender Body text of the email (email.sharezip.body.text-no-sender)

bodyTextWithExpires Additionnal text for the email body (email.sharezip.body.text-with-expires)

buttonText Label of the button to access the application(email.sharezip.download-button)

zip-available.html

Email subject: WXM_CART2 bundle from key: email.download-zip.subject

Translatable text inside the template (from WXM_CART2 bundle)

title Title inside the email (download.ready.body.title)

body Body text of the email (download.ready.body.text)

bodyExpiresInfo Additionnal text for the email body (download.ready.body.expires.text)

buttonText Label of the button to access the application(download.ready.download-button)

Engine based :

authorizedusers/user_deactivate.html

Email subject: bov3/wcm bundle from key: authorizedusers_user_deactivate_mail_subject

Translatable text inside the template (from bov3/wcm bundle)

title Title inside the email (authorizedusers_user_deactivate_mail_subject)

body Body text of the email (authorizedusers_user_deactivate_mail_txt)

footer Footer of the mail body (authorizedusers_user_deactivate_mail_footer)

login/mail_confirm_user.html

Email subject: bov3/wcm bundle from key: forgotpass_sendmail_mail_subject

Translatable text inside the template (from bov3/wcm bundle)

title Title inside the email (forgotpass_sendmail_mail_subject)

body Body text of the email (forgotpass_sendmail_mail_link_init)

footer Footer of the mail body (forgotpass_sendmail_mail_footer)

login/mail_password_changed.html

Email subject: bov3/wcm bundle from key: forgotpass_passchanged_mail_subject

Translatable text inside the template (from bov3/wcm bundle)

title Title inside the email (forgotpass_passchanged_mail_subject)

body Body text of the email (forgotpass_passchanged_mail_txt)

footer Footer of the mail body (forgotpass_passchanged_mail_footer)

statusPageEvents/mail_status_page_events.html

Email subject: bov3/wcm bundle from key: status_page_mail_subject

Translatable text inside the template (from bov3/wcm bundle)

title Title inside the email (status_page_mail_description)

body Body text of the email (status_page_mail_reason_caption)

footer Footer of the mail body (status_page_mail_link_status_page)