What Are Submodules?

A submodule is a full module that lives inside another module's submodule/ directory. It has its own controller, views, assets, and models — but inherits its parent's frame and routing context. This lets you break large features into organized pieces without cluttering the top-level modules/ directory.

Directory Structure

Submodules live in a submodule/ directory inside their parent:

Each submodule is a self-contained module with the same structure as a top-level module — controller, views, assets, and models are all supported.

Namespace Convention

A submodule's namespace is its parent module name, not its own. This is how the framework's autoloader resolves submodule classes:

<?php
namespace Zero\Module\Ttrpg;

class Characters extends \Zero\Core\Module {

    public function index() {
        $this->respond($this->viewPath . 'index.php');
    }

    public function view($id) {
        $this->data = ['character_id' => $id];
        $this->respond($this->viewPath . 'view.php');
    }
}

Compare this to the parent module:

<?php
namespace Zero\Module;

class Ttrpg extends \Zero\Core\Module {

    public function index() {
        $this->respond($this->viewPath . 'index.php');
    }

    // No characters() method needed - the framework
    // automatically delegates to the submodule
}

URL Routing Delegation

When a URL comes in, the framework first tries to call the matching method on the parent module. If the method doesn't exist, it checks for a matching submodule via Module::__call():

1. URL /ttrpg/characters/view/5 arrives
2. Framework loads Ttrpg module and calls characters('view', '5')
3. Ttrpg has no characters() method — __call() fires
4. Framework finds submodule/Characters/Characters.php
5. Routing shifts: Characters::view('5') is called

Asset Loading for Submodules

Submodule assets are fully supported by the asset system. They are symlinked under the parent module's asset directory:

Auto-loading follows the same convention, scoped to the submodule. For the URL /ttrpg/hexmap/dm, the asset loader checks /assets/ttrpg/hexmap/css/ for:

The same $this->getStylesheets() and $this->getScripts() calls work in submodule frames — the methods automatically resolve to the correct submodule asset path.

Frame Inheritance

Submodules inherit their parent's frame templates (head, header, footer, sideNav) by default. The framework walks up the directory tree looking for frame files:

1. Check submodule: modules/Ttrpg/submodule/Characters/frame/
2. Check parent module: modules/Ttrpg/frame/
3. Fall back to app frame: app/frontend/frame/

This means a submodule gets the parent's header and navigation for free. Override any individual frame file by creating it in the submodule's own frame/ directory — only that file is overridden, the rest continue to inherit.

Infinite Nesting

Submodules can contain their own submodules, creating an arbitrarily deep hierarchy:

The URL /ttrpg/characters/inventory/view/42 would resolve to Inventory::view('42') through two levels of delegation. Each level follows the same namespace and routing rules.