Admin Interface

The Admin Interface provides the management console for Maho e-commerce operations. It includes modernized authentication (Passkeys and 2FA), role-based access control (ACL), administrative controllers, data grids, forms with validation, and JavaScript utilities for rich interactions. This document covers the architecture, components, and implementation patterns specific to the administrative backend.

SCOPING: This page has child pages

This is a PARENT page. The following child pages exist and will cover their topics in detail:

• Admin Architecture — Explain adminhtml area, ACL system, menu structure, and admin routing.
• WYSIWYG Editor (TipTap) — Deep dive into TipTap integration, extensions, custom nodes, widgets, and image handling.
• Grid and Form Components — Cover admin grids, forms, varienForm validation, and dynamic field dependencies.
• Admin JavaScript Utilities — Detail mahoFetch, event system, tree components, and admin UI patterns.

Admin Architecture Overview

The Maho admin interface is built upon the adminhtml area. It uses a specific routing system where the frontName is typically admin. Security is enforced through a robust ACL (Access Control List) system defined in adminhtml.xml files app/code/core/Mage/Adminhtml/etc/adminhtml.xml121-156

Authentication and Security

Maho has modernized the admin login flow to include:

• Passkey Support: Integrated via maho-passkey-tools.js for biometric/hardware authentication app/design/adminhtml/default/default/layout/admin.xml24-29
• Two-Factor Authentication (2FA): A multi-step login process app/design/adminhtml/default/default/template/login.phtml55-65
• CSRF Protection: Every state-changing request requires a form_key, which is inserted into forms via a global block app/design/adminhtml/default/default/layout/main.xml31-33
• Secure Password Reset: Implements token-based reset flows with strict length requirements app/design/adminhtml/default/default/template/resetforgottenpassword.phtml28-40

Admin Request Lifecycle

Sources:

• app/design/adminhtml/default/default/template/login.phtml25-140
• app/design/adminhtml/default/default/layout/main.xml31-33
• app/design/adminhtml/default/default/template/resetforgottenpassword.phtml28-53
• app/code/core/Mage/Adminhtml/etc/adminhtml.xml121-156

Interface Components

The admin UI is composed of structural elements defined in the layout system. The default handle in main.xml establishes the root structure, including the header, menu, and breadcrumbs app/design/adminhtml/default/default/layout/main.xml39-91

Component	Code/Template Entity	Key Responsibilities
Menu	adminhtml/page_menu	Renders the top navigation based on adminhtml.xml app/design/adminhtml/default/default/layout/main.xml69
ACL	adminhtml.xml	Defines menu hierarchy and permission resources app/code/core/Mage/Adminhtml/etc/adminhtml.xml14-120
Health Check	Mage_Adminhtml_Block_System_Tools_Healthcheck	Provides system diagnostic interface app/design/adminhtml/default/default/layout/admin.xml116-120
Email Log	Mage_Core_Block_Adminhtml_Email_Log	Administrative view of outgoing system emails app/design/adminhtml/default/default/layout/admin.xml123-132
Cron Jobs	Mage_Cron_Block_Adminhtml_Cron_Jobs	Manages scheduled tasks app/code/core/Mage/Cron/etc/adminhtml.xml8-12
Global Search	adminhtml/index/globalSearch	Provides quick search functionality across admin entities app/design/adminhtml/default/default/template/page/header.phtml37-47

Data Management Patterns

Maho bridges the gap between server-side PHP logic and client-side interaction using standardized block classes and layout handles. Specific handles like adminhtml_system_account_index load specialized assets such as maho-passkey-tools.js app/design/adminhtml/default/default/layout/admin.xml24-29

Sources:

• app/design/adminhtml/default/default/layout/main.xml39-91
• app/code/core/Mage/Adminhtml/etc/adminhtml.xml14-120
• app/design/adminhtml/default/default/layout/admin.xml24-29
• app/design/adminhtml/default/default/template/page/header.phtml37-47
• app/code/core/Mage/Adminhtml/controllers/System/Tools/HealthcheckController.php13-38
• app/code/core/Mage/Cron/etc/adminhtml.xml8-12

Grid and Form Components

The admin interface relies heavily on standardized components. Layouts reference specialized blocks for editing permissions, users, and roles app/design/adminhtml/default/default/layout/admin.xml46-90 These components utilize maho-tree.js for hierarchical data like category trees or ACL resource trees app/design/adminhtml/default/default/layout/admin.xml32-43

Maho also provides specific grids for managing "orphaned" ACL resources, which are entries in the database that no longer correspond to defined resources in the adminhtml.xml or api.xml files.

• For Admin ACL: Mage_Adminhtml_Block_Permissions_OrphanedResource_Grid app/code/core/Mage/Adminhtml/Block/Permissions/OrphanedResource/Grid.php14-73 uses Mage_Admin_Model_Resource_Rules::getOrphanedResourcesCollection() app/code/core/Mage/Admin_Model/Resource/Rules.php99-107 to identify and manage these.
• For API ACL: Mage_Adminhtml_Block_Api_OrphanedResource_Grid app/code/core/Mage/Adminhtml/Block/Api/OrphanedResource/Grid.php13-72 uses Mage_Api_Model_Resource_Rules::getOrphanedResourcesCollection() app/code/core/Mage/Api/Model/Resource/Rules.php78-86

For a deep dive into creating these components, see Grid and Form Components.

Sources:

• app/design/adminhtml/default/default/layout/admin.xml46-90
• app/design/adminhtml/default/default/layout/admin.xml32-43
• app/code/core/Mage/Adminhtml/Block/Permissions/OrphanedResource/Grid.php14-73
• app/code/core/Mage/Admin_Model/Resource/Rules.php99-107
• app/code/core/Mage/Adminhtml/Block/Api/OrphanedResource/Grid.php13-72
• app/code/core/Mage/Api/Model/Resource/Rules.php78-86

Admin JavaScript Framework

Maho's admin JS framework provides utilities for building interactive interfaces. A central utility is mahoFetch, an asynchronous wrapper for the Fetch API that automatically handles isAjax flags and JSON response parsing app/design/adminhtml/default/default/template/page/header.phtml37-64 The layout system loads several specialized libraries for UI components like maho-dialog.js, maho-tree.js, and sortable.min.js app/design/adminhtml/default/default/layout/main.xml43-54

For details on the utility functions and event patterns, see Admin JavaScript Utilities.

Sources:

• app/design/adminhtml/default/default/template/page/header.phtml37-64
• app/design/adminhtml/default/default/layout/main.xml41-65

WYSIWYG and Content Editing

Maho has transitioned to the TipTap editor for content management. This is integrated into the layout system via the editor handle app/design/adminhtml/default/default/layout/main.xml119-131 The handle ensures that tiptap/setup.js is loaded only when needed app/design/adminhtml/default/default/layout/main.xml121-122 The system supports dynamic configuration, including widget insertion, variable injection, and image browsing via browser.js app/design/adminhtml/default/default/layout/main.xml123-126

For implementation details, see WYSIWYG Editor (TipTap).

Sources:

• app/design/adminhtml/default/default/layout/main.xml119-131
• app/design/adminhtml/default/default/layout/admin.xml140-145