Module handling

Modules are an abstract way of seeing a system, they are used for grouping together related functionality. For instance, all content handling code is placed in a module called content. Each module has a number of views associated with it. Each view represents a page in the web browser and can have a number of parameters associated to it. There are ordered parameters, which are the basis for the view, and additional parameters which are named and are unordered.

This system allows collections of view scripts to be seen as modules and views. All files belonging to a module are placed in a directory named after the module. This directory must contain a file called module.php, which defines the module and all it's views. The file normally looks like this (taken from content/module.php):

$Module = array( "name" => "eZContentObject",
                 "variable_params" => true );

$ViewList = array();
$ViewList["edit"] = array(
    "functions" => array( 'edit' ),
    'single_post_actions' => array( 'PreviewButton' => 'Preview',
                                    'TranslateButton' => 'Translate',
                                    'VersionsButton' => 'VersionEdit',
                                    'PublishButton' => 'Publish',
                                    'BrowseNodeButton' => 'BrowseForNodes',
                                    'DeleteNodeButton' => 'DeleteNode',
                                    'BrowseObjectButton' => 'BrowseForObjects',
                                    'StoreButton' => 'Store' ),
    'post_actions' => array( 'BrowseActionName' ),
    'post_action_parameters' => array( 'DeleteNode' => array( 'SelectedNodeList' => 'Content_node_id_checked' ) ),
    "script" => "edit.php",
    "params" => array( "ObjectID", "EditVersion" ) );

$ViewList["view"] = array(
    "functions" => array( 'read' ),
    "script" => "view.php",
    "params" => array( "ViewMode", "NodeID", "LanguageCode" ),
    "unordered_params" => array( "language" => "Language",
                                 "offset" => "Offset" )
    );

$Module

An array that must contain the name key which defines the real name of the module and variable_params which defines whether parameters are set as normal variables when the script is run.

$ViewList

An array with the available views in the module. Each entry consists of the following keys:

• functions - An array with functions that are used by the view, used for determining whether the view can be seen or not according to policies.
• script - The PHP file which should be run, it will be run using the eZProcess class.
• params - The ordered parameters for the view, they are usually taken from the URI or sent from the script which run this view. Each entry gives the name of the parameter which will be available in the script trough the $Params variable.
• unordered_params - An associative array with parameters which are defined by their name instead of order. They are usually optional to the view. Each key defines the name taken from the URL and the value defines the name available to the view.
• single_post_actions - Defines the post actions which should be translated into an action, the first one to be found is used. The key is the name found among the HTTP post variables and the value is the action name. This action is only set if an action is not set by the called code.
• post_actions - Similar to single_post_actions but instead it takes the value in the post variable and uses it as action name.
• post_action_parameters - An associative array of action names and their parameters. Each key is the action name and each value is another associative array of parameters. Each key is the parameter name and the value is the post variable name.

Fetching input parameters

Fetching the parameters is done by using the $Params variable, it is an associative array with all the parameters. The name of the parameter keys are defined by params. The Module parameter is always present and contains the current eZModule object.

$Module =& $Params['Module'];
$ObjectID =& $Params['ObjectID'];

Hooks

Hooks are a way of letting external code hook in extra code, the code will be run at places defined by the view using the runHooks() function. The external code can create a function and add it to the hook name. It is also possible to run a method in an object by supplying an array with the object and method name instead of the function name. Hooks can also have priorities to allow a hook to be run before/after another. The default is to give everything the same priority.

// Define the function and add the hook
function checkSomething( &$module, $objectID, $editVersion )
{
    // Do something and return
}

$Module->addHook( 'pre_fetch', 'checkSomething' );

// Run the hooks
if ( $Module->runHooks( 'pre_fetch', array( $ObjectID, $EditVersion ) ) )
    return;

Actions

To check which action is to be run use the currentAction or isCurrentAction functions. isCurrentAction will return true if the current action matches the action name supplied. Parameters for the action can be fetched with actionParameter and checked with hasActionParameter. These parameters are either fetched from post variables or set by the code running this view.

Return values

The return value is determined by the value sent by the return statement, or if there are no return statement it reads the variable called $Result. This variable is is sent to the client code executing the module/view.

Redirection

It's possible for the view code to issue a redirection, the redirection request will be read by the client that executes the view and it's up to that code to do anything. There are several different methods available for redirection.

• redirect - Redirects to a given module and view with some optional ordered and unordered parameters.
• redirectToView - Same as redirect but doesn't require a module since it's done in the current module.
• redirectTo - Redirects to a given URL, this is best used for custom URLs, if it's a module/view use redirect and redirectToView instead.
• redirectionURI - Creates a URI usable for redirection and can be passed to redirectTo, use this if you need a URI for a module/view and have to store it or send to some other code.