Base class to encaspulate a request to the component, instantinated by the MidCOM component interface.

It provides an automatic mechanism for URL processing and validation, minimizing the required work to get a new component running.

Request switch configuration

The class uses an array which aids in URL-to-function mapping. Handlers are distinguished by the "URL-space" they handle. For each handler two functions are needed, one for the request handle decision ("Can Handle Phase"), one for the request handling ("Handle Phase") and one for output ("Output Phase"). These handlers can either be contained in this class or refer to another class which gets instantinated, if neccesary.

All request handlers are contained in a single array, whose keys identify the various switch configurations. These identifiers are only for informational purposes (they appear in the debug log), so you could just resort to automatic array index numbering using the [] operator.

Each request handler definition in the switch must contain these key/value pairs:

• mixed fixed_args: This is either a string or an array and defines the fixed arguments that have to be present at the beginning of the URL to be handeld. A string denotes a single argument, an array is used if more then one fixed argument is needed. If you do not have any fixed arguments, set this parameter to null, which is the default.
• int variable_args: Usually, there are a number of variables in the URL, like article IDs, or article names. This can be 0, indicating that no variable arguments are required, which is the default.
• bool no_cache: For those cases where you want to prevent a certain "type" of request being cached. Set to false by default.
• int expires: Set the default expiration time of a given type of request. The default -1 is used to indicate no expiration setting. Any positive integer will cause its value to be passed to the caching engine, indicating the expiration time in seconds.
• mixed handler: This is a definition of what method should be invoked to handle the request. You have two options here. First you can refer to a method of this request handler class, in that case you just supply the name of the method. Alternativly, you can refer to an external class for request processing using an array syntax. The first array member must either contain the name of a existing class or a reference to an already instantinated class. This value has no default and must be set. The actual methods called will have either an _handle_ or _show_ prefixed to the exec_handler value, respecitvly. See below for automatic handler instances, the preferred way to set things up.

 <?php
 $this->_request_switch[] = Array
 (
     'fixed_args' => Array ('registratons', 'view'),
     'variable_args' => 1,
     'no_cache' => false,
     'expires' => -1,
     'handler' => 'view_registration'
     //
// Alternative, use a class with automatic instantination:
     // 'handler' => Array('net_nemein_registrations_regadmin', 'view')
     //
     // Alternative, use existing class (first parameter must be a reference):
     // 'handler' => Array(&$regadmin, 'view')
 
 );
 ?>

This definition is usually located in either in the _on_initialize event handler (preferred) or the subclass' constructor (discouraged, as you can't use references to $this safely there).

The handlers are processed in the order which they have been added to the array. This has several implications:

First, if you have two handlers with similar signatures, the latter might be hidden by the former, for example the handler 'view' with two variable arguments includes the urls that could match 'view','registration' with a single variable argument if processed in this order. In these cases you have to add the most specific handlers first.

Second, for performance reasons, you should try to add the handler which will be accessed most of the time first (unless it conflicts with the first rule above), as this will speed up average request processing.

Subclasses may add additional configuration data to the handler declarations, this is done, for example by the config_dm handler defined in the request_admin subclass. They must only be used to configure predefined requests, you should refer to the documentation of these handlers for details.

Callback method signatures

 <?php
 /**
  * can_handle example, with Docblock:
  * @param mixed $handler_id The ID of the handler.
  * @param Array $args The argument list.
  * @param Array $data The local request data.
  * @return bool True if the request can be handled, false otherwise.
  */
 function _can_handle_xxx ($handler_id, $args, &$data) {}
 
 /**
  * Exec handler example, with Docblock:
  * @param mixed $handler_id The ID of the handler.
  * @param Array $args The argument list.
  * @param Array $data The local request data.
  * @return bool Indicating success.
  */
 function _handler_xxx ($handler_id, $args, &$data) {}
 
 /**
  * Show handler example, with Docblock:
  * @param mixed $handler_id The ID of the handler.
  * @param Array $data The local request data.
  * @return bool Indicating success.
  */
 function _show_xxx ($handler_id, &$data) {}
 ?>

The three callbacks match the regular processing sequence of MidCOM.

_can_handle_xxx notes: For ease of use, the _can_handle_xxx callback is optional, it will only be called if the method actually exists. Normally you want to override this only if you request handler can hide stuff which is not under the control of your topic. A prominent example is a hander definition which has only a single variable argument. It would hide all subtopics if you don't check what objects actually belong to you, and what not.

The main callbacks _handle_xxx and _show_xxx are mandatory.

As you can see, the system provides you with an easy way to keep track of the data of your request, without having dozens of members for trivial flags. This data array is automatically registered in the custom component context under the name 'request_data', making it easily available within style elements avoiding the problems of the view_* globals, this is the new recommended way of passing information to the style elements:

 <?php
 // Bind the view data, remember the reference assignment:
 $view =& $GLOBALS['midcom']->get_custom_context_data('request_data');
 ?>

The data array can also be accessed by using the $_request_data member of this class, which is the orignal data storage location for the request data.

Note, that the request data, for ease of use, already contains references to the L10n Databases of the Component and MidCOM itself located in this class. They are stored as 'l10n' and 'l10n_midcom'. Also availbale as 'config' is the current component configuratio and 'topic' will hold the current conten topic.

For those asking about "avoiding the problems of the view_* globals", this basically breaks down to the fact that multiple components use these variables simultaneously. If you invoke a dynamic_load within a style elemnt, you have good chances, that after it your original global $view variables have been overwritten by the style code of the dynamically loaded component.

Automatic handler class instantination

If you specify a class name instead of a class isntance as a exec handler, MidCOM will automatically create an instance of that class type and initialize it. These so-called handler classes must be a subclass of midcom_baseclasses_components_handler.

The subclasses you create should look about this:

 <?php
 class my_handler extends midcom_baseclasses_components_handler
 {
     function my_handler()
     {
         // just call the base class constructor, avoid
         // additional code at this point.
         parent::midcom_baseclasses_components_handler();
     }
 
     function _on_initialize()
     {
         // Add class initialization code here, all members have
         // been prepared, and the instance is already stable, so
         // you can safely work with references to $this here.
     }
 }
 ?>

The two methods for each handler have the same signature as if they were in the same class.

• todo: Exec Handler Baseclass
• todo: Automatic exec handler instantination
• todo: AIS Handler Subclass

Located in /midcom/baseclasses/components/request.php (line 208)