213 lines
6.9 KiB
Markdown
213 lines
6.9 KiB
Markdown
<!-- Copyright (C) 2025 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: Moko-Cassiopeia.Documentation
|
|
REPO: https://github.com/mokoconsulting-tech/moko-cassiopeia
|
|
FILE: ./README.md
|
|
VERSION: 03.05.00
|
|
BRIEF: Documentation for Moko-Cassiopeia template
|
|
-->
|
|
|
|
# Moko-Cassiopeia (VERSION: 03.05.00)
|
|
|
|
A modern, lightweight enhancement layer for Joomla's Cassiopeia
|
|
template.
|
|
Moko-Cassiopeia adds **Font Awesome 7**, **Bootstrap 5** helpers, an
|
|
automatic **Table of Contents (TOC)** utility, and optional **Moko
|
|
Expansions** including **Google Tag Manager** and **Google Analytics
|
|
(GA4)** hooks---all while keeping core template overrides minimal and
|
|
upgrade-friendly.
|
|
|
|
## Table of Contents
|
|
|
|
- [Features](#features)
|
|
- [Requirements](#requirements)
|
|
- [Quick Start](#quick-start)
|
|
- [Installation](#installation)
|
|
- [Configuration](#configuration)
|
|
- [Global Params](#global-params)
|
|
- [Font Awesome 6](#font-awesome-6)
|
|
- [Bootstrap 5 Helpers](#bootstrap-5-helpers)
|
|
- [Table of Contents](#table-of-contents)
|
|
- [Dark Mode Toggle](#dark-mode-toggle)
|
|
- [Soft Offline Mode](#soft-offline-mode)
|
|
- [Development](#development)
|
|
- [Changelog](#changelog)
|
|
- [Roadmap](#roadmap)
|
|
|
|
## Features
|
|
|
|
### Core Enhancements
|
|
|
|
- Built on top of Joomla's default **Cassiopeia** template.
|
|
- **Font Awesome 6** integration.
|
|
- **Bootstrap 5** helpers (grid, utility classes).
|
|
- **Automatic TOC** insertion for articles (activated via layout
|
|
`toc-left` or `toc-right`).
|
|
|
|
### Added in 2.0
|
|
|
|
- **Dark Mode Toggle**
|
|
- User-facing switch in the header.
|
|
- Persists preference with local storage.
|
|
- Admins can override default mode in template settings.
|
|
- **Improved Template Params**
|
|
- Configure logo, GTM container ID, and dark mode defaults
|
|
directly from template settings.
|
|
|
|
### New in 2.1.5 (In Development)
|
|
|
|
- **Soft Offline Mode**
|
|
- Keeps articles in specific categories available when the site is
|
|
offline.
|
|
- Example: legal or policy documents remain publicly viewable even
|
|
during maintenance.
|
|
- Admin can configure which categories remain accessible.
|
|
|
|
## Requirements
|
|
|
|
- Joomla **4.4.x** or **5.x**
|
|
- PHP **8.0+**
|
|
- MySQL/MariaDB compatible database
|
|
|
|
## Quick Start
|
|
|
|
1. Install `moko-cassiopeia.zip` via Joomla's Template Installer.
|
|
2. Set **Moko-Cassiopeia** as your default template.
|
|
3. Configure template options under **System → Site Templates →
|
|
Moko-Cassiopeia**.
|
|
|
|
## Installation
|
|
|
|
Upload and install through Joomla's extension manager.
|
|
If upgrading from a prior version, Joomla will safely overwrite files
|
|
--- no manual uninstall required.
|
|
|
|
## Configuration
|
|
|
|
### Global Params
|
|
|
|
- **Logo**: Upload a custom site logo.
|
|
- **Color Scheme**: Toggle light/dark defaults.
|
|
- **Analytics/GTM**: Enable/disable optional expansions.
|
|
|
|
### Font Awesome 7
|
|
|
|
- Fully integrated into Joomla's asset manager.
|
|
- No extra scripts required.
|
|
|
|
### Bootstrap 5 Helpers
|
|
|
|
- Adds extended utility classes and responsive tweaks.
|
|
|
|
### Table of Contents
|
|
|
|
- Select `toc-left` or `toc-right` in article **Options → Layout** to
|
|
insert TOC automatically.
|
|
|
|
### Dark Mode Toggle
|
|
|
|
- User-facing switch in the header.
|
|
- Remembers preference via local storage.
|
|
- Default behavior can be set in template settings.
|
|
|
|
### Soft Offline Mode
|
|
|
|
- Introduced in **2.1.5**.
|
|
- Allows articles in selected categories to remain viewable during
|
|
offline/maintenance mode.
|
|
- Useful for compliance, legal, or policy content.
|
|
|
|
## Development
|
|
|
|
For developers and contributors working on the moko-cassiopeia template:
|
|
|
|
### Quick Start for Developers
|
|
|
|
Get started in minutes:
|
|
|
|
```bash
|
|
# Setup development environment
|
|
make dev-setup
|
|
|
|
# Validate code
|
|
make validate-required
|
|
|
|
# Check code quality
|
|
make quality
|
|
|
|
# Create distribution package
|
|
make package
|
|
|
|
# Install Git hooks (optional but recommended)
|
|
python3 ./scripts/git/install-hooks.py
|
|
```
|
|
|
|
**New to the project?** See [Quick Start Guide](./docs/QUICK_START.md) for a 5-minute walkthrough.
|
|
|
|
### Development Resources
|
|
|
|
- **[Quick Start Guide](./docs/QUICK_START.md)** - Get up and running in 5 minutes
|
|
- **[Workflow Guide](./docs/WORKFLOW_GUIDE.md)** - Complete workflow reference with examples
|
|
- **[Joomla Development Guide](./docs/JOOMLA_DEVELOPMENT.md)** - Testing, quality checks, and deployment
|
|
- **[Scripts Documentation](./scripts/README.md)** - Available automation scripts
|
|
- **[Contributing Guide](./CONTRIBUTING.md)** - How to contribute
|
|
|
|
### Available Tools
|
|
|
|
- **Makefile**: Run `make help` to see all available commands
|
|
- **Python Scripts**: All automation scripts are now Python-based for cross-platform compatibility
|
|
- **Pre-commit Hooks**: Automatic validation before commits
|
|
- **VS Code Tasks**: Pre-configured development tasks
|
|
- **GitHub Actions**: Automated CI/CD pipelines
|
|
|
|
### Cross-Platform Support
|
|
|
|
All scripts are now written in Python for maximum cross-platform compatibility:
|
|
- **Joomla Extension Support**: Full support for Joomla 4.x and 5.x templates, components, modules, and plugins
|
|
- **Dolibarr Module Support**: Automatic detection and packaging of Dolibarr modules
|
|
- **Platform Detection**: Scripts automatically detect whether you're working with Joomla or Dolibarr extensions
|
|
|
|
### Joomla Development Workflows
|
|
|
|
Comprehensive Joomla-aware development tools and workflows are available:
|
|
|
|
- **Extension Packaging** - Create distributable ZIP packages for Joomla or Dolibarr
|
|
- **PHP Quality Checks** - PHPStan and PHP_CodeSniffer with Joomla standards
|
|
- **Automated Testing** - Codeception framework with multiple Joomla versions
|
|
- **CI/CD Pipelines** - GitHub Actions with caching for faster builds
|
|
|
|
Run `make help` to see all available development commands.
|
|
|
|
## Changelog
|
|
|
|
See the [CHANGELOG.md](./CHANGELOG.md) for detailed version history.
|
|
|
|
---
|
|
|
|
## Metadata
|
|
|
|
* Maintainer: Moko Consulting Engineering
|
|
* Repository: [https://github.com/mokoconsulting-tech/moko-cassiopeia](https://github.com/mokoconsulting-tech/moko-cassiopeia)
|
|
* File: README.md
|
|
* Version: 3.0
|
|
* Classification: Public Open Source Standards
|
|
|
|
## Revision History
|
|
|
|
| Version | Date | Author | Description |
|
|
| ------- | ---------- | -----------------------------_-- | ------------------------------------- |
|
|
| 3.0 | 2025-12-09 | Jonathan Miller (@jmiller-moko) | Added Metadata and Revision History |
|