Mail Builder - xoopscube/legacy GitHub Wiki

XCube Core Mail Builder System

Provides a framework for modules to build and send notification emails.
Modules should extend these classes to implement module-specific details
like email subjects, body content, and recipient lists.

Based on RegistMailBuilder by Kazuhisa Minato aka minahito, Core developer

How to Use This in Your Module

1. Create a module-specific mail builder by extending one of the core builder classes
   (e.g., XCube_AdminNotificationMailBuilder or XCube_UserNotificationMailBuilder).

Example for an admin notification:

// /modules/yourmodule/class/YourModuleAdminMailBuilder.class.php
class YourModule_AdminMailBuilder extends XCube_AdminNotificationMailBuilder
{
   public function __construct()
   {
       // Pass your module's dirname to the parent constructor
       parent::__construct('yourmodule');
   }

  // REQUIRED: Implement setSubject using your module's language constants
   public function setSubject($object, $xoopsConfig)
       {
       // _MYMOD_ADMIN_NOTIFY_SUBJECT would be defined in yourmodule's language files
       $this->mMailer->setSubject(
           sprintf(
               _MYMOD_ADMIN_NOTIFY_SUBJECT,
               $object->getVar('title'), // Example
               $xoopsConfig['sitename']
           )
       );
   }

   // OPTIONAL: Override setBody to add more specific variables
   public function setBody($object, $xoopsConfig)
   {
       parent::setBody($object, $xoopsConfig); // Sets common XOOPS and admin vars

       // Add module-specific variables for your template
       $this->mMailer->assign('MYMODULE_FIELD', $object->getVar('my_field'));
       $this->mMailer->assign('MYMODULE_LINK', XOOPS_URL . '/modules/yourmodule/view.php?id=' . $object->getVar('id'));

       // You can also override variables set by parent::setBody if needed
       // For example, if the default ADMIN_OBJECT_URL is not suitable:
       // $this->mMailer->assign('ADMIN_OBJECT_URL', XOOPS_URL . '/modules/' . $this->mModuleName . '/admin/index.php?action=custom_view&id=' . $object->getVar('id'));
   }

   // OPTIONAL: Override setToUsers if the default admin group logic is not sufficient
   // public function setToUsers($object, $moduleConfig)
   // {
   //     // Custom logic to set recipients, or call parent for default behavior
   //     parent::setToUsers($object, $moduleConfig);
   // }

   // OPTIONAL: Override setTemplateName if 'admin_notification.tpl' is not desired
   // public function setTemplateName()
   // {
   //    $this->mMailer->setTemplate('my_custom_admin_template.tpl');
   // }
   }

2. Create email templates in your module's language directory:

   • /modules/yourmodule/language/english/mail_template/admin_notification.tpl
   • /modules/yourmodule/language/english/mail_template/user_notification.tpl

   (Or whatever names you specify in setTemplateName()).

3. In your module's action class, use the Director and your custom Builder:

   protected function _sendAdminNotification($object) // Example method
   {
       $root = XCube_Root::getSingleton();
       $xoopsConfig = $root->mContext->getXoopsConfig();
       // Assuming $this->mModuleConfig holds your module's preferences/configs
       // or pass an empty array if not used by your setToUsers or other methods.
       $moduleConfig = $this->mModuleConfig ?? [];

       // Create your module-specific builder
       $builder = new YourModule_AdminMailBuilder();

       // Create the director
       $director = new XCube_MailDirector($builder, $object, $xoopsConfig, $moduleConfig);
       $director->constructMail(); // Changed from contruct() to avoid PHP4 constructor conflict

       $mailer = $builder->getResult();
       if (!$mailer->send()) {
           // Log error: $mailer->getErrors();
           return false;
       }
       return true;
   }

4. Define necessary language constants in your module (e.g., '_MYMOD_ADMIN_NOTIFY_SUBJECT' )

---

How to Use MailBuilder Generator

The custom mail builder class generates a PHP class extending XCube_AdminNotificationMailBuilder,
a basic email template for your notifications and the required language definitions for your module.

The MailBuilder Class Generator

1. Fill in the form fields with your desired values:

Module Name
The lowercase name of your module (e.g., "mymodule")

Subject Language Constant
The language constant for email subjects

Subject Default
Default subject text if language constant isn't defined

Message Language Constant
The language constant for email messages

Message Generic
Default message text if language constant isn't defined

Template Name
Name of the email template file

Admin Group Preference Key
Module preference key for admin group selection

Extra Admin Emails
Additional email addresses to receive notifications

2. Click "Generate Code" to produce:

   • PHP Class: The custom mail builder class extending XCube_AdminNotificationMailBuilder
   • Mail Template: A basic email template for your notifications
   • Language Constants: Required language definitions for your module

3. Copy the generated code to the appropriate files in your module:

   • PHP Class: /modules/yourmodule/admin/class/AdminNotificationMailBuilder.class.php
   • Mail Template: /modules/yourmodule/language/english/mail_template/admin_notification.tpl
   • Language Constants: Add to /modules/yourmodule/language/english/admin.php

This generator follows the pattern used in the standard module's mail builder implementation,
with customizable constants at the top of the class for easy configuration.

---

Mail Template Variables

Variables Provided by Parent Classes XCube_MailBuilder and XCube_AdminNotificationMailBuilder

When you call parent::setBody($object, $xoopsConfig); in your ModuleName_AdminNotificationMailBuilder::setBody() method, the parent classes XCube_MailBuilder and XCube_AdminNotificationMailBuilder typically assign a set of common variables.
Based on the XCube_MailBuilder::setBody these include:

{SITENAME}
The name of your website (e.g., "Web Application Platform").
Assigned from $xoopsConfig['sitename']

{ADMINMAIL}
The administrator's email address for the website.
Assigned from $xoopsConfig['adminmail']

{SITEURL}
The base URL of your website (e.g., "https://example.com/")
Assigned from XOOPS_URL . '/'

Additionally, for consistency with the notification system and to provide more explicit "XCube" prefixed tags, the parent also assigns:

• {X_SITENAME}: Same as {SITENAME}
• {X_ADMINMAIL}: Same as {ADMINMAIL}
• {X_SITEURL}: Same as {SITEURL}
• {X_MODULE}: The directory name of the current module.

This is derived from $this->mModuleName which is set in the XCube_AdminNotificationMailBuilder constructor
when you call parent::__construct('stdCache');

• {X_MODULE_URL}: The URL to the current module's root (e.g., "https://example.com/modules/moduleName/")

[!IMPORTANT] {X_UNAME} : The parent XCube_MailBuilder or XCube_AdminNotificationMailBuilder might also assign {X_UNAME}
(the recipient's username). However, for admin notifications that often go to a group or a list of email addresses
(rather than a single specific user who triggered an event), this variable might:

• Not be set.
• Be set to a generic value like "Admin".
• Be set to the email address if the mailer is iterating (which XoopsMailer doesn't do by default when given an array of 'To' addresses).

It's generally safer for admin notification templates to use a generic greeting like "Hello Administrator,"
unless you have specific logic to personalize it.

Extending with Custom Variables in Your Module's Mail Builder

Your StdCache_AdminNotificationMailBuilder::setBody() method is where you add variables specific to your module's
notification needs. You do this using $this->mMailer->assign('YOUR_TAG_NAME', $value);

In your ModuleName_AdminNotificationMailBuilder, you can assign:

• {MODULE_NAME}: The display name of your module.

You'd assign this using $this->mMailer->assign('MODULE_NAME', $this->mModule->getVar('name'));
where $this->mModule is the XoopsModule object, available because XCube_AdminNotificationMailBuilder initializes it.

• {NOTIFICATION_TITLE}: A title for the notification (e.g., "Module Name Automated Alert").
• {NOTIFICATION_MESSAGE}: The main detailed message, which itself can be dynamic containing the formatted value via sprintf.
• {ADMIN_URL}: The direct link to the relevant admin page in your module.

[!NOTE] The parent XCube_MailBuilder assigns SITENAME, SITEURL, and ADMINMAIL (and their X_ prefixed versions).
It does not typically assign variables with the prefix_ and lowercase names like {app_sitename}.

To make these footer tags work, you can change your template to use the tags assigned by your module:

Explicitly assign app_sitename, app_url, and app_adminmail in your ModuleName_AdminNotificationMailBuilder::setBody()
If you have a strong reason to keep the {app_...} tags in your template, you would add these lines to your setBody method:

// In StdCache_AdminNotificationMailBuilder::setBody()
parent::setBody($object, $xoopsConfig);
// ... other assignments ...

$this->mMailer->assign('app_sitename', $xoopsConfig['sitename']);
$this->mMailer->assign('app_url', XOOPS_URL . '/');
$this->mMailer->assign('app_adminmail', $xoopsConfig['adminmail']);

[!TIP] When documenting the available tags for your email template (module_notification.tpl)
list all variables that are reliably assigned in a list e.g., in a README.txt or module's help file

Available Email Template Tags

The following tags can be used in the default admin_notification.tpl email template.
They are assigned by the module and the XCube mail system.

General Site & Module Information (mostly from XCube_MailBuilder):

• {SITENAME}: The name of your website.
• {SITEURL}: The base URL of your website.
• {ADMINMAIL}: The website administrator's email address.
• {X_SITENAME}: (Alias for SITENAME)
• {X_SITEURL}: (Alias for SITEURL)
• {X_ADMINMAIL}: (Alias for ADMINMAIL)
• {X_MODULE}: The directory name of this module.
• {X_MODULE_URL}: The URL to this module's root.
• `{APP_...} Your custom tags.

Example Usage of custom tags in Template:

Hello Administrator,

This is an automated notification from the {APP_NAME} on your website: {APP_SITE} ({APP_URL}).

Event: {NOTIFICATION_TITLE}

{NOTIFICATION_MESSAGE}

Current custom tag (for reference): {APP_EVENT}
Custom notification tag (for reference): {APP_TASK}

Please review the cache statistics here:
{APP_URL}

-----------
{APP_NAME} ({APP_URL})
Webmaster
{APP_ADMINMAIL}

This documentation provides clarity for anyone who might want to customize the email template,
ensuring they use the correct tags that your module code makes available.

The xoopsMailer

The mailer object you get from $xoopsMailer = getMailer(); gives you an instance of the xoopsmailer class defined in html/class/xoopsmailer.php This class is actually a wrapper around a more powerful mailer, XoopsMultiMailer which itself uses PHPMailer as its engine.

The object returned by getMailer() is not limited to just sending a single, simple email to the admin.
It does allow for significant customization, much like what you'd expect from a more structured builder
pattern like XCube_MailBuilder

Multiple Recipients

The xoopsmailer object has methods like setToEmails($email_array), setToUsers($user_object_array), and setToGroups($group_object_array).
This means you can send the same email to multiple email addresses, multiple users, or all users within specific groups.

Usually, modules use $xoopsMailer->setToEmails($this->xoopsConfig['adminmail']); which sends to a single recipient (the admin email).
But you could pass an array of emails if needed.

Mail Templates

It supports using mail templates using this:

$xoopsMailer->setTemplateDir($mailTemplateDir);
$xoopsMailer->setTemplate('module_support_request.tpl');
$xoopsMailer->assign('CLIENT_NAME', $clientName);
// ... other assigns ...

This allows you to separate the email's structure and content from your PHP code, making it easier to manage and translate.

Custom Headers, From Address, Subject, Body:

• You can set custom headers $xoopsMailer->addHeaders()
• You can set the "From" email and name $xoopsMailer->setFromEmail(), $xoopsMailer->setFromName()
• You can set the subject and body $xoopsMailer->setSubject(), $xoopsMailer->setBody()

HTML vs. Plain Text

The underlying XoopsMultiMailer is capable of sending HTML emails. While the basic xoopsmailer wrapper might primarily
focus on text-based templates, the capability is there if you delve into the multimailer property.

xoopsMailer vs XCube_MailBuilder

XCube_MailBuilder, and its derivatives like XCube_AdminNotificationMailBuilder, is a higher-level abstraction provided
by the XOOPSCube framework. It offers a more structured, often delegate-driven, way to construct and send emails.

Typically, an XCube_MailBuilder instance will itself use an instance of XoopsMultiMailer
or a similar mailer object, often obtained via getMailer() or directly instantiated, to do the actual sending.

So, getMailer() gives you access to the foundational mailing capabilities that XCube_MailBuilder would also utilize.

You can use the xoopsmailer object obtained from getMailer() in a fairly standard and capable way:

• You set the "To" address (admin).
• You set the "From" address (client's email).
• You set the subject.

You use a mail template (module_support_request.tpl) and assign variables to it for the body.

This is already more than just sending a "single simple email."
You're using templating, which is a form of customization.
If you needed to send to multiple admins or CC someone, the $xoopsMailer object has the methods to support that.

So, while XCube_MailBuilder provides a more formalized "builder" pattern, the object from getMailer() is quite versatile
and not just a simple "send one email to admin" tool.