v1.13
- Fixed CSS - Cleaned up Table of Contents - Deleted conflicting default.php in com_content
This commit is contained in:
253
readme.md
Normal file
253
readme.md
Normal file
@@ -0,0 +1,253 @@
|
||||
# Moko-Cassiopeia
|
||||
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
## 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)
|
||||
- [TOC Function](#toc-function)
|
||||
- [Moko Expansions](#moko-expansions)
|
||||
- [Google Tag Manager](#google-tag-manager)
|
||||
- [Google Analytics (GA4)](#google-analytics-ga4)
|
||||
- [CSS Variables](#css-variables)
|
||||
- [Usage Examples](#usage-examples)
|
||||
- [Best Practices](#best-practices)
|
||||
- [Development](#development)
|
||||
- [Changelog](#changelog)
|
||||
- [License](#license)
|
||||
|
||||
---
|
||||
|
||||
## Features
|
||||
|
||||
- **Font Awesome 6**: Solid, Regular, Brands (locally enqueued or CDN with Subresource Integrity).
|
||||
- **Bootstrap 5**: Utility classes, grid, and components available to your layouts and modules.
|
||||
- **Auto TOC**: Generate an in‑page Table of Contents from headings with a single data attribute.
|
||||
- **Moko Expansions**:
|
||||
- **GTM**: Drop‑in dataLayer and container injection with a template param.
|
||||
- **GA4**: Native GA4 Measurement ID support (with or without GTM).
|
||||
- **Production‑safe**: Assets loaded conditionally; no duplicate library loads if another extension already enqueues them.
|
||||
- **Accessible by default**: TOC anchors and focus styles follow a11y guidelines.
|
||||
|
||||
## Requirements
|
||||
|
||||
- Joomla 4.4+ or Joomla 5+
|
||||
- PHP 8.1+
|
||||
- Cassiopeia as the active base template (Moko-Cassiopeia may be installed as a child/override set)
|
||||
|
||||
## Quick Start
|
||||
|
||||
1. Install the template package via Joomla Extension Manager.
|
||||
2. In the Template Style settings, enable the features you want (FA6, BS5, TOC, GTM/GA).
|
||||
3. (Optional) Add a TOC container to any article or module using the data attribute shown below.
|
||||
|
||||
## Installation
|
||||
|
||||
1. Go to 'System' → 'Install' → 'Extensions'.
|
||||
2. Upload 'Moko-Cassiopeia.zip'.
|
||||
3. After installation, go to 'System' → 'Site Templates' → 'Styles' and open 'Moko-Cassiopeia'.
|
||||
4. Choose 'Default' to make it your active style (or assign per menu item).
|
||||
|
||||
## Configuration
|
||||
|
||||
Configuration lives in the Template Style parameters. Common params are listed below. Names may vary slightly depending on release.
|
||||
|
||||
### Global Params
|
||||
|
||||
- 'load\_bootstrap5' (bool): Enqueue Bootstrap 5 core CSS/JS if not provided by Joomla context.
|
||||
- 'load\_fontawesome6' (bool): Enqueue Font Awesome 6 (solid, regular, brands).
|
||||
- 'use\_cdn' (bool): Use CDN with SRI instead of local assets.
|
||||
- 'minified' (bool): Prefer '.min' assets.
|
||||
- 'defer\_js' (bool): Add 'defer' to template‑injected scripts where safe.
|
||||
|
||||
### Font Awesome 6
|
||||
|
||||
When enabled, the template registers FA6 and exposes the standard icon syntax:
|
||||
|
||||
```html
|
||||
<i class='fa-solid fa-circle-check' aria-hidden='true'></i>
|
||||
<span class='visually-hidden'>Success</span>
|
||||
```
|
||||
|
||||
**Notes**
|
||||
|
||||
- Icons are decorative unless paired with text or 'aria-label'.
|
||||
- Prefer the 'fa-solid', 'fa-regular', or 'fa-brands' families explicitly.
|
||||
|
||||
### Bootstrap 5 Helpers
|
||||
|
||||
If 'load\_bootstrap5' is enabled, grid and utilities are available:
|
||||
|
||||
```html
|
||||
<div class='container'>
|
||||
<div class='row g-3'>
|
||||
<div class='col-12 col-md-6'>Left</div>
|
||||
<div class='col-12 col-md-6'>Right</div>
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
You can also use helpers like 'ratio', 'visually-hidden', 'd-flex', and spacing utilities (e.g., 'mt-3', 'px-4').
|
||||
|
||||
### TOC Function
|
||||
|
||||
Moko-Cassiopeia ships a tiny script that scans within a container for headings (h2–h6) and builds a nested TOC with anchor links.
|
||||
|
||||
**Enable**: Turn on 'auto\_toc' in Template Style.
|
||||
|
||||
**Place a TOC container**:
|
||||
|
||||
```html
|
||||
<nav class='toc' data-moko-toc='true' data-moko-toc-target='#article-body' aria-label='Table of contents'></nav>
|
||||
```
|
||||
|
||||
**Mark your content region**:
|
||||
|
||||
```html
|
||||
<article id='article-body'>
|
||||
<h2>Section A</h2>
|
||||
<p>...</p>
|
||||
<h3>Subsection A.1</h3>
|
||||
<p>...</p>
|
||||
</article>
|
||||
```
|
||||
|
||||
**Options via data attributes**
|
||||
|
||||
- 'data-moko-toc-target': CSS selector for the content area (default: 'main').
|
||||
- 'data-moko-toc-levels': CSV or range string like '2-4' (default: '2-4').
|
||||
- 'data-moko-toc-collapsible': 'true'|'false' to make nested lists collapsible.
|
||||
|
||||
**Styling**
|
||||
|
||||
A minimal stylesheet is included. Customize using the CSS variables below or add your own overrides.
|
||||
|
||||
### Moko Expansions
|
||||
|
||||
#### Google Tag Manager
|
||||
|
||||
Enable GTM by entering your container ID (e.g., 'GTM-XXXXXXX') in Template Style under 'Moko Expansions'. The template will inject the standard script and 'noscript' iframe per Google guidance.
|
||||
|
||||
**Data Layer**
|
||||
|
||||
You can push events from modules or overrides like so:
|
||||
|
||||
```html
|
||||
<script>
|
||||
window.dataLayer = window.dataLayer || [];
|
||||
window.dataLayer.push({
|
||||
'event': 'moko_event',
|
||||
'moko_category': 'ui',
|
||||
'moko_action': 'toc_opened',
|
||||
'moko_label': 'sidebar'
|
||||
});
|
||||
</script>
|
||||
```
|
||||
|
||||
#### Google Analytics (GA4)
|
||||
|
||||
Two options:
|
||||
|
||||
1. **Direct GA4**: Provide 'G-' Measurement ID (e.g., 'G-ABC123XYZ'). The template injects the GA4 base script.
|
||||
|
||||
2. **Via GTM**: Leave GA4 field empty and configure GA4 inside your GTM container.
|
||||
|
||||
```html
|
||||
<script>
|
||||
window.dataLayer = window.dataLayer || [];
|
||||
window.dataLayer.push({ 'event': 'page_view' });
|
||||
</script>
|
||||
```
|
||||
|
||||
> Tip: When both GTM and direct GA4 are set, the template prefers GTM to avoid duplicate pageviews.
|
||||
|
||||
## CSS Variables
|
||||
|
||||
Moko-Cassiopeia exposes custom properties for theme tuning. Example set:
|
||||
|
||||
```css
|
||||
:root {
|
||||
--moko-cassiopeia-color-primary: #0b4008;
|
||||
--moko-cassiopeia-color-link: #0b4008;
|
||||
--moko-cassiopeia-color-hover: #000000;
|
||||
|
||||
--moko-cassiopeia-header-background-image: linear-gradient(30deg, #fefcf9, var(--accent-color-primary));
|
||||
--moko-cassiopeia-header-background-position: auto;
|
||||
--moko-cassiopeia-header-background-attachment: fixed;
|
||||
--moko-cassiopeia-header-background-repeat: repeat;
|
||||
--moko-cassiopeia-header-background-size: auto;
|
||||
}
|
||||
```
|
||||
|
||||
> Apply these in a custom stylesheet or template options if provided. Use semantic variables where possible to maintain consistency.
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### 1) FA6 Icon Buttons
|
||||
|
||||
```html
|
||||
<a class='btn btn-primary d-inline-flex align-items-center' href='#'>
|
||||
<i class='fa-solid fa-bolt me-2' aria-hidden='true'></i>
|
||||
<span>Action</span>
|
||||
</a>
|
||||
```
|
||||
|
||||
### 2) Sticky Sidebar TOC
|
||||
|
||||
```html
|
||||
<aside class='position-sticky top-0 pt-3'>
|
||||
<nav class='toc' data-moko-toc='true' data-moko-toc-target='#content'></nav>
|
||||
</aside>
|
||||
```
|
||||
|
||||
### 3) Module‑driven GA Event
|
||||
|
||||
```php
|
||||
<?php
|
||||
// In a custom module layout
|
||||
$label = 'cta_hero';
|
||||
?>
|
||||
<button class='btn btn-outline-primary' onclick='window.dataLayer && window.dataLayer.push({"event": "cta_click", "label": "<?php echo $label; ?>"})'>
|
||||
Click me
|
||||
</button>
|
||||
```
|
||||
|
||||
> Note: We use single quotes in HTML where possible to keep consistency with PHP string style preferences.
|
||||
|
||||
## Best Practices
|
||||
|
||||
- **One source of truth** for analytics injection (prefer GTM, or direct GA4—not both).
|
||||
- **Defer non‑critical JS** using the 'defer\_js' param when feasible.
|
||||
- **Avoid duplicate libraries** if another extension already loads FA6/BS5.
|
||||
- **Respect a11y**: Provide visible focus, 'visually-hidden' labels, and heading order for the TOC.
|
||||
- **Cache smartly**: After enabling new features, clear Joomla cache and any CDN cache to propagate assets.
|
||||
|
||||
## Development
|
||||
|
||||
- Source structure follows Joomla template conventions:
|
||||
- '/css', '/js', '/images', '/html' (overrides), 'templateDetails.xml'
|
||||
- Scripts are enqueued via the template's 'index.php' with conditional params.
|
||||
- Build/compile steps (if using bundlers) are noted in 'package.json' (when applicable).
|
||||
|
||||
**Local overrides**
|
||||
|
||||
- Place site‑specific CSS in '/css/custom.css'.
|
||||
- Use '/html' for component/module layout overrides as needed.
|
||||
|
||||
## Changelog
|
||||
|
||||
- 1.0.0: Initial public release with FA6, BS5, TOC, GTM/GA hooks.
|
||||
|
||||
## License
|
||||
|
||||
Distributed under the GNU General Public License v3. See 'LICENSE' for details.
|
||||
|
||||
Reference in New Issue
Block a user