<!--
 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: MokoCassiopeia.Documentation
 REPO: https://github.com/mokoconsulting-tech/MokoCassiopeia
 FILE: docs/OVERRIDE_PHILOSOPHY.md
 VERSION: 03.08.04
 BRIEF: Philosophy and implementation of non-replacing alternative layouts
 PATH: /docs/OVERRIDE_PHILOSOPHY.md
-->

# Override Philosophy — MokoCassiopeia

## Core Principle: Add-On, Not Replacement

**MokoCassiopeia 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 MokoCassiopeia overrides use **`mobile.php`** naming instead of **`default.php`**:

```
❌ BAD (Replaces default):
src/templates/html/mod_virtuemart_cart/default.php

✅ GOOD (Alternative layout):
src/templates/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/mokocassiopeia/html/{extension}/{view}/{layout}.php`
2. **Extension's specified layout**: `{extension}/tmpl/{view}/{layout}.php`
3. **Template override for default layout**: `templates/mokocassiopeia/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 **MokoCassiopeia - 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/mokocassiopeia/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/templates/html/mod_menu/mainmenu.php`
- `src/templates/html/mod_menu/mainmenu_component.php`
- `src/templates/html/mod_menu/mainmenu_heading.php`
- `src/templates/html/mod_menu/mainmenu_url.php`
- `src/templates/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 **MokoCassiopeia - 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, MokoCassiopeia **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 MokoCassiopeia:

### ✅ 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/mokocassiopeia/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)