Jonathan Miller
97d3133843
* Add mod_custom hero layout override and bump version to 03.09.01 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> * Ignore and untrack .claude/settings.local.json Adds .claude/settings.local.json to .gitignore and removes it from version control to keep local Claude Code permissions out of the repo. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * Ship custom palette starters and update template description - Add src/templates/light.custom.css and dark.custom.css as starter palette files that ship with the template, giving users a full variable reference to copy and customise - Register src/templates/ folder in templateDetails.xml <files> - Update <description> in templateDetails.xml: correct palette source paths, add Custom CSS & JavaScript section (user.css / user.js), link docs to GitHub repo docs/ directory - Sync en-GB and en-US tpl_mokocassiopeia.sys.ini with same changes, preserving British/American spelling variants; bump version to 03.09.01 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * Add CSS Variables reference tab to template options Adds a new 'CSS Variables' tab to the template configuration with eight documented sections (brand, typography, navigation, header background, container backgrounds, borders/shadows, forms/focus) so site builders can reference all available custom properties without leaving Joomla admin. Also removes external docs links from descriptions in templateDetails.xml and both language files, replacing them with a pointer to the new tab. Fixes stale custom palette source paths in en-GB and en-US ini files. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * Expand CSS Variables tab to full variable reference and add custom-hero class - Replace 8-field CSS Variables tab with 21 comprehensive sections covering all variables from light.standard.css and dark.standard.css - New sections: Links, Layout & Spacing, Breakpoints, Bootstrap Semantic Palette, Bootstrap State Colors, Alert & List Group Colors, Standard Colors/Grays/Opacity, Shadows & Shadow Tokens, Buttons, Cards, Component & Plugin Colors, VirtueMart, Gable - Add custom-hero class to hero.php outer div (always present) - Both en-GB and en-US language files updated Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * Add Google Search Console verification and ensure all Google services coexist - Add googlesitekey param to Google fieldset in templateDetails.xml - Inject <meta name="google-site-verification"> via setMetaData() in index.php, component.php, and offline.php - GTM, GA, and Search Console verification can now all be active simultaneously - Add language strings for new field in en-US and en-GB Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * Add header-aside module position to the right of the logo - New position renders inside .header-brand-wrap, right-aligned via margin-inline-start: auto on .container-header-aside - CSS: .header-brand-wrap uses flexbox so logo stays left, aside floats right - Registered in templateDetails.xml positions list - Language strings added to both en-US and en-GB sys.ini files Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * Add minify build script and generate .min CSS/JS; rename position to brand-aside Build tooling: - Add package.json with clean-css and terser dev dependencies - Add scripts/minify.js: reads joomla.asset.json, auto-detects source/.min pairs, and minifies all template-owned CSS and JS files - Add node_modules/ to .gitignore Generated .min files (all 6 manifest pairs): - css/template.min.css (17.8% saved) - css/editor.min.css (49.4% saved) - css/theme/light.standard.min.css (13.1% saved) - css/theme/dark.standard.min.css (14.4% saved) - js/template.min.js (58.2% saved) - js/gtm.min.js (62.3% saved) Rename: header-aside → brand-aside (position, CSS class, language keys) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * Add hero/banner-overlay CSS variables and wire template.css - Add HERO / BANNER OVERLAY section to light.standard.css and dark.standard.css: --hero-height, --hero-color, --hero-bg-repeat, --hero-bg-attachment, --hero-bg-position, --hero-bg-size, --hero-border-bottom, --hero-overlay-bg (light: 0.1 alpha / dark: 0.3 alpha), --hero-overlay-padding, --hero-overlay-text-align, --hero-overlay-text-color - Replace all hardcoded values in .container-banner .banner-overlay and .overlay with var() references (with fallbacks) - Fix background-position: comma syntax → correct space-separated single-bg value - Add css_vars_hero note field to CSS Variables tab in templateDetails.xml - Add TPL_MOKOCASSIOPEIA_CSS_VARS_HERO_LABEL/DESC to en-US and en-GB - Regenerate .min files Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * Add smooth theme-switch transitions and restore hero .overlay wrapper - Add prefers-reduced-motion-scoped CSS transitions (bg, color, border) on :root, body, and key layout containers so light/dark theme switches animate smoothly instead of snapping - Restore <div class="overlay"> child in hero.php; slim .custom-hero rule to a customisation hook only — visual overlay styles are handled by .overlay child - Regenerate template.min.css Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * Update template.css * Merge duplicate prefers-reduced-motion media queries Consolidate the two @media (prefers-reduced-motion: no-preference) blocks into one — scroll-behavior and theme-switch colour transitions share the same query and are cleaner in a single block. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * Promote offcanvas variables to :root theme files and document in CSS Variables tab - Move --offcanvas-* definitions from component-scoped .offcanvas selector in template.css into :root[data-bs-theme] blocks in light.standard.css and dark.standard.css so they are overridable via user.css at root level - Fix two bugs in the old definitions: --offcanvas-bg was incorrectly set to var(--body-color) (text colour); corrected to var(--body-bg); and --offcanvas-color had a spurious 'color:' prefix - Dark theme uses a heavier box-shadow (0.3 alpha) for better depth perception - Add css_vars_offcanvas field to templateDetails.xml CSS Variables tab - Add en-US and en-GB language strings for the new Offcanvas Panel section - Rebuild all .min CSS files Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * Promote Bootstrap component variables from template.css to :root theme files Move 16 component variable groups from component-scoped selectors in template.css into :root[data-bs-theme] blocks in light.standard.css and dark.standard.css: accordion, breadcrumb, pagination, badge, alert, progress, list-group, dropdown, toast, modal, tooltip, popover, spinner, nav, nav-tabs, nav-pills Dark theme values adapted for dark surfaces: semantic var() references, lighter SVG icon fill colours, heavier shadows, secondary-bg backgrounds. Component selectors in template.css retain only non-variable rules. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * Promote table and backdrop variables to :root theme files Move --table-* and --backdrop-* base definitions from component selectors in template.css into :root[data-bs-theme] blocks in light/dark theme files. Dark table uses white-rgb-based striped/active overlays for proper contrast on dark surfaces. Deduplicate the double --table-active-* declarations that existed in template.css. Backdrop values are identical in both themes. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * Add CSS Variables tab documentation for all promoted Bootstrap components Add LABEL/DESC language strings (en-US + en-GB) for all 17 Bootstrap component variable groups now living in the :root theme files: accordion, alert, badge, backdrop, breadcrumb, dropdown, list-group, modal, nav-tabs, nav-pills, pagination, popover, progress, spinner, table, toast, tooltip Each section documents variables with HTML subheadings (Dimensions, Colours, Typography, Stacking, Animation) and <code> tags for every variable name. British English spellings used throughout en-GB. Adds 34 new lines per language file (17 LABEL + 17 DESC pairs, 80 CSS_VARS_* keys total). XML fields were already present from the prior migration commit. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> --------- 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