MokoConsulting/MokoCassiopeia
1
1
Fork 0
Code Issues 2 Pull Requests Actions Packages Releases 1 Activity

v02.01.05-dev

Browse Source 
Prepped Version Numbers
This commit is contained in:
Jonathan Miller
2025-08-30 21:14:37 -05:00
parent 4569a2ccd2
commit 6d2d855ddb
37 changed files with 157 additions and 321 deletions
Download Patch File Download Diff File Expand all files Collapse all files

375
README.md
View File

@@ -1,304 +1,169 @@
<!--
=========================================================================
Copyright (C) 2025 Moko Consulting <hello@mokoconsulting.tech>
========================================================================
Copyright (C) 2025 Moko Consulting <hello@mokoconsulting.tech>
This file is part of a Moko Consulting project.
This file is part of a Moko Consulting project.
SPDX-License-Identifier: GPL-3.0-or-later
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 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.
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
INGROUP: Moko-Cassiopeia
PATH: README.md
VERSION: 02.00
BRIEF: Project readme for Moko-Cassiopeia, including features, setup, and usage
=========================================================================
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
INGROUP: Template
FILE: README.md
VERSION: 02.01.05-dev (In Development)
BRIEF: Documentation for Moko-Cassiopeia template (in-development 2.1.5)
PATH: /templates/moko-cassiopeia/
NOTE: Includes Dark Mode and Soft Offline Mode
VARIABLES: None
-->
# Moko-Cassiopeia
# Moko-Cassiopeia v02.00 — README
A modern, lightweight enhancement layer for Joomla's Cassiopeia
template.
Moko-Cassiopeia adds **Font Awesome 6**, **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.
> Joomla! site template by **Moko Consulting**
> License: **GPL-3.0-or-later**
> Compatibility: **Joomla 4.4+ / 5.x** (PHP 8.1+)
------------------------------------------------------------------------
---
## Table of Contents
## Overview
- [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)\
- [Changelog](#changelog)\
- [Roadmap](#roadmap)
Moko-Cassiopeia is a streamlined, Bootstrap-friendly Joomla template with a tokenized color system, Google Tag Manager / Analytics hooks, and performance-minded assets.
* **v02.00 (2025-08-30)** introduces **Dark Mode** with OS auto-detection **and** an optional **Dark Mode Toggle** (ID **25**) so users can manually switch themes; their preference persists.
* **v01.00** was the initial public release (FA6, BS5, TOC, GTM/GA hooks).
Public roadmap: **[https://mokoconsulting.tech/support/joomla-cms/moko-cassiopeia-roadmap](https://mokoconsulting.tech/support/joomla-cms/moko-cassiopeia-roadmap)**
---
## What’s New in v02.00
* **Dark Mode** with `prefers-color-scheme` auto-detect.
* **Dark Mode Toggle** (Template param **ID 25**) with positions **Header / Navbar / Footer**.
* Persists choice to `localStorage` (key: `moko.theme`).
* Keyboard- and screen-reader-friendly; focus ring uses theme tokens.
* Admin option **“Show Theme Toggle”** (`On/Off`).
* CSS refactor to **variables**: light tokens in `:root`, dark overrides in `[data-theme="dark"]`.
* Lowered CSS specificity, `rem` units for scalable typography/spacing.
* Stabilized WebAsset registrations (LTR/RTL presets).
---
------------------------------------------------------------------------
## Features
* **Dark Mode + Toggle**
Auto-detect plus manual switch; persistent per user.
### Core Enhancements
* **Bootstrap-friendly CSS**
Low specificity, variable-driven utilities for buttons, alerts, typography, spacing.
- 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`).
* **GTM / GA Hooks**
Clean injection points for Google Tag Manager and optional direct GA4 tag.
### Added in 2.0
* **LTR / RTL Presets**
Stable asset registration pattern for palette and template styles.
- **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.
* **A11y & Performance**
Clear focus styling and balanced contrast; minified bundles in production.
### 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+** / **5.x**
* PHP **8.1+**
* Modern evergreen browsers (graceful fallback if `prefers-color-scheme` isn’t available)
- 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
1. **Install** via *Extensions → Manage → Install* (upload the template `.zip`).
2. **Set as default** in *System → Templates → Site Templates*.
3. **Clear caches**: *System → Clear Cache* and hard-reload your browser.
Upload and install through Joomla's extension manager.\
If upgrading from a prior version, Joomla will safely overwrite files
--- no manual uninstall required.
---
------------------------------------------------------------------------
## Template Options (high-level)
## Configuration
**Theme**
### Global Params
* **Force Theme**: `Auto` (default) | `Light` | `Dark`
* **Show Theme Toggle** (ID **25**): `On` | `Off`
* **Toggle Position**: `Header` | `Navbar` | `Footer`
* **Default Theme** (when not using Auto): `Light`
- **Logo**: Upload a custom site logo.\
- **Color Scheme**: Toggle light/dark defaults.\
- **Analytics/GTM**: Enable/disable optional expansions.
**GTM / Analytics**
### Font Awesome 6
* **GTM Container ID** (e.g., `GTM-XXXXXXX`)
* **Analytics Tag ID** (optional GA4 if not using GTM)
- Fully integrated into Joomla's asset manager.\
- No extra scripts required.
**Performance**
### Bootstrap 5 Helpers
* **Development Mode**
- Adds extended utility classes and responsive tweaks.
* `Off` → `.min.css` / `.min.js` bundles
* `On` → unminified sources for debugging
### Table of Contents
---
- Select `toc-left` or `toc-right` in article **Options → Layout** to
insert TOC automatically.
## Dark Mode — Tokens & Toggle
### Dark Mode Toggle
**Color tokens**
- User-facing switch in the header.\
- Remembers preference via local storage.\
- Default behavior can be set in template settings.
```css
:root {
--color-bg: #ffffff;
--color-surface: #f8f9fa;
--color-text: #1d2125;
--color-text-muted: #6c757d;
--color-border: #dee2e6;
### Soft Offline Mode
--color-primary: #0d6efd;
--color-primary-contrast: #ffffff;
- Introduced in **2.1.5**.\
- Allows articles in selected categories to remain viewable during
offline/maintenance mode.\
- Useful for compliance, legal, or policy content.
--color-link: var(--color-primary);
--color-link-hover: #0b5ed7;
------------------------------------------------------------------------
--focus-ring: 0 0 0 .2rem rgba(13,110,253,.25);
}
## Changelog
[data-theme="dark"] {
--color-bg: #0e1116;
--color-surface: #151922;
--color-text: #e7eaf0;
--color-text-muted: #a4acb9;
--color-border: #2a3240;
See the [CHANGELOG.md](./CHANGELOG.md) for detailed version history.
--color-primary: #66b2ff;
--color-primary-contrast: #0d1117;
--color-link: var(--color-primary);
--color-link-hover: #99ccff;
--focus-ring: 0 0 0 .2rem rgba(102,178,255,.35);
}
```
**Programmatic switch (optional)**
```js
// Apply and persist a choice
document.documentElement.dataset.theme = 'dark'; // or 'light'
localStorage.setItem('moko.theme', 'dark'); // namespaced key
```
---
## CSS Architecture
* **`template.css`** = structure/layout and component scaffolding
* **No hard-coded hex** in core selectors; all colors reference tokens
* **Units**: `rem` (replacing `em`) for scalable typography/spacing
* **Low specificity** to play nicely with Bootstrap and content plugins
---
## GTM / Analytics Integration
* Enter **GTM Container ID** in Template Options to inject the GTM snippet.
* Optionally add a **GA4 Measurement ID** if not routing GA via GTM.
* Output uses Joomla rendering events to avoid duplication.
> Verify tags with DevTools / Tag Assistant.
---
## RTL / LTR Assets (WebAsset JSON)
Minimal pattern:
```json
{
"$schema": "https://developer.joomla.org/schemas/json/schema_web_assets.json",
"name": "template.moko-cassiopeia",
"assets": [
{ "name": "template.moko-cassiopeia.styles", "type": "style", "uri": "templates/moko-cassiopeia/css/template.min.css" },
{ "name": "template.moko-cassiopeia.palette", "type": "style", "uri": "templates/moko-cassiopeia/css/colors_standard.min.css" },
{ "name": "template.moko-cassiopeia", "type": "preset", "dependencies": ["template.moko-cassiopeia.styles","template.moko-cassiopeia.palette"] }
]
}
```
In `index.php`:
```php
/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = $this->getWebAssetManager();
$wa->usePreset('template.moko-cassiopeia');
```
---
## Upgrade Notes
**1.0 → 2.0**
* Clear Joomla + browser caches.
* Convert any hard-coded colors in overrides to **tokens** (e.g., `var(--color-text-muted)`).
* Review spacing/typography where `rem` replaces `em`.
* Verify asset names if you referenced WebAsset handles directly.
* If you previously added a custom dark-mode toggle, remove it and enable **Show Theme Toggle** (ID **25**).
---
## Accessibility
* Improved contrast targets across light/dark.
* Visible, consistent focus indicators.
* Toggle is keyboard-navigable and labeled for assistive tech.
---
## Troubleshooting
* **Toggle not visible** → Ensure “Show Theme Toggle” is on and placed in a visible position.
* **Preference not persisting** → Check `localStorage` availability and console for JS errors.
* **Asset dependency warnings** → Confirm preset/asset names match your `joomla.asset.json`.
---
## Feature Rundown & Comparison
### Moko-Cassiopeia v01.00 — Initial public release
* **Font Awesome 6** integrated; **Bootstrap 5** helpers.
* **TOC utility** hooks for article table of contents.
* **GTM/GA hooks** with safe injection points.
* Minimal, upgrade-friendly overrides; variable-ready CSS.
### Moko-Cassiopeia v02.00 — Dark Mode + Toggle (ID 25)
* **Dark Mode** with OS auto-detect.
* **Optional Dark Mode Toggle** (ID 25) in Header / Navbar / Footer; persisted per user.
* **Tokenized palette** (`:root` + `[data-theme="dark"]`).
* **CSS refactor**: low specificity; `rem` units; Bootstrap-friendly utilities.
* Stabilized **Web Asset** registrations (LTR/RTL presets).
### Baseline: Cassiopeia (Joomla 4.4 / 5.x)
* Responsive, accessible core site template with Bootstrap-friendly markup.
* Template options for color preset, layout width, sticky header, and module menu layouts.
* Web Asset Manager integration (`joomla.asset.json`, `$this->getWebAssetManager()`).
---
------------------------------------------------------------------------
## Roadmap
Public roadmap: **[https://mokoconsulting.tech/support/joomla-cms/moko-cassiopeia-roadmap](https://mokoconsulting.tech/support/joomla-cms/moko-cassiopeia-roadmap)**
---
## Changelog (1.0 → 2.0)
### 02.00 — 2025-08-30 — “Dark Mode”
**Added**
* Dark Mode with OS auto-detection (`prefers-color-scheme`).
* **Dark Mode Toggle** (param **ID 25**) with positions Header / Navbar / Footer; persists choice via `localStorage` (`moko.theme`); accessible markup and focus styling.
* Tokenized CSS palette with `[data-theme="dark"]` overrides.
* Admin override to force Light/Dark/Auto.
* Bootstrap-friendly utility hooks mapped to tokens.
**Changed**
* `template.css` now structure/layout only; colors via tokens.
* `em` → `rem`; reduced specificity; standardized focus indicators.
**Fixed**
* WebAsset registrations (LTR/RTL/preset deps) and dark-theme link/muted contrast.
**Removed / Deprecated**
* Hard-coded color declarations and legacy hex-based helper classes.
---
### 01.00 — Initial public release
* **FA6**, **BS5**, **TOC**, **GTM/GA** hooks.
- **2.2 (Planned)**
- Lazy load media for performance.\
- Expanded template overrides for more layout control.
- **Future Considerations**
- Multi-tenancy support.\
- Visual layout builder for drag-and-drop template positions.