Detailed commentary on the sample message module

Installer

This module is exchanged with PM, so it's best that this module migrates existing data of PM. In XOOPS2, for such purpose, module developers use onInstall script. In Legacy 2.1, custom installer is available. Custom installer is the specific class declared in xoops_version. Normally, the class is a sub-class of the installer class used by the installation action in the control panel.

$modversion['legacy_installer']['installer']['class'] = "Installer";

This doesn't equal the formal class name. The formal class name is a composite name generated by this declaration and dirname. That's {Dirname}_{class}. In this case, the formal class name is "Messgae_Installer". The class has to be defined in admin/class/{class}.class.php.

The naming convention has some options and exceptions for duplicatable modules and D3 modules. For more informations, see comments of Legacy_ModuleInstallAction.

Module developers can control all things of the install process with custom installer. The spec greater than onInstall is flexibility and logging. The installer class has the log instance as its member property. Through that, this module shows message about migration to users. These messages is defined in modinfo.php.

Kernel handler hook

Private message is an optional spec of Legacy 2.1. But, it is popular spec in other features. For example, famous bad class XoopsMultiMailer abstracts mails and messages. Also the notification feature uses private messages. These classes use the private message handler of the kernel to send messages. Therefore, this module has to hook this hander. How do we do that?

The answer is understanding delegate. Handlers of the kernel are gotten through xoops_gethandler() which is a kind of flyweight pattern. xoops_gethandler() has delegate-event "Legacy.Event.GetHandler". So it's possible to hook it with adding the function to this event in preload. By that, xoops_gethandler() returns the adapter class of this module to the request of getting the private message handler. That's interesting. See kernel/privmessage.class.php.

Note

xoops_gethandler() has caches. If someone gets the private message handler before preBlockFilter(), the event is not raised for the private message handler, never.

It's good solution that we make the preload able to be specified as primary preload.