Controllers: module views #

This page is for developers who write controllers. In Exponential the unit that handles one address is a view of a module. Classic views are PHP scripts that the kernel includes with $Params and $Module set; since 6.0.15 a view is best written as a class extending Exponential\Runnable\ModuleView, with a one-line script that calls it (Commands, cronjob parts and module views as classes).

Contents #

1. Controller and view side by side
2. The script form
3. The class form
4. Keeping it thin
5. Before and after the view
6. Changing a kernel view

Controller and view side by side #

The script form #

<?php
// extension/expdemo/modules/expdemo/item.php
$Module = $Params['Module'];
$item = expDemoItem::fetch( (int)$Params['ItemID'] );
if ( !$item )
    return $Module->handleError( eZError::KERNEL_NOT_FOUND, 'kernel' );

$tpl = eZTemplate::factory();
$tpl->setVariable( 'item', $item );

$Result = array();
$Result['content'] = $tpl->fetch( 'design:expdemo/item.tpl' );
$Result['path'] = array( array( 'text' => 'Items', 'url' => 'expdemo/list' ),
                         array( 'text' => $item->attribute( 'title' ), 'url' => false ) );

expDemoItem::fetch() stands for a static method of your own persistent object class (ORM: eZPersistentObject). The result keys are explained on Responses, redirects, errors and JSON.

The class form #

From A module view:

<?php
// extension/myext/classes/runnable/views/report/show.php
namespace Exponential\View\Extension\Myext\Report;

class Show extends \Exponential\Runnable\ModuleView
{
    public function run( array $scope )
    {
        $Module = $scope['Params']['Module'];
        $tpl = \eZTemplate::factory();
        $tpl->setVariable( 'report', \myReportService::build( $scope['Params']['Month'] ) );
        return array( 'content' => $tpl->fetch( 'design:report/show.tpl' ),
                      'path' => array( array( 'text' => 'Report', 'url' => false ) ) );
    }
}

<?php
// extension/myext/modules/report/show.php (named in module.php ViewList as before)
return \Exponential\View\Extension\Myext\Report\Show::main( __FILE__, get_defined_vars() );

The class can be unit tested, wrapped by events and re-implemented by settings. Remember to regenerate the extension autoloads after adding the class (php bin/php/ezpgenerateautoloads.php -e).

Keeping it thin #

The kernel itself puts work that a view, a command and a cronjob part share into service classes, for example Exponential\Service\Trash for the trash view, bin/php/trashpurge.php and the trashpurge cronjob part (Services). Do the same: parse and check input in the view, call a plain class for the work, render the result. The plain class is what you test without a database (Testing).

Before and after the view #

Every class-based view runs between two events: runnable/view/before (notify) and runnable/view/after (a filter that receives and must return the result). Register listeners in site.ini [RunnableSettings] Listeners[]. That is the nearest thing to controller-level interceptors such as Spring's HandlerInterceptor or a Symfony kernel.controller listener (Events and listeners).

Changing a kernel view #

# settings/override/site.ini.append.php, or an extension's settings/site.ini.append.php
[RunnableSettings]
Implementation[Exponential\View\Kernel\Content\History]=myHistoryView

No kernel file is copied, so the next release updates the original underneath your subclass.

Related pages #

• Custom modules and views
• Routing: modules, views and parameters
• Module view templates
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.