Admin Interface System Manual

1. Overview

The Admin Interface System manages all WordPress admin pages for the LineagePress plugin.
It follows a strict Controller/Renderer design pattern, ensuring a clean separation between:

• Business Logic (Controllers) – Data handling, database access, and logic.
• Presentation (Renderers) – HTML output and UI rendering.

This separation simplifies maintenance, debugging, and testing. No business logic is mixed with HTML, and HTML files remain free from PHP complexity.

---

2. Architectural Flow

Each admin page request follows the same lifecycle:

1. Menu Registration (HP_Admin_Menu_Handler)
   When WordPress builds the admin menu, the register_menus() method in \LineagePress\Core\HP_Admin_Menu_Handler is called.
   It registers all menu and sub-menu pages and maps each to a static callback method.
2. User Click & Dispatch
   When a user selects a menu item (e.g., “Dashboard”), WordPress calls the matching method (e.g., public static function dashboard()).
3. Renderer Instantiation
   The callback creates an instance of the proper Renderer class, e.g. $renderer = new \LineagePress\Admin\Renderers\HP_Dashboard_Page_Renderer();
4. Renderer Takes Control
   The callback triggers the renderer’s display method: $renderer->render_dashboard_with_tabs();
5. Controller Handles Data
   The renderer creates its Controller (e.g., HP_Dashboard_Controller) and fetches data.
6. Data Fetching & Preparation
   The controller retrieves and formats data for display.
7. HTML Rendering
   The renderer uses this data to produce the final HTML output.

Flow Summary:

Admin Menu Click
    ↓
HP_Admin_Menu_Handler
    ↓
Renderer
    ↓
Controller
    ↓
(Data)
    ↓
Renderer
    ↓
(HTML)

---

3. Core Components

includes/class-hp-admin-menu-handler.php

• Acts as the central hub for all admin pages.
• The only class hooked into the admin_menu action.
• Its static methods delegate control to the appropriate Renderer or Controller.

---

Controllers

Location: admin/controllers/
Purpose: Handle logic and data.

Responsibilities:

• Process $_POST form submissions.
• Register and manage AJAX actions.
• Query and manipulate data via Database System classes.
• Perform calculations and logic.

Rules:

• ❌ No HTML or echo statements.
• ✅ Return data (usually arrays or objects) for the renderer to use.

---

Renderers

Location: admin/renderers/
Purpose: Handle presentation and output.

Responsibilities:

• Enqueue page-specific CSS and JS.
• Instantiate the relevant Controller.
• Generate and echo HTML output.

Rules:

• ❌ No business logic.
• ✅ All data preparation must be handled by the Controller.

---

4. Adding a New Admin Page

Example: Adding a new page called “My Page”.

---

Step 1: Create the Controller

File: admin/controllers/class-hp-my-page-controller.php

<?php
namespace LineagePress\Admin\Controllers;

class HP_My_Page_Controller {
    public function get_page_data() {
        return [
            'title' => 'My Awesome Page',
            'items' => ['Apple', 'Banana', 'Cherry']
        ];
    }
}

---

Step 2: Create the Renderer

File: admin/renderers/class-hp-my-page-renderer.php

<?php
namespace LineagePress\Admin\Renderers;

class HP_My_Page_Renderer {
    public function render_page() {
        $controller = new \LineagePress\Admin\Controllers\HP_My_Page_Controller();
        $data = $controller->get_page_data();

        echo '<div class="wrap">';
        echo '<h1>' . esc_html($data['title']) . '</h1>';
        echo '<ul>';
        foreach ($data['items'] as $item) {
            echo '<li>' . esc_html($item) . '</li>';
        }
        echo '</ul>';
        echo '</div>';
    }
}

---

Step 3: Register the Menu Item

Edit includes/class-hp-admin-menu-handler.php:

// In register_menus()
add_submenu_page(
    'lineagepress',
    __('My Page', 'lineagepress'),
    __('My Page', 'lineagepress'),
    'manage_options',
    'lineagepress-my-page',
    [__CLASS__, 'my_page']
);

// Add the callback
public static function my_page() {
    $renderer = new \LineagePress\Admin\Renderers\HP_My_Page_Renderer();
    $renderer->render_page();
}

---

✅ Result:
Your new page will now appear under the “LineagePress” admin menu, fully integrated into the system architecture.

---