Confessions of an apprentice: Creating eZ Publish modules

The answer is: modules. Creation of a new module is relatively easy and painless, and it can really help out in situations ranging from a simple modification to the existing code (for example, if you have a segment of a site which does one thing, and you need such a segment to do the same thing but with different parameters), to setting up a whole range of features you won’t find in the regular extensions or the modules found in the eZ Publish installation.

Creation of modules in eZ Publish

What is a module anyway?

Well, the easiest explanation would be: a module is a set of views. You know views, you’ve probably overridden the templates for a view or two. The basic modules are defined in the module.ini file which is located in the settings folder of your eZ Publish installation. And if you open that file, you’ll see a list of all the modules which are installed by default. Just be sure not to modify that file since modifying it will screw up your installation. Consider yourself warned. So, you can see a pretty big list of modules such as class, collaboration, error, package, pdf, etc. And even though all of those modules are useful and needed, the actual user only sees a handful of those.

You’re probably wondering how a person even accesses a module. The short and simple answer is: through the url. What you see on a page in the address bar is actually just the url aliases of the parts of a page you are accessing. In actuality, what you access is a module, and a view defined in that module, with some parameters defined for good measure. The first module, and probably the most commonly used is the content module. When you open a page for the first time, you’re actually viewing the following url: http://name_of_page/content/view/full/2. The /content/view/full/2 is something probably unfamiliar to those who are beginners in eZ Publish, so I’ll break it down for easy explanation. The /content/ part is the name of the module, /view/ is the name of the view, /full/ is the view mode, and /2 is the node id accessed. How do we know this? Where is this module located? Why, in the kernel, of course!

If you look at the kernel folder, you’ll see a folder in it for every module available. Each of these folders has a set of PHP scripts which relate to each and every view of a module, and the module.php file which relates to the module in question. Now, this file is the key file in the creation of a module. It defines all of the views and the parameters this module will have. And some of the PHP files which relate to views have a template file in the templates folder of the design of your page. As you can see, the views are PHP scripts which handle certain actions a website can perform (like a JSON interface or redirections, just to name a few), and not all of them have a template assigned to them. It is also important to keep in mind that a template is just a visual representation of a view. And a module is an HTTP interface which provides a grouping of such views.

You’re probably scratching your head now, re-reading this last paragraph, and trying to figure it out. Have no fear, and read on, we’ll tackle the creation of modules which will most definitely clear out some of the issues.

Creation of a module

The first thing you need to set up is the ini file. For the remainder of this series, I’ll assume you have a test installation of eZ Publish, and that it’s called mypage with an already set up extension of the same name. You need to put a new appendix to the existing module.ini file in the settings folder of your extension. Create a new file called module.ini.append.php in your /extension/mypage/settings folder, and put the following lines of code in it:

[ModuleSettings]
ExtensionRepositories[]=mypage
ModuleList[]=mymodule

With this, you have declared that you want your extension to contain additional modules, and you’ve declared a name for your module. Also, since you’ve put this module just in the /extension/mypage/settings folder, and not in any of the folders in the /extension/mypage/settings/siteaccess folder, this module will be accessible from every siteaccess.

After that, you need to actually define the module. And in that purpose, create the next folder: /extension/mypage/modules/mymodule/ and put a PHP file in it which you’ll name module.php. Also, open this file, and put the following lines of code in it:

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

As you can see, we have created three arrays here which define the settings and data for the module. The $Module array relates to the module itself, it’s name, and some general parameters we wish the module to use. The $ViewList array is an array composed of the definitions of views you wish the module to handle, and last but not least, $FunctionList is a list of policy functions you wish the module to use. Which is basically assignment to different groups of users who can handle the views. So, let’s fill some of those arrays with data, shall we?

To make things simple, I’ll create a view which will redirect a user to the doc.ez.no website, that is, to the documentation page for eZ Publish. I still won’t teach you how to actually assign a template to this view, because it will be a simple redirection, so we won’t need a template, only the PHP script to do its stuff.

Under the line in which you’ve defined the $ViewList array, put in the following lines of code:

$ViewList['redirect']= array(
'script' => 'redirect.php'
);

What we’ve basically done here is, we’ve defined a view called redirect, and a script for that view which will be performed after we access the url: http://mypage/mymodule/redirect, and it will redirect us to the doc.ez.no website.

The next step is the creation of mentioned script. So, create a file in the same folder called redirect.php and put the following lines of code inside:

<?php
eZHTTPTool::redirect('http://doc.ez.no');
?>

Now, bear in mind, since we didn’t put any policy functions in our view, it will only work if you’re logged in as the administrator of the page. For a view to function properly, you need to define additional parameters which will further extend all the possibilities a view can perform. But, all of those will be covered in the next article when we’ll talk about setting up a view, and defining functions of that view. We’ll cover the template part of the view also.

Clear the Global cache, and go to the url http://mypage/mymodule/redirect and hopefully, if you set up everything as described, you will be redirected to the doc.ez.no website.

As you can see, the actual creation of a module is not that hard, and it’s really a matter of your needs. And as I said before, you can rely on modules to do some additional stuff your default installation of eZ Publish doesn’t cover. With that said, look forward to the next article when we break down a view, and define parameters of that view.

Until next time, I wish you happy coding,
Tomislav