Module

Introduction

The module is the basic logic brick: it returns the expanded tags requested from the source files (throught the getTag() method). Take a look to the Source engine tutorial for details.

Also, this black box must react to some external event (usually because of a user click): this is done using the callAction() method.

The basic TiP system comes with a set of predefined modules that can be expanded as needed. Every module must be configure in a central configuration file usually called config.php.

Module families

In the TiP system, there are two kind of modules: the TIP_Module class is the abstraction layer of a module without data access, while TIP_Content is the abstraction of a module with data access.

The modules are loaded dynamically. This means if the source file does not require a module, the logic of the module is not loaded.

The module instantiation

The dynamic instantiation of the modules is provided by the TIP_Type class.

Suppose your application need to instantiate the 'test' module. First of all, the module must be properly configured.

To phisically instantiate the object is enough a single call to the TIP_Type::getInstance method (all TIP_Type derived class share the same instantiation interface):

$test_instance =& TIP_Type::getInstance('test');

The TIP_Module::getInstance() method is defined as:

static public function &getInstance($id, $required = true)
{
  static $register = array();
  global $cfg;

  $id = strtolower($id);
  if (class_exists('TIP_Application')) {
    $namespace = TIP_Application::getGlobal('namespace');
    if (!empty($namespace) && isset($cfg[$namespace . '_' . $id])) {
      $id = $namespace . '_' . $id;
    }
  }

  if (array_key_exists($id, $register)) {
    return $register[$id];
  }

  if (isset($cfg[$id])) {
    $options = $cfg[$id];
    isset($options['id']) || $options['id'] = $id;
    $instance =& TIP_Type::singleton($options);
  } else {
    $instance = null;
  }

  if (is_null($instance) && $required) {
    TIP::fatal("unable to instantiate the requested object ($id)");
    exit;
  }

  $register[$id] =& $instance;
  return $instance;
}

The getInstance method performs the following steps to get the requested instance:

1. The module name is converted to lowercase
   To leave the maximum freedom in the source engine (and avoid stupid mistakes), the TiP system use a case insensitive approach to access the modules. The lowercased module name is stored in $id.
2. Instantiate the main module
   The main module contains fundamental logic (such as user notification methods) that must be initialized before any other module.
3. Search for $id in the register
   This method keeps internally an array, so called register, of all yet instantiated modules.
   If $id is found in this register it means it was previously instantiated: its reference is returned with no further manipulation.
4. The module is instantiated
   The module instantiation is dynamically done by the TIP_Type::singleton() method by including all the requested classes to build its hierarchy.
   Also, the singleton() method is responsible to call (if not in AJAX mode) the postConstructor method of the newly instantiated object is called.
5. Check for errors
   The $required flag is used to control the behavior in case the module cannot be instantiated. If set to true (the default), an error in the instantiation will be fatal.
6. The newly created instance is stored in the register

TIP_Module based modules

This class provides the base of a module without data access. The TIP_Application module, for instance, is a typical example of this kind of module because does not have any specific data.

TIP_Content based modules

The TIP_Content is an extension of the TIP_Module class, that is all the features provided by TIP_Module are available in a TIP_Content module. Furthermore, TIP_Content adds the data management feature to TIP_Module.

The data gets by a content module is managed by views: a TIP_Content can have more views on the same data source. See the TIP_View class to get an idea on how the view works.

The views can also be thought as different queries applied on the same TIP_Data object. A view can be started by calling startDataView() (or the more generic startView()) and must be closed by a endView() call. Also, the views are internally stacked, so ending a view reactivates the previous one.

The TIP_View class implements the Iterator interface, so the result of a view can be browsed using foreach() or the default array methods (rewind(), current(), next()).