Routing: modules, views and parameters #

This page is for developers used to a route table (routes.yaml, routes/web.php, urls.py, config/routes.rb). Exponential has no route table. An address is read as /<module>/<view>/<parameters>, and the module's module.php declares which views exist and which parameters they take. Pretty addresses are a separate layer, URL aliases, that is translated to a module address before this step (Pretty URLs).

Contents #

1. The convention
2. Registering a module
3. Parameters
4. HTTP methods and actions
5. Generating URLs
6. What a router user will miss

The convention #

With URI siteaccess matching, the siteaccess name comes first (/admin/content/view/full/2) and is removed before the module is looked up (Siteaccesses).

Registering a module #

A module is a directory with a module.php in a module repository. The kernel's repositories are settings/module.ini [ModuleSettings] ModuleRepositories[] (kernel, kernel/private/modules); an extension adds its own and lists the module, which makes it reachable:

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

<?php
// extension/expdemo/modules/expdemo/module.php
$Module = array( 'name' => 'Demo' );

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

$FunctionList = array();
$FunctionList['read'] = array();

Every key of $ViewList entries is listed in the module.php reference. After adding a module, clear the INI cache (php bin/php/ezcache.php --clear-tag=ini) and, under Velocity, deploy (Servers and deployment).

Parameters #

Parameters arrive as strings. There are no type constraints or requirements in the declaration: cast and validate in the view ((int), allow lists) (Validation).

HTTP methods and actions #

A view answers every method; there is no methods: [POST] in the declaration. Forms are handled as actions: the view declares which POST button means which action, and the code asks $Module->isCurrentAction( 'Store' ):

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

Check the method yourself where it matters (a JSON endpoint that must only accept POST), and let ezformtoken protect every POST (Forms and CSRF).

Generating URLs #

There are no route names: the module/view path is the name. Keep the paths of your module in one helper class if many places build them.

What a router user will miss #

• Route names and reverse routing by name: build the module path instead.
• Requirements, defaults and converters per parameter: do it in the view.
• Method-specific routes: use actions, or check the method in the view.
• Annotation or attribute routes: module.php is the only declaration.
• Arbitrary pretty paths for your module views: URL aliases point at content nodes; for your own views use global URL aliases or wildcards to give a module address a friendlier one (Pretty URLs).

Related pages #

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