Module

« 
Previous article
|
eZ
|
Next article
 »

Table of contents:

What is a Module?

A Module offers an HTTP interface to a declared grouping or collection of Views.  The default modules are declared in the default module.ini file.  For example /kernel/content is a folder in the file system holding the View scripts of the 'content' Module. The module name 'content', declared in the module.ini, is used in URLs to route requests to the appropriate PHP View script file held on the file system for execution. 

Modules are normally named as nouns while views are often named as a verb or a verb-object. e.g.  http://www.example.com/index.php/user/login  - where 'user' is the module and 'login' is the view.

Module development

eZ publish provides for custom applications and components through support of many kinds of extensions which a developer or administrator can install. One of which is a module or custom module. Custom modules often use custom settings, designs, classes, cronjobs, workflows, triggers, etc.

Module extensions

When adding an extension which provides modules, the eZ publish kernel needs to know that your extension contains modules. In extension/ extensionname /settings/module.ini.append:

 

By declaring your module's name in the ModuleList setting array, you also make sure that the eZ publish URL system does not reuse your module's URL as the nice URL of a content node.

Module definition

The actual definition of your module has to be placed in a file extension/extensionname/modules/modulename/module.php.

<?php  

$Module = array( 'name' => 'mymodule', 'variable_params' => false, 'ui_component_match' => 'module' );
$ViewList = array();
$FunctionList = array(); 

?>

The $Module array will contain global settings and data for your module. The following keys in this array are used by eZ publish:

Key

Type

Default

Usage

name

string

  

Alternative name of the module used in some debug statements (for example: Undefined view mymodule::foo when you try to access a non-existing view).

variable_params

boolean

false

Defines if you want to import variables into the view scripts' symbol table. When false you need to access the variables from the $Params array. You will find more information on this in the chapter "Views"

ui_component_match

string: module|view

module

The string module (default) or view. Defines whether the module or view name will be used as the default ui_component for all views of this module

function

array

  

If your module contains only one view, then you can define the view here. The URl to the view will consist of only the module name.

$ViewList will contain the view definitions, you will find more information on views in the next chapter. $FunctionList will contain the policy function definitions, you will find more information on policy functions in the chapter "Policy functions".

Views

Definition

A module can have one or more views. You need to define your views in the $ViewList array. If your module contains only one view, you can also choose to define it with the "function" key in the module definition. If you define your view in this way, actions are not supported.

$ViewList = array();
$ViewList['viewname'] = array(
    'script' => 'myview.php',
     'params' => array( 'param1', 'param2' ),
    'ui_context' => 'navigation',
     'ui_component' => 'myuicomponent',
     'default_navigation_part' => 'ezmynavigationpart',
     'unordered_params' => array( 'param3ModuleName' => 'param3UrlName' , 'param4ModelName' => 'param4UrlName' ),
     'default_action' => array(
         array(
             'name' => '',
             'type' => 'post',
             'parameters' = array( 'postvariablename' ) ),
     'single_post_actions' => array( 'postvariablename' => 'actionname' ),
     'post_actions' => array( 'postvariablename' )
     'post_action_parameters' => array( 'actionname' => array( 'parametername' => 'postvariablename' ) ),
     'post_value_action_parameters' => array( 'actionname' => array( 'parametername' => 'postvariablenamestart' )
);

The keys of the $ViewList array are the names of the views, the values are the view definitions.

The following keys in your view definition are used by eZ publish:

Key

Type

Default

Usage

script

string

  

Filename of the view's PHP script.

params

array

  

The names of the parameters you can pass to the view by putting their values in the URL. For example: module/view/parametervalue

ui_context

string

navigation

Defines the UI context of the view.

ui_component

string

module or view name, depending on the "ui_component_match" key in the module definition

Defines the UI component of the view.

default_navigation_part

string

  

Defines the navigation part string of the view. The view result can override this.

unordered_params

array

  

The names of the parameters you can pass to the view by putting their name + value in the URL ( For example: module/view/(parametername)/parametervalue ). Please note the mapping here; in the view definition you define the name of the parameter in the url and also the according name for the parameter in the module script.

default_action

array

    

single_post_actions

array

  

If the current action is not yet determined it will use the definitions in module.php for finding out the current action. It first looks trough the single_post_actions array in the selected view mode, the key to each element is the name of the post-variable to match, if it matches the element value is set as the action. 'single_post_actions' => array( 'PreviewButton' => 'Preview', 'PublishButton' => 'Publish' )

post_actions

array

  

If none of these matches it will use the elements from the post_actions array to find a match. It uses the element value for each element to match agains a post-variable, if it is found the contents of the post-variable is set as the action. 'post_actions' => array( 'BrowseActionName' )

post_action_parameters

array

  

A 2-level array defining the POST variables that will be accessible in the module, depending on the current action. The array keys are the action names, the values are an array with the key being the post var. name and the value being the php var. name. 'post_action_parameters' => array( 'EditLanguage' => array( 'SelectedLanguage' => 'EditSelectedLanguage' ) )

post_value_action_parameters

array

    

Troubleshooting

Possible debug messages:

  • error "eZProcess", "PHP script $file does not exist, cannot run" The file specified with the "script" key doesn't exist. Maybe you misspelled it or you forgot to create it.

Policy functions

Simple example that shows 2 views and 2 policy functions. A user need to have the permission to use the function 'editors' in order to access the 'set_priority' view.

$Module = array( 'name' => 'services' );

$ViewList = array();
$ViewList[ 'set_priority'] = array( 'script' => 'set_priority.php',
                                    'functions' => array( 'editors' ) );

$ViewList[ 'right_column'] = array( 'script' => 'right_column.php',
                                    'functions' => array( 'public' ) );

$FunctionList = array();
$FunctionList[ 'public' ] = array();
$FunctionList[ 'editors' ] = array();

More Info: http://share.ez.no/forums/developer/limiting-within-viewlist-possible and the policy functions feature documentation.

Fetch functions

See custom fetch.

Module php script

In the module definition you define which php script a module view should run. In that php script you can implement your custom functionality and return to module output as the module result. Usually the module result is the inner part of the pagelayout template. In order to return the module output you have to save the output as $Result['content'].

Module $Result

content

module output

pagelayout

a template file for a custom pagelayout, or a boolean false to skip using a pagelayout

path

see Module Path
   

Examples

Use a Custom Pagelayout

A module can have a custom pagelayout template located at this path: extension/my_module/design/standard/templates/my_module/pagelayout.tpl. To use it in your module.php:

$Result = array();
$Result['pagelayout'] = 'my_module/pagelayout.tpl';

Module Path

A module can have one or more views. You should to define your views path in the $Result['path'] array.

Examples

No URL

$Result = array();
$Result['path'] = array( array( 'url' => false, 'text' => 'Database Query Manager' ) );

Two levels without URL

$Result['path'] = array(
    array( 'url' => false, 'text' => 'Order ' ),
    array( 'url' => false, 'text' => 'Refund Completed' )
);

Multi-level with URL

$Result['path'] = array(
    array( 'url' => '/', 'text' => 'Home' ),
    array( 'url' => '/account', 'text' => 'My account' ),
    array( 'url' => '/account/addressbook', 'text' => 'Addressbook' )
);

Multi-level with URL and node ID

Adding node IDs to the path will help you to mark parent items as selected in the site menu. In this example "My account" will be selected if node 78 is a folder.

$Result['path'] = array(
    array( 'url' => '/', 'text' => 'Home' ),
    array( 'url' => '/My-account', 'node_id' => 78, 'text' => 'My account' ),
    array( 'url' => false, 'text' => 'Addressbook' )
);

You will also need to set a dummy node ID for the menu selection to work, e.g.

$Result['node_id'] = false;

Operations

...

Troubleshooting

If eZ Publish doesn't seem to want to load your module, then you might want to check out some useful tips to get it to work at the Troubleshooting extensions page.

External reference