From d66f357cb8fdcf6b346f9e0d9b95fedeff4aaf24 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 27 Feb 2026 04:26:16 +0000 Subject: [PATCH] Add comprehensive override philosophy documentation Co-authored-by: jmiller-moko <230051081+jmiller-moko@users.noreply.github.com> --- docs/MODULE_OVERRIDES.md | 49 ++++++ docs/OVERRIDE_PHILOSOPHY.md | 332 ++++++++++++++++++++++++++++++++++++ docs/README.md | 10 +- 3 files changed, 389 insertions(+), 2 deletions(-) create mode 100644 docs/OVERRIDE_PHILOSOPHY.md diff --git a/docs/MODULE_OVERRIDES.md b/docs/MODULE_OVERRIDES.md index 7acd309..04d342b 100644 --- a/docs/MODULE_OVERRIDES.md +++ b/docs/MODULE_OVERRIDES.md @@ -39,6 +39,17 @@ MokoCassiopeia includes **16 mobile-responsive module overrides** and **12 compo **Important**: Following Cassiopeia template best practices, MokoCassiopeia avoids overriding standard Joomla core modules (such as mod_search, mod_login, mod_breadcrumbs) to ensure proper language loading and compatibility. **Exception**: mod_menu "Main Menu" override provides essential Bootstrap 5 collapsible dropdown functionality. +### Alternative Layouts, Not Replacements + +**All MokoCassiopeia overrides use alternative layout names (`mobile.php`) instead of replacing default layouts (`default.php`).** This means: + +- ✅ Default Joomla layouts continue to work unchanged +- ✅ You must explicitly select the "mobile" layout in module/menu item settings +- ✅ Joomla core updates don't break your site +- ✅ Full control over which modules use enhanced layouts + +**📖 See [OVERRIDE_PHILOSOPHY.md](OVERRIDE_PHILOSOPHY.md) for complete details on how to activate and use these alternative layouts.** + ### Key Features All module overrides share these characteristics: @@ -655,16 +666,54 @@ Override CSS variables in your custom color scheme: --- +## How to Activate Alternative Layouts + +All MokoCassiopeia overrides are **alternative layouts** that must be explicitly activated. They do not automatically replace default layouts. + +### Quick Start: Enable Mobile Layout + +1. **Go to Joomla Administrator** → Extensions → Modules +2. **Open the module** you want to enhance (e.g., VirtueMart Cart) +3. **Navigate to Advanced tab** +4. **Find "Alternative Layout" field** +5. **Select "MokoCassiopeia - mobile"** from dropdown +6. **Save & Close** + +### For Menu Items (Component Views) + +1. **Go to Menus** → Select your menu +2. **Open the menu item** (e.g., Events List) +3. **Navigate to Advanced Options or Page Display tab** +4. **Find "Alternative Layout" field** +5. **Select "MokoCassiopeia - mobile"** from dropdown +6. **Save & Close** + +### Apply to All Modules in a Position + +In your template's `index.php`, specify layout for entire module position: + +```php + +``` + +**📖 For complete documentation, see [OVERRIDE_PHILOSOPHY.md](OVERRIDE_PHILOSOPHY.md)** + +--- + ## Version History | Version | Date | Changes | |----------|------------|--------------------------------------------------| +| 03.08.04 | 2026-02-27 | Added alternative layout activation instructions, JEM overrides | +| 03.08.03 | 2026-02-25 | Removed mod_search override per Cassiopeia philosophy | +| 03.08.00 | 2026-02-22 | Added Community Builder component overrides | | 03.07.00 | 2026-02-22 | Initial release of all mobile-responsive overrides | --- ## Additional Resources +- **Override Philosophy**: [OVERRIDE_PHILOSOPHY.md](OVERRIDE_PHILOSOPHY.md) ⭐ **Start here** - **Main README**: [README.md](../README.md) - **Changelog**: [CHANGELOG.md](../CHANGELOG.md) - **CSS Variables**: [CSS_VARIABLES.md](CSS_VARIABLES.md) diff --git a/docs/OVERRIDE_PHILOSOPHY.md b/docs/OVERRIDE_PHILOSOPHY.md new file mode 100644 index 0000000..e2736fd --- /dev/null +++ b/docs/OVERRIDE_PHILOSOPHY.md @@ -0,0 +1,332 @@ + + +# 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 + +countModules('sidebar-left')) : ?> + + +``` + +### 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 `` 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) diff --git a/docs/README.md b/docs/README.md index 6696f6f..03ddd74 100644 --- a/docs/README.md +++ b/docs/README.md @@ -61,11 +61,17 @@ This directory contains comprehensive documentation for the MokoCassiopeia Jooml * Light and dark mode theming * **[Module & Component Overrides](MODULE_OVERRIDES.md)** - Mobile-responsive overrides guide - * 20 module overrides + 3 component overrides - * VirtueMart, Joomla core, Community Builder, industry extensions + * 16 module overrides + 12 component overrides + * VirtueMart, Community Builder, JEM, Kunena, industry extensions * Mobile-first responsive design patterns * Accessibility features and customization +* **[Override Philosophy](OVERRIDE_PHILOSOPHY.md)** ⭐ - Alternative layouts, not replacements + * Why overrides use `mobile.php` naming instead of `default.php` + * How to activate alternative layouts in Joomla + * Benefits of non-replacing overrides + * Developer guidelines and best practices + * **[Roadmap](ROADMAP.md)** - Version-specific roadmap * Current features (v03.07.00) * Feature evolution timeline