activeCollab 2: Changes to Module Definitions

activeCollab 2 slightly changes the way modules are defined. Our goal was to use object oriented design for things that were procedural in the past. This way, we reduced number of files needed to define a module and amount of code that you need to write.

In previous versions, you needed 5 files to define a module:

1. info.php - Information about the module
2. routes.php - Route definitions for the module
3. handlers.php - Event handlers that this module implements
4. install.php - Code that prepares and installs the module
5. uninstall.php - Code that cleans up the database and file system after the module has been uninstalled

Instead of all these files, now we have a single file - module class. Its name is based on module name. If module name is tickets, this class would be TicketsModule (defined in TicketsModule.class.php file) and if it is status_updates, name is StatusUpdatesModule (defined in StatusUpdatesModule.class.php file).

Information and operation handled by the old files are now fully covered with this class:

1. Information about the module are stored in object properties (like name and version). Some properties are returned by special function so you can localize them (like getDescription() or getUninstallMessage()).
2. When Router loads defined routes, it will call defineRoutes() method of each module.
3. EventManager loads even handler definition in similar ways as Router, but instead of defineRoutes() method it calls defineHandlers() method.
   
4. install.php and uninstall.php are replaced with install() and uninstall() methods.

Router and EventManager now know which module they are loading so there is no need to specify module in route and handler definition any more. You can do that if you wish (to override other modules for example), but it’s optional.

Because new module definitions extend Module class, there are helper methods they inherit that make definition of new configuration options and email templates much easier. Please check addConfigOption() and addEmailTemplate() of Module class for details.

And finally, we added support for platform tests before module is installed. Before you can install a module, activeCollab calls its canBeInstalled() method. If it returns true, module can be installed, but if it returns false, system will abort the installation. Module developer can log messages to inform the user about the tests performed and/or reasons why the module can’t be installed.

Check this implementation from new Incoming Mail module:

/**
 * Returns true if this module can be installed
 *
 * @param array $log
 * @return boolean
 */
function canBeInstalled(&$log) {
  if(extension_loaded('imap')) {
    $log[] = lang('OK: IMAP extension loaded');
  } else {
    $log[] = lang('This module requires IMAP PHP extension to be installed. Read more about IMAP extension in PHP documentation: http://www.php.net/imap');
    return false;
  } // if
  
  return true;
} // canBeInstalled

It’s that easy!

The best way to learn the new system is to see it working. Because of that we recommend that you download latest activeCollab 2 beta from your profile and check out IncomingMailModule or TicketsModule implementations to see all the new features implemented and working.