Creating a Module

This tutorial will guide you through creating a simple "My Module" that adds a new menu item and a corresponding page.

Step 1: Create the Module Directory

All modules live inside the private/modules/ directory. Create a new folder for your module. The folder name should be unique and use PascalCase.

Step 2: Create the Manifest File

Every module requires a module.json file in its root directory. This file tells the system about your module.

File: private/modules/MyModule/module.json

{
    "name": "My First Module",
    "version": "1.0",
    "description": "A simple module that adds a new page.",
    "hooks": []
}

Step 3: Create the Initialization Script

The init.php script runs when an administrator activates your module. Its job is to set up everything the module needs, like database tables, menu items, and roles.

File: private/modules/MyModule/init.php

beginTransaction();

    // 1. Add a new role
    $pdo->exec("INSERT OR IGNORE INTO roles (name, is_system) VALUES ('my_module_view', 0)");

    // 2. Add a top-level menu item
    $stmt = $pdo->prepare("INSERT INTO menu_items (name, url, parent_id, order_num, is_dropdown, is_visible, required_role) VALUES ('My Module', NULL, NULL, 50, 1, 1, 'my_module_view')");
    $stmt->execute();
    $parentId = $pdo->lastInsertId();

    // 3. Add a sub-menu item linked to the parent
    $stmt = $pdo->prepare("INSERT INTO menu_items (name, url, parent_id, order_num, is_dropdown, is_visible, required_role) VALUES ('My Page', 'my_page.php', ?, 1, 0, 1, 'my_module_view')");
    $stmt->execute([$parentId]);

    // 4. Register the module itself
    $stmt = $pdo->prepare("INSERT INTO modules (name, path, is_active) VALUES ('My First Module', 'MyModule', 1)");
    $stmt->execute();

    // 5. Copy the public page
    copy(__DIR__ . '/my_page.php', PUBLIC_PATH . 'my_page.php');

    $pdo->commit();
    echo "My Module initialized successfully.";

} catch (Exception \$e) {
    if (\$pdo->inTransaction()) {
        \$pdo->rollBack();
    }
    die("Error initializing My Module: " . \$e->getMessage());
}
?>

Step 4: Create the De-initialization Script

The deinit.php script is the opposite of `init.php`. It runs when the module is deactivated and must clean up everything the `init.php` script created.

File: private/modules/MyModule/deinit.php

beginTransaction();

    // 1. Delete the menu items
    $pdo->exec("DELETE FROM menu_items WHERE url = 'my_page.php'");
    $pdo->exec("DELETE FROM menu_items WHERE name = 'My Module'");

    // 2. Delete the role
    $pdo->exec("DELETE FROM roles WHERE name = 'my_module_view'");

    // 3. Delete the module record
    $pdo->exec("DELETE FROM modules WHERE path = 'MyModule'");

    // 4. Delete the public page
    if (file_exists(PUBLIC_PATH . 'my_page.php')) {
        unlink(PUBLIC_PATH . 'my_page.php');
    }

    $pdo->commit();
    echo "My Module deinitialized successfully.";

} catch (Exception \$e) {
    if (\$pdo->inTransaction()) {
        \$pdo->rollBack();
    }
    die("Error deinitializing My Module: " . \$e->getMessage());
}
?>

Step 5: Create the Public Page

This is the actual page the user will see. It must include the authentication header and check for the required role.

File: private/modules/MyModule/my_page.php

Hello from My Module!
This page is part of a custom module.

Step 6: Package Your Module

To prepare your module for installation, you must package it correctly.

1. Find your module's folder (e.g., `MyModule`) inside `private/modules/`.
2. Using your operating system's file manager or a command-line tool, create a ZIP archive of the **entire `MyModule` folder**.
3. Rename the resulting file from `MyModule.zip` to `MyModule.dmod`.

Step 7: Activation

Finally, navigate to Administrator -> Module Manager in the application to upload and activate your newly created .dmod file.