Legacy_AbstractModule

Description
The sub-core Legacy has a virtual controller. This controller handles modules, blocks and themes through new interfaces. Module developers can define the sub-class of these classes to get programable class.
legmodule_dialogs
('Controller' in XOOPS Cube isn't a development framework, but a kind of frameworks as CMS procedure.)

XOOPS2 case
First of all, remind XOOPS2 spec. There are XoopsModule and XoopsBlock in XOOPS2. These classes are the base class for handling module data & block data. XOOPS2 handles them directly, so module developers have to follow how XOOPS2 interprets data of xoops_version. For example, modules can't give any effects to XOOPS2 cache feature, and they can't change titles of their blocks.

Legacy case
Now, see alternative architecture of Legacy. Legacy controller doesn't use XoopsModule and XoopsBlock directly. Legacy delegates data interpretation to Legacy_AbstractModule and Legacy_AbstractBlockProcedure. These classes are an abstract class having interfaces to connect with the controller. Module developers can define a sub-class of these classes to be used by the controller. The sub-class has a XoopsModule object as its member property. So a module developer can change its data interpretation in his module sub class.

How to create an instance

1. Create 'Module.class.php' in /class directory of your module.
2. Define {Dirname}_Module class as the sub-class of Legcy_AbstractModule.
3. Implement methods.

In the case where {Dirname}_Module class is defined already, the instance factory doesn't load 'Module.class.php'. This rule may be useful for duplicatable modules. Do review please.

For more informations, see /module/legacy/class/Module.class.php as an example. And, about 'Overridable' member functions you should implement, see Legacy_AbstractModule.

For compatibility
Most modules don't have such sub-classes. In the case where modules don't have such sub-classes, Legacy uses 'Legacy_ModuleAdapter' as adapter class for the XOOPS2 compatibility. This adapter imitates XOOPS2 spec completely. In addition, this adapter class is useful to quick use, because it's not an abstract class. Module developers may choose this adapter class as the base class for their sub-classes.

Is it possible to change factory?
The precondition of the factory is that a module specified by $xoopsModule->get('dirname') has Module.class.php in /class directory of the module. This spec is unhappy for duplicatable modules. Factory to generate instances of sub-classes and adapter classes is in Legacy_Utils as static functions. By that, module developers can't change the naming convention. In other words, the factory is a fixed-pipeline function. But, the factory function uses XCube_Delegate. So developers can interrupt the fxied-pipeline-factory through delegates.

Also, it's important that Legacy skips loading Module.class.php if the specified class is defined already. Therefore, many solutions for duplicatable modules might be invented. Do review please.

Note
The instance Legacy creates, is set to $root->mContext->mModule. You can access this instance in your module through getting root object.

Reviews
"The base class is in /kernel directoy of the legacy module. Therefore, the factory should hope the file in /kernel directory, too." (minahito)