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

Simplify component.php to minimal layout with conditional analytics #82

Merged
Copilot merged 78 commits from copilot/fix-breaking-overrides into main 2026-03-17 21:42:02 +00:00
Conversation 1 Commits 78 Files Changed 142 +354
1 changed files with 354 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Showing only changes of commit 30b488d6a7 - Show all commits

354
.github/copilot-instructions.md vendored Normal file
View File

@@ -0,0 +1,354 @@
# GitHub Copilot Instructions for MokoCassiopeia
## Repository Context
MokoCassiopeia is a modern, lightweight Joomla template that extends Cassiopeia (Joomla's default template). It follows a strict **non-replacement philosophy** for maximum upgrade compatibility.
**Key Characteristics:**
- Joomla 4.4.x and 5.x compatible
- PHP 8.0+ required
- Built on Cassiopeia template
- Minimal core template overrides
- Alternative layout naming convention (not default replacements)
- GPL-3.0-or-later license
## Project Structure
```
MokoCassiopeia/
├── .github/ # GitHub workflows and configuration
├── docs/ # Comprehensive documentation
├── scripts/ # Build and deployment scripts
├── src/ # Template source files (main working directory)
│ ├── index.php # Main template file
│ ├── templateDetails.xml # Joomla template manifest
│ ├── joomla.asset.json # Web Asset Manager configuration
│ ├── language/ # Frontend language files (en-GB, en-US)
│ ├── html/ # Alternative layout overrides
│ └── media/ # CSS, JS, images, fonts, vendors
├── templates/ # Custom color scheme templates
└── tests/ # Codeception tests
```
## Critical Conventions
### 1. Override Philosophy: Alternative Layouts Only
**NEVER replace default layouts.** All overrides must use alternative layout names.
✅ **Correct:**
- `mobile.php` (alternative layout)
- `mainmenu.php` (alternative layout for mod_menu)
- `toc-left.php`, `toc-right.php` (alternative layouts with TOC)
❌ **Incorrect:**
- `default.php` (replaces core layout - FORBIDDEN)
- Any file that replaces Cassiopeia's default behavior
**Rationale:** Ensures Joomla core updates don't break the template and gives users choice.
### 2. File Headers
All source files must include standardized copyright headers:
```php
<?php
/**
* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
*
* This file is part of a Moko Consulting project.
*
* SPDX-License-Identifier: GPL-3.0-or-later
*
* @defgroup Joomla.Template.Site
* @ingroup MokoCassiopeia.Template
* @brief [Brief description]
* @version [Version number]
*/
defined('_JEXEC') or die;
```
### 3. Language Files
**Key Rules:**
- Template metadata (name, description) goes in `.sys.ini` files ONLY
- Frontend runtime strings go in `.ini` files
- Language files location: `src/language/{locale}/`
- NO `folder` attribute in `<languages>` section of templateDetails.xml
- Paths must be relative from package root (e.g., `language/en-GB/tpl_mokocassiopeia.sys.ini`)
**Example templateDetails.xml:**
```xml
<languages folder="language">
<language tag="en-GB">en-GB/tpl_mokocassiopeia.ini</language>
<language tag="en-GB">en-GB/tpl_mokocassiopeia.sys.ini</language>
</languages>
```
### 4. Hardcoded XML Description
The template description in `templateDetails.xml` is **hardcoded using CDATA**, not a language constant:
```xml
<description><![CDATA[Modern, lightweight Joomla template...]]></description>
```
**Rationale:** Ensures immediate availability during installation without language file dependency.
### 5. Version Format
Follow semantic versioning: `XX.YY.ZZ`
- XX: Major version
- YY: Minor version
- ZZ: Patch version
**Examples:** `03.06.03`, `03.08.04`
## Coding Standards
### PHP
- **PSR-12 compliant** where not conflicting with Joomla standards
- **Joomla Coding Standards** for Joomla-specific code
- Use `defined('_JEXEC') or die;` at the top of every PHP file
- Type hints for PHP 8.0+ features
- Strict types declarations where appropriate
### JavaScript
- **ES6+** syntax
- Use `'use strict';`
- Prefer `const` and `let` over `var`
- Document functions with JSDoc comments
- Integrate with Joomla's Web Asset Manager
### CSS
- **CSS Variables** for theming (see `docs/CSS_VARIABLES.md`)
- Light/dark mode support via `data-bs-theme` attribute
- Bootstrap 5 utility classes
- Mobile-first responsive design
- Namespace custom classes to avoid conflicts
### Asset Management
All assets must be registered in `joomla.asset.json`:
```json
{
"name": "template.mokocassiopeia.custom",
"version": "1.0.0",
"description": "Custom asset",
"license": "GPL-3.0-or-later",
"dependencies": ["core"],
"js": ["js/custom.js"],
"css": ["css/custom.css"]
}
```
## Development Workflow
### Branching Strategy
- **Development:** Work on feature branches
- **Branch naming:** `feature/description`, `fix/issue-description`
- **Protected branches:** Cannot commit directly to `main` or version branches
- See `docs/WORKFLOW_GUIDE.md` for complete workflow
### Commit Messages
```
Brief summary (50 chars or less)
Detailed explanation if needed:
- What changed
- Why it changed
- Impact of the change
```
**Example:**
```
Fix language file installation paths in templateDetails.xml
- Remove folder attribute from <languages> section
- Update paths to be relative from package root
- Ensures proper installation to JOOMLA_ROOT/language/
```
### Quality Checks
Before committing:
1. **PHP CodeSniffer:** `phpcs --standard=Joomla src/`
2. **PHPStan:** Static analysis for PHP code
3. **Pre-commit hooks:** Automatically run validation
## Testing
### Manual Testing
- Test in Joomla 4.4.x and 5.x
- Test on PHP 8.0, 8.1, 8.2
- Test light/dark mode switching
- Test responsive layouts (mobile/tablet/desktop)
- Test alternative layouts activation
### Test Environment
- Use local Joomla installation
- See `docs/JOOMLA_DEVELOPMENT.md` for setup
## Documentation Standards
### Markdown Files
All documentation must include:
1. **Copyright header**
```markdown
<!--
Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
SPDX-License-Identifier: GPL-3.0-or-later
# FILE INFORMATION
DEFGROUP: [Group]
INGROUP: [Subgroup]
REPO: https://github.com/mokoconsulting-tech/MokoCassiopeia
FILE: [filename]
VERSION: [version]
BRIEF: [Brief description]
-->
```
2. **Metadata section** (at end)
3. **Revision history table** (at end)
### Code Comments
- Use DocBlocks for functions and classes
- Explain "why" not just "what"
- Keep comments up-to-date with code changes
## Common Patterns
### Theme System Integration
Use CSS variables for colors:
```css
:root[data-bs-theme="light"] {
--color-primary: #1e40af;
--body-bg: #ffffff;
}
:root[data-bs-theme="dark"] {
--color-primary: #60a5fa;
--body-bg: #1f2937;
}
```
### Alternative Layout Structure
```php
<?php
/**
* Alternative layout: mobile
* Activated via: Advanced → Alternative Layout → "mobile"
*/
defined('_JEXEC') or die;
use Joomla\CMS\Layout\LayoutHelper;
// Layout implementation
?>
```
### JavaScript Asset Loading
```javascript
// Register in joomla.asset.json, then use:
Joomla.getOptions('template.mokocassiopeia.options');
```
## Build and Release
### Local Build
```bash
cd scripts
./build-release.sh
```
### Automated Release
- Tags trigger GitHub Actions workflow
- Format: `XX.YY.ZZ`
- Generates ZIP packages with checksums
- Updates `updates.xml` automatically
## Important Don'ts
❌ **Never:**
- Replace default Joomla layouts (use alternative layouts)
- Commit without running code quality checks
- Add version numbers to revision history (use VERSION metadata)
- Hardcode absolute paths (use Joomla path constants)
- Remove copyright headers
- Modify `vendor/` directory contents
- Change language constants location (.sys.ini vs .ini)
- Add `folder` attribute to `<languages>` in templateDetails.xml
## Important Do's
✅ **Always:**
- Use alternative layout names (mobile.php, mainmenu.php, etc.)
- Include copyright headers in all files
- Test in both Joomla 4.x and 5.x
- Test light/dark mode themes
- Update documentation when changing functionality
- Follow semantic versioning
- Register assets in joomla.asset.json
- Use CSS variables for theming
- Keep minimal overrides philosophy
- Document activation steps for alternative layouts
## Key Documentation References
- **Quick Start:** `docs/QUICK_START.md` - First-time setup
- **Override Philosophy:** `docs/OVERRIDE_PHILOSOPHY.md` - Critical reading
- **Development Guide:** `docs/JOOMLA_DEVELOPMENT.md` - Complete dev workflow
- **CSS Variables:** `docs/CSS_VARIABLES.md` - Theming reference
- **Workflow Guide:** `docs/WORKFLOW_GUIDE.md` - Git workflow
## Security Considerations
- Follow `SECURITY.md` for security issues
- Never commit credentials or API keys
- Validate and sanitize all user inputs
- Use Joomla's security features (CSRF tokens, etc.)
- Keep dependencies updated
## Client Forks
For client-specific customizations:
- Use `CLIENT_FORK_README.md` template
- Follow fork workflow in `docs/CLIENT_FORK_WORKFLOW.md`
- Keep custom color files in `media/.../css/colors/` (gitignored)
- Document client-specific changes separately
## License Compliance
All code contributions must be:
- GPL-3.0-or-later compatible
- Properly attributed (third-party code)
- Include SPDX license identifiers
- Maintain existing copyright notices
## Contact and Support
- **Issues:** GitHub Issues
- **Discussions:** GitHub Discussions
- **Security:** Follow SECURITY.md procedures
- **Maintainer:** Moko Consulting Engineering
---
**Last Updated:** 2026-03-04
**Repository:** https://github.com/mokoconsulting-tech/MokoCassiopeia
**Version:** 03.08.04