Creating Custom Admin Modules & Views

Creating our module

We can now finally create our module. We set the name of our module in our module.ini.append.php file and so eZ Publish will know to look for a module called “newsletter”. Within this module we can create many views which will be linked to a central module file so that eZ Publish can find all of them. Each view is comprised of two main files:

• A PHP file – this is used for carrying out any custom PHP logic required by the view. For instance, you can carry out database queries or process a specific user action.
• A TPL file – this is specified within the PHP file and is used to render what the user will see (template).

This approach provides a high level of flexibility as different TPL files can be used according to what happens within your custom PHP logic. The PHP file can also pass custom variables into views for use in the template. We will use this functionality later in the tutorial to pass feedback based on user actions.

To create our module, firstly create a folder named "modules" in the root of your extension. Within this create a folder with the name of the module. In our case the module is called "newsletter". All of our custom PHP code will be stored in this directory but first we need to create the central module file, called module.php, file so eZ Publish can find all of the views.

Please note that in this tutorial you will need to be logged in as a user with Admin rights. We will cover how to access the module for other users at the end of the tutorial.

Creating the module.php file

The module.php file is used to store details about the module. In particular it stores a list of views within the module and the permissions required within the module. The file itself is quite straightforward but it is important to include all necessary details when you create the file.

Within the “newsletter” folder you have just created (/extension/mynewsletter/modules/newsletter/), create a file called module.php and enter the following code:

<?php
$module = array( 'name' => 'newsletter' ); //the name of our module, this ties in with the name specified in module.ini.append.php and the name of the parent folder

$ViewList = array(); //add as many views as you want here:
$ViewList['userlist'] = array( 'script' => 'userlist.php',
                               'functions' => array( 'read' ));
//the script used to setup the template plus the user permissions required for it (also see below). The default navigation part is optional but can be used to default what template will be loaded for the left navigation (this can also be defined within the view’s PHP file)
     
//setting user permissions required by our module:
$FunctionList = array(); 
$FunctionList['read'] = array(); 
?>

The code is split into three parts:

Module Name

Firstly, we define the name of the module we are in. This will tie in with the folder we just created and also the module.ini.append.php file we created at the start of this tutorial. This will also be the name of the module used in the URL. For example, for this module all of the views in the module will be located as follows: http://www.mysite.com/admin/newsletter/xxx where xxx represents a view name.

Defining the Views within the Module

After this comes the definition of the PHP files associated with the views in the module. You can include as many views as you want here. We only declare the PHP file associated with the view as the template used to render the view may vary according to what happens in the PHP. Because of this the main template to render the view is specified in the PHP file associated with the view rather than in the module.php file.

In our case we are initially making only a single view called “userlist”. As with the name of the module, this will be used in the URL, therefore the path to our first view will be:

http://www.yoursite.com/admin/newsletter/userlist

Defining the Security Policies of the module

After the views we define the security policies associated with the module. If you want to read more about this then I would recommend reading the article Adding custom security policy limitations to your modules, we will only look it at in terms of basic usage in this tutorial.

Creating the view PHP file

We will now create the custom PHP file for the View. Initially, our PHP will not require any custom code above what is needed to setup the template.

<?php
/**
 * File containing the eZ Publish view implementation.
 *
 * @copyright Your Name here
 * @license licence details
 * @version 1.0.0
 * @package mynewsletter
 */
//setting up the eZ template object:
$tpl = eZTemplate::factory(); //this line of code is for ez publish 4.3, replace it with the following lines for versions prior to that
//version <4.3 of eZ Publish should use these lines of code instead:
//include_once( 'kernel/common/template.php' );
//$tpl = templateInit();

//carry out internal processing here, none required in this case.

// setting up what to render to the user:
$Result = array();
$Result['content'] = $tpl->fetch( 'design:newsletter/userlist.tpl' ); //main tpl file to display the output
$Result['left_menu'] = "design:newsletter/leftmenu.tpl"; //uncomment this line if you want to use a custom left navigation for this view.

$Result['path'] = array( array( 'url' => 'newsletter/users',
                                'text' => 'User List' ) ); //what to show in the Title bar for this URL
?>

The code can again be split into three parts:

Setting up Variables

In this case we are not doing any custom PHP and so the only variable we need is an instance of eZTemplate so that we can retrieve the template files.

//setting up the eZ template object:
$tpl = eZTemplate::factory();//this line of code is for ez publish 4.3, replace it with the following lines for versions prior to that
//version <4.3 of eZ Publish should use these lines of code instead:
//include_once( 'kernel/common/template.php' );
//$tpl = templateInit();

Please note that if your eZ Publish build is before 4.3, you will need to comment out the second line of code above and uncomment the other lines.

Carrying out custom PHP

For our simple example there is not any custom PHP but any required can be added straight after the variables have been setup (we will do this later in this tutorial)

//carry out internal processing here, none required in this case.

Establishing what to render

The final part of the code is required to setup what template(s) will be used to render the view and other view specific details we need to know before the page can be rendered for the user. In this section we can also set custom parameters to send to the template file (again, we will do this later in the tutorial).

// setting up what to render to the user:
$Result = array();
$Result['content'] = $tpl->fetch( 'design:newsletter/userlist.tpl' );//main tpl file to display the output
$Result['left_menu'] = "design:newsletter/leftmenu.tpl";//uncomment this line if you want to use a custom left navigation for this view.

$Result['path'] = array( array( 'url' => 'newsletter/users',
                                'text' => 'User List' ) );//what to show in the Title bar for this URL

There’s a couple of things to note here:

• The Result array is used by eZ Publish to establish what needs to be displayed to the user, based on what templates are stored within it
• Although the menu.ini file provides options for setting up a left navigation you must provide an implementation of a left menu to display to the user. In this tutorial we are going to provide a flat implementation but see this post for more details and an alternative implementation using ini file contents.

Now that we have a basic PHP file linking to our View template lets setup the templates for the main content and also the left navigation.

Please note that if you want to see the current progress, you can now visit http://www.yoursite.com/admin/newsletter/userlist and you should currently be returned a blank page (since we have not created our templates yet). As we create the templates refer to this address to view what we have done so far. In the URL above, replace 'admin' by the name of your administration interface siteaccess, if different. You may also be using a different access method than URI-based, in which case you can simply remove the siteaccess name.