Custom modules and views #

This page is for application creators who add screens to Exponential. A module is the first part of an address (/expdemo/...), a view the second (/expdemo/latest/...). The module's module.php declares its views and policies; each view is a script (or a class) that returns a result.

Contents #

1. Registering a module
2. Parameters
3. Handling forms: actions
4. The result
5. Redirects and errors
6. The class-based view
7. Overriding a kernel view

Registering a module #

# extension/expdemo/settings/module.ini.append.php
<?php /* #?ini charset="utf-8"?
[ModuleSettings]
ExtensionRepositories[]=expdemo
ModuleList[]=expdemo
*/ ?>

Modules live in extension/expdemo/modules/<module>/. The complete list of module.php keys is in module.php reference.

Parameters #

$ViewList['item'] = array(
    'script' => 'item.php',
    'functions' => array( 'read' ),
    'params' => array( 'ItemID' ),                      // /expdemo/item/42
    'unordered_params' => array( 'offset' => 'Offset' ) // /expdemo/item/42/(offset)/20
);

In the view, $Params['ItemID'] and $Params['Offset'] hold the values, as strings from the address: cast and validate them ((int), allow lists) before use (Input validation and output escaping).

Handling forms: actions #

Declare the buttons of a form as actions:

$ViewList['edit'] = array(
    'script' => 'edit.php',
    'functions' => array( 'edit' ),
    'params' => array( 'ItemID' ),
    'single_post_actions' => array( 'StoreButton' => 'Store', 'CancelButton' => 'Cancel' ),
    'post_action_parameters' => array( 'Store' => array( 'Title' => 'ItemTitle' ) ) );

$Module = $Params['Module'];
if ( $Module->isCurrentAction( 'Cancel' ) )
    return $Module->redirectTo( '/expdemo/list' );
if ( $Module->isCurrentAction( 'Store' ) && $Module->hasActionParameter( 'Title' ) )
{
    $title = trim( (string)$Module->actionParameter( 'Title' ) );
    // validate, store, then redirect (POST - redirect - GET)
}

Forms must post with the form token, which ezformtoken adds to method="post" forms automatically (Forms, CSRF protection and HTTP input).

The result #

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

content goes into the pagelayout, path becomes the breadcrumb and title. More keys and pagelayout choices: View results, templates and the pagelayout.

Redirects and errors #

Redirect targets that come from the request must be checked; the kernel's safe redirect helpers only follow addresses of the site (Safe redirects).

The class-based view #

New code writes the view as a class extending Exponential\Runnable\ModuleView; the view file becomes one line that calls it. The class can be tested and re-implemented by settings (A module view).

Overriding a kernel view #

An extension can override the templates or the views of a kernel module (Extension module override). Prefer adding your own module; an override must follow every kernel update.

Related pages #

• Your first extension
• Policy functions and limitations
• Module and view pattern
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.