Gentics Portal.Node PHP Guide

Chapters

1. Introduction

2. Module folders

3. New Module

4. Using modules

5. Testing of a new module

1 Introduction

A module is a self-contained software unit that consists of models, views, controllers and other supporting components. In many aspects, a module resembles to an application. The main difference is that a module cannot be deployed alone and it must reside inside of an application (in our case the portal). Users can access the controllers in a module like they do with normal application controllers.

Modules are useful in several scenarios. For a large-scale application, we may divide it into several modules, each being developed and maintained separately.

Some commonly used features, such as user management, comment management, may be developed in terms of modules so that they can be reused easily in future projects.

2 Module folders

There are two folders for modules inside Gentics Portal.Node PHP:

• common
• custom

In the common folder core modules and components are stored. These files shouldn`t be touched or changed.

In the custom folder all client specific files are stored, i.e. configurations, widgets templates, mail templates, client specific modules, overwritten modules.

3 New Module

A module is organized as a directory whose name serves as its unique ID. The structure of the module directory is similar to that of the application base directory. The following shows the typical directory structure of a module named forum:

forum/
   ForumModule.php            the module class file
   components/                containing reusable user components
      views/                  containing view files for widgets
   controllers/               containing controller class files
      DefaultController.php   the default controller class file
   extensions/                containing third-party extensions
   models/                    containing model class files
   views/                     containing controller view and layout files
      layouts/                containing layout view files
      default/                containing view files for DefaultController
         index.php            the index view file

A module must have a module class that extends from CWebModule. The class name is determined using the expression ucfirst($id).‘Module’, where $id refers to the module ID (or the module directory name).

The module class serves as the central place for storing information shared among the module code.

For example, we can use CWebModule::params to store module parameters, and use CWebModule::components to share application components at the module level.

To create new module named ‘post’:

• Create new folder in /custom/modules/post
• Create PHP-file /custom/modules/post/PostModule.php with following content:

class PostModule extends CWebModule {
 	public function init() {
		// do what has to be done...
		echo '<h2>Hello World</h2>';
	}
}

4 Using modules

To use a module declare its ID and class location in the modules property of the application. For example, in order to use the above post module, we can use the following application configuration:

return array(
    ......
    'modules'=>array(
        'post'=>array(
            //alias to module class location,
            //then will converted into real path
            'class' => 'custom.modules.post.PostModule'
        )

    ,...
    ),
    ......
);

A module can also be configured with initial property values. The usage is very similar to configuring application components.

For example, the forum module may have a property named postPerPage in its module class which can be configured in the application configuration as follows:

return array(
    ......
    'modules'=>array(
        'post'=>array(
            'class' => 'custom.modules.post.PostModule',
            'postPerPage'=>20,
        ),
    ),
    ......
);

The module instance may be accessed via Yii::app()->getModule method.

Through the module instance, we can then access information that are shared at the module level.

For example, in order to access the above postPerPage information, we can use the following expression:

$postPerPage=Yii::app()->getModule('post')->postPerPage;

A controller action in a module can be accessed using the route moduleID/controllerID/actionID.

For example, assuming the above forum module has a controller named PostController, we can use the route forum/post/create to refer to the create action in this controller.

The corresponding URL for this route would be http://www.example.com/index.php?r=forum/post/create.

5 Testing of a new module

Follow this questions to check if you really finished your module?

Approval criterias

• go through requirements specification!
• go through technical concept!
• is your module secure?
• have you checked the developer guidelines for potential problems?
• have you implemented I18N?
• have you documented each class AND method, general german translation is required
• have you implemented localization (date / numbers)?
• have you implemented unit tests?
• have you added documentation to guides?
• have you added a language flag to the data object if necessary (i.e. comments)?
• has the module a widget available (if there is a visual output)?
• are the inputs in a form evaluated on the server-side (against model)?
• have you checked open issues for this module and resolved them?