MokoOnyx v01.00.00 — initial release (successor to MokoCassiopeia)

All files renamed from mokocassiopeia to mokoonyx. Update server points to MokoOnyx repo. Bridge migration removed (clean standalone template). Version reset to 01.00.00. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-19 17:19:03 -05:00
parent 3ba2214614
commit 8258ed804a
238 changed files with 85443 additions and 2 deletions
--- a/docs/OVERRIDE_PHILOSOPHY.md
+++ b/docs/OVERRIDE_PHILOSOPHY.md
@@ -0,0 +1,332 @@
+<!--
+ Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+
+ This file is part of a Moko Consulting project.
+
+ SPDX-License-Identifier: GPL-3.0-or-later
+
+ This program is free software; you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation; either version 3 of the License, or
+ (at your option) any later version.
+ 
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ GNU General Public License for more details.
+ 
+ You should have received a copy of the GNU General Public License
+ along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+
+ # FILE INFORMATION
+ DEFGROUP: Joomla.Template.Site
+ INGROUP: MokoOnyx.Documentation
+ REPO: https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx
+ FILE: docs/OVERRIDE_PHILOSOPHY.md
+ VERSION: 03.09.03
+ BRIEF: Philosophy and implementation of non-replacing alternative layouts
+ PATH: /docs/OVERRIDE_PHILOSOPHY.md
+-->
+
+# Override Philosophy — MokoOnyx
+
+## Core Principle: Add-On, Not Replacement
+
+**MokoOnyx overrides are designed as alternative layouts, not replacements of default Joomla layouts.**
+
+This means:
+- ✅ Default Joomla layouts continue to work unchanged
+- ✅ Site administrators can choose when to use our enhanced layouts
+- ✅ Updates to Joomla core layouts don't break the site
+- ✅ Compatibility with other extensions is maintained
+- ✅ Users have control over which layouts to use
+
+---
+
+## Technical Implementation
+
+### Layout Naming Convention
+
+All MokoOnyx overrides use **`mobile.php`** naming instead of **`default.php`**:
+
+```
+❌ BAD (Replaces default):
+src/html/mod_virtuemart_cart/default.php
+
+✅ GOOD (Alternative layout):
+src/html/mod_virtuemart_cart/mobile.php
+```
+
+### How Joomla Handles Layouts
+
+When a module or component looks for a layout, Joomla searches in this order:
+
+1. **Template override with specified layout name**: `templates/mokoonyx/html/{extension}/{view}/{layout}.php`
+2. **Extension's specified layout**: `{extension}/tmpl/{view}/{layout}.php`
+3. **Template override for default layout**: `templates/mokoonyx/html/{extension}/{view}/default.php`
+4. **Extension's default layout**: `{extension}/tmpl/{view}/default.php`
+
+By naming our overrides `mobile.php` instead of `default.php`, they become **step 1** alternatives that must be explicitly selected, rather than **step 3** replacements that are automatically used.
+
+---
+
+## How to Use Alternative Layouts
+
+### Method 1: Module/Menu Item Settings
+
+When editing a module or menu item in Joomla administrator:
+
+1. Open the module/menu item for editing
+2. Navigate to the **Advanced** tab
+3. Find the **Alternative Layout** field
+4. Select **MokoOnyx - mobile** from the dropdown
+5. Save
+
+### Method 2: Override in Module Position
+
+If you want all modules in a specific position to use the mobile layout:
+
+```php
+<!-- In your index.php template file -->
+<?php if ($this->countModules('sidebar-left')) : ?>
+    <jdoc:include type="modules" name="sidebar-left" style="none" layout="mobile" />
+<?php endif; ?>
+```
+
+### Method 3: Module Chrome (Advanced)
+
+Create a custom module chrome in `templates/mokoonyx/html/layouts/chromes/` that automatically applies the mobile layout.
+
+---
+
+## Exception: Main Menu
+
+**The only exception** to this philosophy is `mod_menu` with the "Main Menu" module type.
+
+The template includes files like:
+- `src/html/mod_menu/mainmenu.php`
+- `src/html/mod_menu/mainmenu_component.php`
+- `src/html/mod_menu/mainmenu_heading.php`
+- `src/html/mod_menu/mainmenu_url.php`
+- `src/html/mod_menu/mainmenu_separator.php`
+
+These use a **custom layout name** (`mainmenu`) instead of replacing `default.php`, which allows the site to:
+- Use the enhanced Bootstrap 5 collapsible menu for main navigation
+- Keep standard Joomla menus working in other positions
+- Provide better mobile navigation without breaking existing menus
+
+To use this layout, set the module's **Alternative Layout** to **MokoOnyx - mainmenu**.
+
+---
+
+## Override Inventory
+
+### Module Overrides (16 total)
+
+All use `mobile.php` naming (alternative layout):
+
+**VirtueMart (5)**:
+- `mod_virtuemart_cart/mobile.php`
+- `mod_virtuemart_product/mobile.php`
+- `mod_virtuemart_currencies/mobile.php`
+- `mod_virtuemart_category/mobile.php`
+- `mod_virtuemart_manufacturer/mobile.php`
+
+**Community Builder (2)**:
+- `mod_cblogin/mobile.php`
+- `mod_comprofilerOnline/mobile.php`
+
+**Main Menu (1)**:
+- `mod_menu/mainmenu.php` (custom layout name)
+
+**Industry Extensions (8)**:
+- `mod_k2_content/mobile.php`
+- `mod_acymailing/mobile.php`
+- `mod_hikashop_cart/mobile.php`
+- `mod_kunenalatest/mobile.php`
+- `mod_kunenalogin/mobile.php`
+- `mod_kunenasearch/mobile.php`
+- `mod_kunenastats/mobile.php`
+- `mod_osmembership/mobile.php`
+
+### Component View Overrides (12 total)
+
+All use `mobile.php` naming (alternative layout):
+
+**Community Builder (4)**:
+- `com_comprofiler/userprofile/mobile.php`
+- `com_comprofiler/userslist/mobile.php`
+- `com_comprofiler/registers/mobile.php`
+- `com_comprofiler/login/mobile.php`
+
+**JEM - Joomla Event Manager (5)**:
+- `com_jem/eventslist/mobile.php`
+- `com_jem/event/mobile.php`
+- `com_jem/calendar/mobile.php`
+- `com_jem/venue/mobile.php`
+- `com_jem/categories/mobile.php`
+
+**Kunena Forum (1)**:
+- `com_kunena/category/mobile.php`
+
+**OSMembership (2)**:
+- `com_osmembership/plan/mobile.php`
+- `com_osmembership/plans/mobile.php`
+
+**Joomla Core (2)**:
+- `com_content/article/toc-left.php` (custom layout name)
+- `com_content/article/toc-right.php` (custom layout name)
+
+---
+
+## Benefits of This Approach
+
+### 1. **Zero Breaking Changes**
+
+Existing sites continue to work exactly as before. No layouts are forcibly changed.
+
+### 2. **Gradual Adoption**
+
+Site administrators can:
+- Test mobile layouts on specific modules first
+- Roll out changes module-by-module
+- Keep some modules using default layouts if needed
+- Easily revert by changing the Alternative Layout setting
+
+### 3. **Extension Compatibility**
+
+Third-party extensions' default layouts remain untouched, preventing conflicts with:
+- Extension updates
+- Other templates
+- Custom development
+
+### 4. **Joomla Core Updates**
+
+When Joomla core updates:
+- Default layouts get new features/bug fixes automatically
+- Mobile layouts remain stable and tested
+- No emergency fixes needed after Joomla updates
+
+### 5. **Multi-Language Support**
+
+Joomla's language system loads extension language files properly because:
+- Extensions aren't hijacked by template overrides
+- Language strings come from the correct source
+- Translations work as expected
+
+---
+
+## Standards Not Overridden
+
+Following Cassiopeia template best practices, MokoOnyx **does not override** standard Joomla core modules:
+
+- ❌ `mod_breadcrumbs` - Use Joomla core layout
+- ❌ `mod_login` - Use Joomla core layout
+- ❌ `mod_articles_latest` - Use Joomla core layout
+- ❌ `mod_articles_category` - Use Joomla core layout
+- ❌ `mod_articles_news` - Use Joomla core layout
+- ❌ `mod_search` - Use Joomla core layout (removed in v03.08.03)
+
+**Reason**: These modules have robust core layouts with proper language loading, accessibility, and ongoing Joomla maintenance.
+
+---
+
+## Developer Guidelines
+
+When adding new overrides to MokoOnyx:
+
+### ✅ DO:
+
+1. Name files `mobile.php` or use descriptive custom names (`mainmenu.php`, `toc-left.php`)
+2. Document the alternative layout in MODULE_OVERRIDES.md
+3. Add CSS with BEM naming: `.{extension}-{view}__element`
+4. Test that default layouts still work
+5. Provide clear instructions for selecting the layout
+
+### ❌ DON'T:
+
+1. Create `default.php` files that replace core layouts
+2. Override standard Joomla core modules without strong justification
+3. Break backward compatibility
+4. Assume users will automatically get your layout
+5. Forget to document how to enable the alternative layout
+
+---
+
+## Migration from Replacing Overrides
+
+If you're migrating from a template that used `default.php` overrides:
+
+### Step 1: Identify Replaced Layouts
+
+```bash
+find templates/oldtemplate/html -name "default.php"
+```
+
+### Step 2: Rename to Alternative Layouts
+
+```bash
+# For each default.php found:
+mv default.php mobile.php
+```
+
+### Step 3: Update Module Settings
+
+For each module using the old override:
+1. Edit module in administrator
+2. Advanced tab → Alternative Layout
+3. Select "mobile" from dropdown
+4. Save
+
+### Step 4: Test
+
+- Verify module displays correctly
+- Check that other modules still use default layouts
+- Confirm language strings load properly
+
+---
+
+## Troubleshooting
+
+### My Alternative Layout Doesn't Appear in Dropdown
+
+**Check:**
+1. File is in correct location: `templates/mokoonyx/html/{extension}/{view}/`
+2. File has `.php` extension
+3. File is not named `default.php`
+4. Cache is cleared (System → Clear Cache)
+
+### Module Still Uses Default Layout
+
+**Check:**
+1. Module's Alternative Layout setting in administrator
+2. Module position's `layout` parameter in `<jdoc:include>` tag
+3. File permissions (must be readable)
+4. Template is assigned to correct pages
+
+### Layout Works But Looks Wrong
+
+**Check:**
+1. CSS is loaded: inspect element and check for `.{extension}-{view}__` classes
+2. `template.css` is up to date
+3. Browser cache is cleared
+4. CSS variables are defined in template
+
+---
+
+## References
+
+- [Joomla Docs: Layout Overrides](https://docs.joomla.org/Layout_Overrides_in_Joomla)
+- [Joomla Docs: Alternative Layouts](https://docs.joomla.org/J3.x:How_to_use_the_alternative_layout_feature)
+- [MODULE_OVERRIDES.md](MODULE_OVERRIDES.md) - Complete override inventory
+- [CSS_VARIABLES.md](CSS_VARIABLES.md) - Template styling system
+
+---
+
+## Version History
+
+- **03.08.04**: Created OVERRIDE_PHILOSOPHY.md document
+- **03.08.03**: Removed mod_search override to align with philosophy
+- **03.08.02**: Removed standard Joomla module overrides for proper language loading
+- **Earlier**: Renamed all overrides from default.php to mobile.php (21 files)