Jonathan Miller
40cce64afc
Adds src/html/mod_custom/hero.php — a banner-overlay style template override for mod_custom, mirroring Cassiopeia's banner layout pattern. Includes background image support via WebAssetManager and respects the Module Manager's moduleclass_sfx field. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
README - MokoCassiopeia (VERSION: 03.06.03)
A Modern, Lightweight Joomla Template Based on Cassiopeia
MokoCassiopeia is a modern, lightweight enhancement layer built on top of Joomla's Cassiopeia template. It adds Font Awesome 7, Bootstrap 5 helpers, an automatic Table of Contents (TOC) utility, advanced Dark Mode theming, and optional integrations for Google Tag Manager and Google Analytics (GA4)—all while maintaining minimal core template overrides for maximum upgrade compatibility.
📑 Table of Contents
- Features
- Requirements
- Installation
- Quick Start
- Configuration
- Theme System
- Development
- Documentation
- Changelog
- Support
- Contributing
- Included Libraries
- License
✨ Features
Core Enhancements
- Built on Cassiopeia: Extends Joomla's default template with minimal overrides
- Font Awesome 7: Fully integrated into Joomla's asset manager with 2,000+ icons
- Bootstrap 5: Extended utility classes and responsive grid system
- No Template Overrides: Clean installation that inherits all Cassiopeia defaults
- Upgrade-Friendly: Minimal modifications ensure smooth Joomla updates
Advanced Theming
- Dark Mode Support: Built-in light/dark mode toggle with system preference detection
- Color Palettes: Standard, Alternative, and Custom color schemes
- Theme Persistence: User preferences saved via localStorage
- Theme Control Options: Switch, radio buttons, or hidden controls
- Auto Dark Mode: Optional automatic dark mode based on time/system settings
- Meta Tags: Automatic color-scheme and theme-color meta tags
Developer Features
- Custom Code Injection: Add custom HTML to
<head>start/end - Drawer Sidebars: Configurable left/right drawer positions with custom icons
- Font Options: Local and web fonts (Roboto, Fira Sans, Noto Sans)
- Sticky Header: Optional sticky navigation
- Back to Top: Floating back-to-top button
Analytics & Tracking
- Google Tag Manager: Optional GTM integration with container ID configuration
- Google Analytics: Optional GA4 integration with measurement ID
- Privacy-Friendly: All tracking features are optional and easily disabled
Content Features
- Table of Contents: Automatic TOC generation for long articles
- Placement options:
toc-leftortoc-rightlayouts - Automatic heading extraction and navigation
- Responsive sidebar positioning
- Placement options:
📋 Requirements
- Joomla: 4.4.x or 5.x
- PHP: 8.0 or higher
- Database: MySQL 5.7+ / MariaDB 10.2+ / PostgreSQL 11+
- Browser Support: Modern browsers (Chrome, Firefox, Safari, Edge)
📦 Installation
Note: MokoCassiopeia is a standalone Joomla template extension (not bundled as a package). Install it directly via Joomla's Extension Manager.
Via Joomla Extension Manager
- Download the latest
mokocassiopeia-{version}.zipfrom Releases - In Joomla admin, navigate to System → Install → Extensions
- Upload the ZIP file and click Upload & Install
- Navigate to System → Site Templates
- Set MokoCassiopeia as your default template
Via Git (Development)
git clone https://github.com/mokoconsulting-tech/MokoCassiopeia.git
cd MokoCassiopeia
See Development Guide for development setup.
🚀 Quick Start
1. Install the Template
Install mokocassiopeia.zip via Joomla's Extension Manager.
2. Set as Default
Navigate to System → Site Templates and set MokoCassiopeia as default.
3. Configure Template Options
Go to System → Site Templates → MokoCassiopeia to configure:
- Branding: Upload logo, set site title/description
- Theme: Configure color schemes and dark mode
- Layout: Set container type (static/fluid), sticky header
- Analytics: Add GTM/GA4 tracking codes (optional)
- Custom Code: Inject custom HTML/CSS/JS
4. Test Dark Mode
The template includes a dark mode toggle. Test it by:
- Using the floating theme toggle button (bottom-right by default)
- Checking theme persistence across page loads
- Verifying system preference detection
⚙️ Configuration
Global Parameters
Access template configuration via System → Site Templates → MokoCassiopeia.
Theme Tab
General Settings:
- Theme Enabled: Enable/disable theme system
- Theme Control Type: Switch (Light↔Dark), Radios (Light/Dark/System), or None
- Default Choice: System, Light, or Dark
- Auto Dark Mode: Automatic dark mode based on time
- Meta Tags: Enable color-scheme and theme-color meta tags
- Bridge Bootstrap ARIA: Sync theme with Bootstrap's data-bs-theme
Variables & Palettes:
- Light Mode Palette: Standard, Alternative, or Custom
- Dark Mode Palette: Standard, Alternative, or Custom
Typography:
- Font Scheme: Local (Roboto) or Web fonts (Fira Sans, Roboto+Noto Sans)
Branding & Icons:
- Brand: Enable/disable site branding
- Logo File: Upload custom logo (no default logo included)
- Site Title: Custom site title
- Site Description: Tagline/description
- Font Awesome Kit: Optional FA Pro kit code
Header & Navigation:
- Sticky Header: Enable fixed header on scroll
- Back to Top: Enable floating back-to-top button
Theme Toggle UI:
- FAB Enabled: Enable floating action button toggle
- FAB Position: Bottom-right, Bottom-left, Top-right, or Top-left
Advanced Tab
- Layout: Static or Fluid container
Google Tab
- Google Tag Manager: Enable and configure GTM container ID
- Google Analytics: Enable and configure GA4 measurement ID
Custom Code Tab
- Custom Head Start: HTML injected at start of
<head> - Custom Head End: HTML injected at end of
<head>
Drawers Tab
- Left Drawer Icon: Font Awesome icon class (e.g.,
fa-solid fa-chevron-right) - Right Drawer Icon: Font Awesome icon class (e.g.,
fa-solid fa-chevron-left)
Custom Theme Palettes
MokoCassiopeia supports custom theme schemes:
- Copy template files from
/templates/directory:light.custom.css→media/templates/site/mokocassiopeia/css/theme/light.custom.cssdark.custom.css→media/templates/site/mokocassiopeia/css/theme/dark.custom.css
- Customize the CSS variables to match your brand colors
- Enable in Joomla: System → Site Templates → MokoCassiopeia → Theme tab → Set palette to "Custom"
- Save and view your site with custom colors
Note: Custom color files are excluded from version control (.gitignore) to prevent fork-specific customizations from being committed.
Quick Example:
:root[data-bs-theme="light"] {
--color-primary: #1e40af;
--color-link: #2563eb;
--color-hover: #1d4ed8;
--body-color: #1f2937;
--body-bg: #ffffff;
}
Complete Reference: See CSS Variables Documentation for all available variables and detailed usage examples.
Table of Contents
Enable automatic TOC for articles:
- Edit an article in Joomla admin
- Navigate to Options → Layout
- Select toc-left or toc-right
- Save the article
The TOC will automatically generate from article headings (H2, H3, etc.) and appear as a sidebar.
🎨 Theme System
Dark Mode Features
- Automatic Detection: Respects user's system preferences
- Manual Toggle: Floating button or radio controls
- Persistence: Saves preference in localStorage
- Smooth Transitions: Animated theme switching
- Comprehensive Support: All components themed for dark mode
Theme Control Types
- Switch: Simple light/dark toggle button
- Radios: Three options - Light, Dark, System
- None: No visible control (respects system only)
Meta Tags
When enabled, the template adds:
<meta name="color-scheme" content="light dark">
<meta name="theme-color" content="#1e3a8a" media="(prefers-color-scheme: dark)">
<meta name="theme-color" content="#ffffff" media="(prefers-color-scheme: light)">
🛠 Development
For Contributors
New to the project? See Quick Start Guide for a 5-minute setup.
Development Resources
- Quick Start Guide - Setup and first steps
- Joomla Development Guide - Testing, quality checks, deployment
- Workflow Guide - Git workflow and branching
- Contributing Guide - Contribution guidelines
- Roadmap - Feature roadmap and planning
Development Tools
- Pre-commit Hooks: Automatic validation before commits
- PHP CodeSniffer: Code style validation (Joomla standards)
- PHPStan: Static analysis for PHP code
- Codeception: Testing framework
Quick Development Setup
# Clone repository
git clone https://github.com/mokoconsulting-tech/MokoCassiopeia.git
cd MokoCassiopeia
# Install development dependencies (if using Composer)
composer install --dev
# Run code quality checks
make validate # or manual commands
Building Template Package
See Joomla Development Guide for packaging instructions.
📚 Documentation
User Documentation
- README - This file (overview and features)
- CHANGELOG - Version history and changes
- Roadmap - Planned features and timeline
Developer Documentation
- Quick Start - 5-minute developer setup
- Development Guide - Comprehensive development guide
- Workflow Guide - Git workflow and processes
- CSS Variables Reference - Complete CSS customization guide
- Documentation Index - All documentation links
Governance
- Contributing - How to contribute
- Code of Conduct - Community standards
- Governance - Project governance model
- Security Policy - Security reporting and procedures
📖 Changelog
See the CHANGELOG.md for detailed version history.
Recent Releases
- [03.06.03] (2026-01-30) - README updates and TOC color variable improvements
- [03.06.02] (2026-01-30) - Complete rebrand to MokoCassiopeia, removed all overrides
- [03.06.00] (2026-01-28) - Version standardization
- [03.05.01] (2026-01-09) - Security and compliance improvements
- [02.00.00] (2025-08-30) - Dark mode toggle and improved theming
💬 Support
Getting Help
- Documentation: Check this README and docs folder
- Issues: Report bugs via GitHub Issues
- Discussions: Ask questions in GitHub Discussions
- Roadmap: View planned features in Roadmap
Reporting Bugs
Please include:
- Joomla version
- PHP version
- Template version
- Steps to reproduce
- Expected vs actual behavior
- Screenshots (if applicable)
Security Issues
Do not report security vulnerabilities via public issues. See SECURITY.md for reporting procedures.
🤝 Contributing
We welcome contributions! Please see CONTRIBUTING.md for guidelines.
How to Contribute
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes
- Run quality checks
- Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
Development Workflow
See Workflow Guide for detailed Git workflow.
Customizations
For template customizations, use Joomla's built-in template settings (System → Site Templates → MokoCassiopeia → Custom Code tab) for HTML/CSS/JS customizations.
📦 Included Libraries
MokoCassiopeia includes the following third-party libraries to provide enhanced functionality:
Bootstrap TOC
- Version: 1.0.1
- Author: Aidan Feldman
- License: MIT License
- Source: GitHub Repository
- Release: v1.0.1 Release
- Purpose: Automatically generates a table of contents from article headings with scrollspy support
- Location:
src/media/vendor/bootstrap-toc/ - Integration: Registered in
joomla.asset.jsonasvendor.bootstrap-toc(CSS) andvendor.bootstrap-toc.js(JavaScript) - Usage: Activated when using
toc-leftortoc-rightarticle layouts - Features:
- Automatic TOC generation from H1-H6 headings
- Hierarchical nested navigation
- Active state highlighting with scrollspy
- Responsive design (collapses on mobile)
- Smooth scrolling to sections
- Automatic unique ID generation for headings
- Customizations: CSS adapted to use Cassiopeia CSS variables for theme compatibility
Font Awesome 7 Free
- Version: 7.0 (Free)
- License: Font Awesome Free License
- Source: Font Awesome
- Purpose: Provides 2,000+ vector icons for interface elements
- Location:
src/media/vendor/fa7free/ - Integration: Fully integrated into Joomla's asset manager
- Styles Available: Solid, Regular, Brands
Bootstrap 5
- Version: 5.x (via Joomla)
- License: MIT License
- Source: Bootstrap
- Purpose: Provides responsive grid system and utility classes
- Integration: Inherited from Joomla's Cassiopeia template, extended with additional helpers
- Components Used: Grid, utilities, modal, dropdown, collapse, offcanvas, tooltip, popover, scrollspy
Integration Method
All third-party libraries are:
- ✅ Properly licensed and attributed
- ✅ Registered in Joomla's Web Asset Manager (
joomla.asset.json) - ✅ Loaded on-demand to optimize performance
- ✅ Versioned and documented for maintenance
- ✅ Compatible with Joomla 4.4.x and 5.x
📄 License
This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.
Third-Party Licenses
- Joomla! CMS: GPL-2.0-or-later
- Cassiopeia Template: GPL-2.0-or-later (Joomla Project)
- Font Awesome 7 Free: Font Awesome Free License
- Bootstrap 5: MIT License
- Bootstrap TOC: MIT License (A. Feld)
All third-party libraries and assets remain the property of their respective authors and are credited in source files.
🔗 Links
- Repository: GitHub
- Issue Tracker: GitHub Issues
- Discussions: GitHub Discussions
- Roadmap: Full Roadmap
- Moko Consulting: Website
📊 Metadata
- Maintainer: Moko Consulting Engineering
- Author: Jonathan Miller (@jmiller-moko)
- Repository: https://github.com/mokoconsulting-tech/MokoCassiopeia
- License: GPL-3.0-or-later
- Classification: Public Open Source Standards
📝 Revision History
| Date | Version | Change Summary | Author |
|---|---|---|---|
| 2026-01-30 | 03.06.03 | Updated README title, fixed custom color variables instructions, improved TOC color scheme integration | Copilot Agent |
| 2026-01-30 | 03.06.02 | Regenerated README with comprehensive documentation and updated structure | Copilot Agent |
| 2026-01-30 | 03.06.02 | Complete rebrand to MokoCassiopeia, removed overrides | Copilot Agent |
| 2026-01-05 | 03.00.00 | Initial publication of template documentation and feature overview | Moko Consulting |
| 2026-01-05 | 03.00.00 | Fixed malformed markdown table formatting in revision history | Jonathan Miller (@jmiller-moko) |
Made with ❤️ by Moko Consulting