Wiki
Search

Object information

3913

16/12/2006 3:14 pm
Kristof Coomans

31/05/2008 10:50 am
Kristof Coomans

24

126

This article

Module

Table of contents:

This is a Stub article. Help the eZ Publish community by expanding it!

Module development

eZ publish provides for custom applications and components through support of many kinds of different extensions one of which is a module or custom module. Custom modules often use custom settings, designs, classes, cronjobs, workflows, triggers, etc. Custom module classes often extend the persistent object class.

Module extensions

The eZ publish kernel needs to know that your extension contains modules. In extension/extensionname/settings/module.ini.append: 

[ModuleSettings]
ExtensionRepositories[]=extensionname
ModuleList[]=modulename

By putting your module's name in the ModuleList setting array, you 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 scipts' 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 wether 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

   

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

Coming soon. You can already take a look at https://ez.no/community/forum/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

   

Module Path

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

Here is one example with no url 

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

Here is one with two levels and without a url 

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

Here is a multi level with url example 

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

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