 |
VOOZH | about |
|
VOOZH | about |
This document explains Maho's theme system architecture, including directory structure, fallback mechanisms, package organization, and theme customization. It covers the separation between design templates and skin assets, theme inheritance, and how themes are selected and configured.
For information about layout XML and block rendering, see Layout XML and Blocks. For core layout system architecture, see Layout System. For CSS architecture and responsive design implementation, see Responsive Design and CSS Architecture.
Maho implements a dual-directory theme system that separates template logic from static assets. This separation enables efficient caching, CDN distribution, and clear organization of frontend resources.
Design Directory (app/design/frontend/ lib/MahoCLI/Commands/HealthCheck.php50): Contains template files (.phtml), layout XML, translation files, and theme configuration. These files contain PHP logic and are processed server-side.
Skin Directory (public/skin/frontend/ lib/MahoCLI/Commands/HealthCheck.php51): Contains static assets (CSS, JavaScript, images) that are served directly to browsers without PHP processing. Note that the application environment provides commands to manage these assets, such as flushing minified caches maho37
The following diagram maps the logical structure of a theme to the physical directory locations used by the system.
Sources: app/code/core/Mage/Core/Model/Design/Package.php13-19 app/code/core/Mage/Core/Model/Design/Package.php30-58 lib/MahoCLI/Commands/HealthCheck.php50-51
Themes follow a two-level naming convention: Package/Theme. This structure is managed by Mage_Core_Model_Design_Package app/code/core/Mage/Core/Model/Design/Package.php13
| Component | Description | Example |
|---|---|---|
| Package | Top-level grouping of related themes | base, rwd, custom |
| Theme | Specific design variation within a package | default, modern, blue |
| Full Path | Combined package and theme name | base/default, rwd/default |
The system defines several constants for default values:
DEFAULT_AREA: frontend app/code/core/Mage/Core/Model/Design/Package.php15DEFAULT_PACKAGE: default app/code/core/Mage/Core/Model/Design/Package.php16DEFAULT_THEME: default app/code/core/Mage/Core/Model/Design/Package.php17BASE_PACKAGE: base app/code/core/Mage/Core/Model/Design/Package.php18Sources: app/code/core/Mage/Core/Model/Design/Package.php13-19
Maho implements a cascading fallback system via Mage_Core_Model_Design_Fallback. It searches for files in multiple locations, enabling theme inheritance and partial overrides without duplicating entire theme files.
When Maho needs to load a template file, Mage_Core_Model_Design_Package follows a specific resolution order. The system uses store-specific base URLs for skin and template resolution app/code/core/Mage/Core/Model/Store.php57-62
The Mage_Core_Model_Design_Package class handles the logic for finding files. It uses a _shouldFallback flag to determine if the hierarchy should be checked app/code/core/Mage/Core/Model/Design/Package.php80
Sources: app/code/core/Mage/Core/Model/Design/Package.php13-107 app/code/core/Mage/Core/Model/Design/Package.php229-260 app/code/core/Mage/Core/Model/Store.php57-62
Template files use the .phtml extension and combine HTML markup with PHP logic. These files are typically rendered within the context of a block object.
Templates support inline translation, allowing merchants to edit text directly on the frontend. The Mage_Core_Model_Translate_Inline model processes response bodies to replace translation tokens with editable HTML fragments app/code/core/Mage/Core/Model/Translate_Inline.php197-222 It uses a regex token {{{...}}} to identify translatable strings app/code/core/Mage/Core/Model/Translate_Inline.php19
Maho provides several structural templates. These define the layout of the storefront and are selected via Layout XML.
These layouts are also reflected in the translation files, for example, app/locale/en_US/Mage_Page.csv app/locale/en_US/Mage_Page.csv6-9
Maho is transitioning from legacy Varien_ classes to Maho\ namespaces. The app/bootstrap.php file provides class aliases for backward compatibility app/bootstrap.php29-101 Developers should prefer using the new Maho\ namespaced classes, such as Maho\DataObject instead of Varien_Object app/bootstrap.php101
Sources: app/code/core/Mage/Core/Model/Translate_Inline.php12-25 app/code/core/Mage/Core/Model/Translate_Inline.php197-222 app/bootstrap.php26-101 app/design/frontend/base/default/template/page/1column.phtml app/design/frontend/base/default/template/page/2columns-left.phtml app/design/frontend/base/default/template/page/2columns-right.phtml app/design/frontend/base/default/template/page/3columns.phtml app/locale/en_US/Mage_Page.csv6-9
Themes are configured at the store view level, enabling multi-store installations to use different designs per store. The Mage_Core_Model_Design_Package class retrieves these configurations using Mage::getStoreConfig() app/code/core/Mage/Core/Model/Design/Package.php159
| Config Path | Class Property | Default |
|---|---|---|
design/package/name | $_name | default |
design/theme/template | $_theme['template'] | default |
design/theme/skin | $_theme['skin'] | default |
design/theme/layout | $_theme['layout'] | default |
The package name is resolved in setPackageName():
app/code/core/Mage/Core/Model/Design/Package.php159-160
Maho supports dynamic theme switching based on the browser's User-Agent string. This is evaluated in setPackageName() using regex patterns defined in design/package/ua_regexp app/code/core/Mage/Core/Model/Design/Package.php155-158
Themes are segmented into types (layout, template, skin, locale). The setTheme() method handles setting these specific components or setting all types at once app/code/core/Mage/Core/Model/Design/Package.php229-246
Sources: app/code/core/Mage/Core/Model/Design/Package.php151-169 app/code/core/Mage/Core/Model/Design/Package.php229-246
Maho provides a CLI command to streamline theme creation:
php maho frontend:theme:create maho98
base/default: This package is reserved for core updates and serves as the ultimate fallback.base package via the Mage_Core_Model_Design_Fallback mechanism app/code/core/Mage/Core/Model/Design/Package.php82-92php maho health-check command to identify legacy files or deprecated folders (like the old skin folder in root vs public/skin) that might interfere with modern theme architecture lib/MahoCLI/Commands/HealthCheck.php22-43Sources: maho98 app/code/core/Mage/Core/Model/Design/Package.php82-92 lib/MahoCLI/Commands/HealthCheck.php22-43
Refresh this wiki