MokoOnyx v01.00.00 — initial release (successor to MokoCassiopeia)
Some checks failed
Standards Compliance / Secret Scanning (push) Successful in 3s
Standards Compliance / License Header Validation (push) Successful in 4s
Standards Compliance / Repository Structure Validation (push) Successful in 5s
Standards Compliance / Coding Standards Check (push) Failing after 3s
Standards Compliance / Version Consistency Check (push) Successful in 3s
Standards Compliance / Workflow Configuration Check (push) Failing after 2s
Standards Compliance / Documentation Quality Check (push) Successful in 3s
Standards Compliance / README Completeness Check (push) Successful in 3s
Standards Compliance / Git Repository Hygiene (push) Successful in 2s
Standards Compliance / Script Integrity Validation (push) Successful in 4s
Standards Compliance / Line Length Check (push) Failing after 4s
Standards Compliance / File Naming Standards (push) Successful in 2s
Standards Compliance / Insecure Code Pattern Detection (push) Successful in 3s
Standards Compliance / Code Complexity Analysis (push) Successful in 3s
Standards Compliance / Code Duplication Detection (push) Successful in 4s
Standards Compliance / Dead Code Detection (push) Successful in 3s
Standards Compliance / File Size Limits (push) Successful in 2s
CodeQL Security Scanning / Analyze (javascript) (push) Failing after 1m9s
Standards Compliance / Binary File Detection (push) Successful in 4s
CodeQL Security Scanning / Analyze (actions) (push) Failing after 1m11s
Standards Compliance / TODO/FIXME Tracking (push) Successful in 3s
Standards Compliance / Dependency Vulnerability Scanning (push) Successful in 5s
Standards Compliance / Broken Link Detection (push) Successful in 5s
Standards Compliance / Unused Dependencies Check (push) Successful in 7s
Standards Compliance / API Documentation Coverage (push) Successful in 3s
Standards Compliance / Accessibility Check (push) Successful in 3s
Standards Compliance / Performance Metrics (push) Successful in 3s
Standards Compliance / Enterprise Readiness Check (push) Successful in 3s
Standards Compliance / Repository Health Check (push) Successful in 4s
Standards Compliance / Terraform Configuration Validation (push) Successful in 6s
CodeQL Security Scanning / Security Scan Summary (push) Successful in 1s
Standards Compliance / Compliance Summary (push) Successful in 1s
Repo Health / Access control (push) Successful in 1s
Auto-Update SHA Hash / Update SHA-256 Hash in updates.xml (release) Successful in 4s
Repo Health / Release configuration (push) Failing after 3s
Repo Health / Scripts governance (push) Successful in 3s
Repo Health / Repository health (push) Failing after 3s
Some checks failed
Standards Compliance / Secret Scanning (push) Successful in 3s
Standards Compliance / License Header Validation (push) Successful in 4s
Standards Compliance / Repository Structure Validation (push) Successful in 5s
Standards Compliance / Coding Standards Check (push) Failing after 3s
Standards Compliance / Version Consistency Check (push) Successful in 3s
Standards Compliance / Workflow Configuration Check (push) Failing after 2s
Standards Compliance / Documentation Quality Check (push) Successful in 3s
Standards Compliance / README Completeness Check (push) Successful in 3s
Standards Compliance / Git Repository Hygiene (push) Successful in 2s
Standards Compliance / Script Integrity Validation (push) Successful in 4s
Standards Compliance / Line Length Check (push) Failing after 4s
Standards Compliance / File Naming Standards (push) Successful in 2s
Standards Compliance / Insecure Code Pattern Detection (push) Successful in 3s
Standards Compliance / Code Complexity Analysis (push) Successful in 3s
Standards Compliance / Code Duplication Detection (push) Successful in 4s
Standards Compliance / Dead Code Detection (push) Successful in 3s
Standards Compliance / File Size Limits (push) Successful in 2s
CodeQL Security Scanning / Analyze (javascript) (push) Failing after 1m9s
Standards Compliance / Binary File Detection (push) Successful in 4s
CodeQL Security Scanning / Analyze (actions) (push) Failing after 1m11s
Standards Compliance / TODO/FIXME Tracking (push) Successful in 3s
Standards Compliance / Dependency Vulnerability Scanning (push) Successful in 5s
Standards Compliance / Broken Link Detection (push) Successful in 5s
Standards Compliance / Unused Dependencies Check (push) Successful in 7s
Standards Compliance / API Documentation Coverage (push) Successful in 3s
Standards Compliance / Accessibility Check (push) Successful in 3s
Standards Compliance / Performance Metrics (push) Successful in 3s
Standards Compliance / Enterprise Readiness Check (push) Successful in 3s
Standards Compliance / Repository Health Check (push) Successful in 4s
Standards Compliance / Terraform Configuration Validation (push) Successful in 6s
CodeQL Security Scanning / Security Scan Summary (push) Successful in 1s
Standards Compliance / Compliance Summary (push) Successful in 1s
Repo Health / Access control (push) Successful in 1s
Auto-Update SHA Hash / Update SHA-256 Hash in updates.xml (release) Successful in 4s
Repo Health / Release configuration (push) Failing after 3s
Repo Health / Scripts governance (push) Successful in 3s
Repo Health / Repository health (push) Failing after 3s
All files renamed from mokocassiopeia to mokoonyx. Update server points to MokoOnyx repo. Bridge migration removed (clean standalone template). Version reset to 01.00.00. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Jonathan Miller
1460
docs/CSS_VARIABLES.md
Normal file
1460
docs/CSS_VARIABLES.md
Normal file
File diff suppressed because it is too large
Load Diff
376
docs/JOOMLA_DEVELOPMENT.md
Normal file
376
docs/JOOMLA_DEVELOPMENT.md
Normal file
@@ -0,0 +1,376 @@
|
||||
# Joomla Development Workflows and Scripts
|
||||
|
||||
This document describes the Joomla-aware development workflows and scripts available in this repository.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Overview](#overview)
|
||||
- [Requirements](#requirements)
|
||||
- [Scripts](#scripts)
|
||||
- [GitHub Actions Workflows](#github-actions-workflows)
|
||||
- [Testing](#testing)
|
||||
- [Code Quality](#code-quality)
|
||||
- [Deployment](#deployment)
|
||||
|
||||
## Overview
|
||||
|
||||
This repository includes comprehensive Joomla development workflows and scripts for:
|
||||
|
||||
1. **Extension Packaging** - Create distributable ZIP packages
|
||||
2. **Joomla Testing** - Automated testing with multiple Joomla versions
|
||||
3. **Code Quality** - PHPStan, PHP_CodeSniffer, and compatibility checks
|
||||
4. **Deployment** - Staging and production deployment workflows
|
||||
|
||||
## Requirements
|
||||
|
||||
### Local Development
|
||||
|
||||
- PHP 8.0 or higher
|
||||
- Composer (for PHPStan and PHP_CodeSniffer)
|
||||
- Node.js 18+ (for some workflows)
|
||||
- MySQL/MariaDB (for Joomla testing)
|
||||
|
||||
### CI/CD (GitHub Actions)
|
||||
|
||||
All requirements are automatically installed in CI/CD pipelines.
|
||||
|
||||
## Scripts
|
||||
|
||||
### Extension Packaging
|
||||
|
||||
Package the Joomla template as a distributable ZIP file:
|
||||
|
||||
```bash
|
||||
make package
|
||||
```
|
||||
|
||||
This creates a ZIP file in the `dist` directory with all necessary template files, excluding development files.
|
||||
|
||||
## GitHub Actions Workflows
|
||||
|
||||
### 1. PHP Code Quality (`php_quality.yml`)
|
||||
|
||||
Runs on every push and pull request to main branches.
|
||||
|
||||
**Jobs:**
|
||||
- **PHP_CodeSniffer** - Checks code style and standards
|
||||
- **PHPStan** - Static analysis at level 5
|
||||
- **PHP Compatibility** - Ensures PHP 8.0+ compatibility
|
||||
|
||||
**Matrix Testing:**
|
||||
- PHP versions: 8.0, 8.1, 8.2, 8.3
|
||||
|
||||
**Trigger:**
|
||||
```bash
|
||||
# Automatically runs on push/PR
|
||||
git push origin dev/3.5.0
|
||||
```
|
||||
|
||||
### 2. Joomla Testing (`joomla_testing.yml`)
|
||||
|
||||
Tests template with multiple Joomla and PHP versions.
|
||||
|
||||
**Jobs:**
|
||||
- **Joomla Setup** - Installs Joomla CMS
|
||||
- **Template Installation** - Installs template into Joomla
|
||||
- **Validation** - Validates template functionality
|
||||
- **Codeception** - Runs test framework
|
||||
|
||||
**Matrix Testing:**
|
||||
- PHP versions: 8.0, 8.1, 8.2, 8.3
|
||||
- Joomla versions: 4.4 (LTS), 5.0, 5.1
|
||||
- MySQL version: 8.0
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
# Automatically runs on push to main branches
|
||||
git push origin main
|
||||
```
|
||||
|
||||
### 3. Deploy to Staging (`deploy_staging.yml`)
|
||||
|
||||
Manual deployment to staging/development environments.
|
||||
|
||||
**Parameters:**
|
||||
- `environment`: Target environment (staging, development, preview)
|
||||
- `version`: Version to deploy (optional, defaults to latest)
|
||||
|
||||
**Usage:**
|
||||
1. Go to Actions → Deploy to Staging
|
||||
2. Click "Run workflow"
|
||||
3. Select environment and version
|
||||
4. Click "Run workflow"
|
||||
|
||||
**Required Secrets:**
|
||||
For staging deployment, configure these repository secrets:
|
||||
- `STAGING_HOST` - SFTP server hostname
|
||||
- `STAGING_USER` - SFTP username
|
||||
- `STAGING_KEY` - SSH private key (recommended) or use `STAGING_PASSWORD`
|
||||
- `STAGING_PATH` - Remote path for deployment
|
||||
- `STAGING_PORT` - SSH port (optional, default: 22)
|
||||
|
||||
## Testing
|
||||
|
||||
### Codeception Framework
|
||||
|
||||
The repository is configured with Codeception for acceptance and unit testing.
|
||||
|
||||
#### Running Tests Locally
|
||||
|
||||
1. Install Codeception:
|
||||
```bash
|
||||
composer global require "codeception/codeception" --with-all-dependencies
|
||||
```
|
||||
|
||||
2. Run tests:
|
||||
```bash
|
||||
# Run all tests
|
||||
codecept run
|
||||
|
||||
# Run acceptance tests only
|
||||
codecept run acceptance
|
||||
|
||||
# Run unit tests only
|
||||
codecept run unit
|
||||
|
||||
# Run with verbose output
|
||||
codecept run --debug
|
||||
```
|
||||
|
||||
#### Test Structure
|
||||
|
||||
```
|
||||
tests/
|
||||
├── _data/ # Test data and fixtures
|
||||
├── _output/ # Test reports and screenshots
|
||||
├── _support/ # Helper classes
|
||||
├── acceptance/ # Acceptance tests
|
||||
│ └── TemplateInstallationCest.php
|
||||
├── unit/ # Unit tests
|
||||
│ └── TemplateConfigurationTest.php
|
||||
├── acceptance.suite.yml
|
||||
└── unit.suite.yml
|
||||
```
|
||||
|
||||
#### Writing Tests
|
||||
|
||||
**Unit Test Example:**
|
||||
```php
|
||||
<?php
|
||||
namespace Tests\Unit;
|
||||
|
||||
use Codeception\Test\Unit;
|
||||
|
||||
class MyTemplateTest extends Unit
|
||||
{
|
||||
public function testSomething()
|
||||
{
|
||||
$this->assertTrue(true);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Acceptance Test Example:**
|
||||
```php
|
||||
<?php
|
||||
namespace Tests\Acceptance;
|
||||
|
||||
use Tests\Support\AcceptanceTester;
|
||||
|
||||
class MyAcceptanceCest
|
||||
{
|
||||
public function testPageLoad(AcceptanceTester $I)
|
||||
{
|
||||
$I->amOnPage('/');
|
||||
$I->see('Welcome');
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Code Quality
|
||||
|
||||
### PHPStan
|
||||
|
||||
Static analysis configuration in `phpstan.neon`:
|
||||
|
||||
```bash
|
||||
# Run PHPStan locally
|
||||
phpstan analyse --configuration=phpstan.neon
|
||||
```
|
||||
|
||||
**Configuration:**
|
||||
- Analysis level: 5
|
||||
- Target paths: `src/`
|
||||
- PHP version: 8.0+
|
||||
|
||||
### PHP_CodeSniffer
|
||||
|
||||
Coding standards configuration in `phpcs.xml`:
|
||||
|
||||
```bash
|
||||
# Check code style
|
||||
phpcs --standard=phpcs.xml
|
||||
|
||||
# Fix auto-fixable issues
|
||||
phpcbf --standard=phpcs.xml
|
||||
```
|
||||
|
||||
**Standards:**
|
||||
- PSR-12 as base
|
||||
- PHP 8.0+ compatibility checks
|
||||
- Joomla coding conventions (when available)
|
||||
|
||||
### Running Quality Checks Locally
|
||||
|
||||
1. Install tools:
|
||||
```bash
|
||||
composer global require "squizlabs/php_codesniffer:^3.0" --with-all-dependencies
|
||||
composer global require "phpstan/phpstan:^1.0" --with-all-dependencies
|
||||
composer global require "phpcompatibility/php-compatibility:^9.0" --with-all-dependencies
|
||||
```
|
||||
|
||||
2. Configure PHPCompatibility:
|
||||
```bash
|
||||
phpcs --config-set installed_paths ~/.composer/vendor/phpcompatibility/php-compatibility
|
||||
```
|
||||
|
||||
3. Run checks:
|
||||
```bash
|
||||
# PHP syntax check
|
||||
make validate-required
|
||||
|
||||
# CodeSniffer
|
||||
phpcs --standard=phpcs.xml src/
|
||||
|
||||
# PHPStan
|
||||
phpstan analyse --configuration=phpstan.neon
|
||||
|
||||
# PHP Compatibility
|
||||
phpcs --standard=PHPCompatibility --runtime-set testVersion 8.0- src/
|
||||
```
|
||||
|
||||
## Deployment
|
||||
|
||||
### Manual Deployment
|
||||
|
||||
Use the package script to create a distribution:
|
||||
|
||||
```bash
|
||||
# Create package
|
||||
make package
|
||||
|
||||
# Upload to server
|
||||
scp dist/moko-cassiopeia-3.5.0-template.zip user@server:/path/to/joomla/
|
||||
```
|
||||
|
||||
### Automated Deployment
|
||||
|
||||
Use the GitHub Actions workflow:
|
||||
|
||||
1. **Staging Deployment:**
|
||||
- Go to Actions → Deploy to Staging
|
||||
- Select "staging" environment
|
||||
- Click "Run workflow"
|
||||
|
||||
2. **Development Testing:**
|
||||
- Select "development" environment
|
||||
- Useful for quick testing without affecting staging
|
||||
|
||||
3. **Preview Deployment:**
|
||||
- Select "preview" environment
|
||||
- For showcasing features before staging
|
||||
|
||||
### Post-Deployment Steps
|
||||
|
||||
After deployment to Joomla:
|
||||
|
||||
1. Log in to Joomla administrator
|
||||
2. Go to System → Extensions → Discover
|
||||
3. Click "Discover" to find the template
|
||||
4. Click "Install" to complete installation
|
||||
5. Go to System → Site Templates
|
||||
6. Configure template settings
|
||||
7. Set as default template if desired
|
||||
|
||||
## CI/CD Pipeline Details
|
||||
|
||||
### Build Process
|
||||
|
||||
1. **Validation** - All scripts validate before packaging
|
||||
2. **Packaging** - Create ZIP with proper structure
|
||||
3. **Testing** - Run on multiple PHP/Joomla versions
|
||||
4. **Quality** - PHPStan and PHPCS analysis
|
||||
5. **Deployment** - SFTP upload to target environment
|
||||
|
||||
### Matrix Testing Strategy
|
||||
|
||||
- **PHP Versions:** 8.0, 8.1, 8.2, 8.3
|
||||
- **Joomla Versions:** 4.4 LTS, 5.0, 5.1
|
||||
- **Exclusions:** PHP 8.3 not tested with Joomla 4.4 (incompatible)
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**Issue: PHP_CodeSniffer not found**
|
||||
```bash
|
||||
composer global require "squizlabs/php_codesniffer:^3.0"
|
||||
export PATH="$PATH:$HOME/.composer/vendor/bin"
|
||||
```
|
||||
|
||||
**Issue: PHPStan errors**
|
||||
```bash
|
||||
# Increase analysis memory
|
||||
php -d memory_limit=1G $(which phpstan) analyse
|
||||
```
|
||||
|
||||
**Issue: Joomla installation fails in CI**
|
||||
- Check MySQL service is running
|
||||
- Verify database credentials
|
||||
- Ensure PHP extensions are installed
|
||||
|
||||
**Issue: SFTP deployment fails**
|
||||
- Verify SSH key is correctly formatted
|
||||
- Check firewall allows port 22
|
||||
- Ensure STAGING_PATH exists on server
|
||||
|
||||
## Contributing
|
||||
|
||||
When adding new workflows or scripts:
|
||||
|
||||
1. Follow existing script structure
|
||||
2. Add proper error handling
|
||||
3. Include usage documentation
|
||||
4. Test with multiple PHP versions
|
||||
5. Update this documentation
|
||||
|
||||
## Support
|
||||
|
||||
For issues or questions:
|
||||
- Open an issue on GitHub
|
||||
- Check existing workflow runs for examples
|
||||
- Review test output in Actions tab
|
||||
|
||||
## License
|
||||
|
||||
All scripts and workflows are licensed under GPL-3.0-or-later, same as the main project.
|
||||
|
||||
---
|
||||
|
||||
## Metadata
|
||||
|
||||
* Document: docs/JOOMLA_DEVELOPMENT.md
|
||||
* Repository: [https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx](https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx)
|
||||
* Path: /docs/JOOMLA_DEVELOPMENT.md
|
||||
* Owner: Moko Consulting
|
||||
* Version: 03.06.03
|
||||
* Status: Active
|
||||
* Effective Date: 2026-01-30
|
||||
* Classification: Public Open Source Documentation
|
||||
|
||||
## Revision History
|
||||
|
||||
| Date | Change Summary | Author |
|
||||
| ---------- | ----------------------------------------------------- | --------------- |
|
||||
| 2026-01-30 | Updated metadata to MokoStandards format | GitHub Copilot |
|
||||
| 2025-01-04 | Initial Joomla development guide created | GitHub Copilot |
|
||||
310
docs/MANUAL_DEPLOYMENT.md
Normal file
310
docs/MANUAL_DEPLOYMENT.md
Normal file
@@ -0,0 +1,310 @@
|
||||
# Manual Deployment Guide - MokoOnyx
|
||||
|
||||
This guide explains how to manually deploy the MokoOnyx template from the `src` directory to a Joomla installation without using the build/packaging process.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Overview](#overview)
|
||||
- [Understanding the Structure](#understanding-the-structure)
|
||||
- [Manual Deployment Methods](#manual-deployment-methods)
|
||||
- [Troubleshooting](#troubleshooting)
|
||||
- [When to Use Manual Deployment](#when-to-use-manual-deployment)
|
||||
|
||||
## Overview
|
||||
|
||||
**Important**: The `src` directory in this repository is the development source, not a ready-to-install package. For production use, we recommend using the packaged ZIP file from [Releases](https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx/releases).
|
||||
|
||||
However, for development or testing purposes, you can manually deploy files from the `src` directory to your Joomla installation.
|
||||
|
||||
## Understanding the Structure
|
||||
|
||||
### Repository Structure
|
||||
|
||||
The `src/` directory contains:
|
||||
|
||||
```
|
||||
src/
|
||||
├── component.php # Template file
|
||||
├── error.php # Template file
|
||||
├── index.php # Main template file
|
||||
├── offline.php # Template file
|
||||
├── templateDetails.xml # Template manifest
|
||||
├── joomla.asset.json # Asset registration
|
||||
├── html/ # Module & component overrides
|
||||
├── language/ # Frontend language files
|
||||
├── administrator/ # Backend language files
|
||||
│ └── language/
|
||||
└── media/ # Assets (CSS, JS, images, fonts)
|
||||
├── css/
|
||||
├── js/
|
||||
├── images/
|
||||
└── fonts/
|
||||
```
|
||||
|
||||
### Joomla Installation Structure
|
||||
|
||||
Joomla expects template files in these locations:
|
||||
|
||||
```
|
||||
YOUR_JOOMLA_ROOT/
|
||||
├── templates/
|
||||
│ └── mokoonyx/ # Template files go here
|
||||
│ ├── component.php
|
||||
│ ├── error.php
|
||||
│ ├── index.php
|
||||
│ ├── offline.php
|
||||
│ ├── templateDetails.xml
|
||||
│ ├── joomla.asset.json
|
||||
│ ├── html/
|
||||
│ ├── language/
|
||||
│ └── administrator/
|
||||
└── media/
|
||||
└── templates/
|
||||
└── site/
|
||||
└── mokoonyx/ # Media files go here
|
||||
├── css/
|
||||
├── js/
|
||||
├── images/
|
||||
└── fonts/
|
||||
```
|
||||
|
||||
**Key Point**: Template files and media files go to **different locations** in Joomla!
|
||||
|
||||
## Manual Deployment Methods
|
||||
|
||||
### Method 1: Recommended - Upload as ZIP (Still Manual)
|
||||
|
||||
This method mimics what Joomla's installer does automatically.
|
||||
|
||||
1. **Prepare the template directory**:
|
||||
```bash
|
||||
# From the repository root
|
||||
cd src
|
||||
|
||||
# Copy all files EXCEPT media to a temp directory
|
||||
mkdir -p /tmp/mokoonyx
|
||||
cp component.php /tmp/mokoonyx/
|
||||
cp error.php /tmp/mokoonyx/
|
||||
cp index.php /tmp/mokoonyx/
|
||||
cp offline.php /tmp/mokoonyx/
|
||||
cp templateDetails.xml /tmp/mokoonyx/
|
||||
cp joomla.asset.json /tmp/mokoonyx/
|
||||
cp -r html /tmp/mokoonyx/
|
||||
cp -r language /tmp/mokoonyx/
|
||||
cp -r administrator /tmp/mokoonyx/
|
||||
|
||||
# Copy media to a separate temp directory
|
||||
mkdir -p /tmp/mokoonyx_media
|
||||
cp -r media/* /tmp/mokoonyx_media/
|
||||
```
|
||||
|
||||
2. **Upload to Joomla via FTP/SFTP**:
|
||||
```bash
|
||||
# Upload template files
|
||||
# Replace with your actual Joomla path
|
||||
scp -r /tmp/mokoonyx/* user@yourserver:/path/to/joomla/templates/mokoonyx/
|
||||
|
||||
# Upload media files
|
||||
scp -r /tmp/mokoonyx_media/* user@yourserver:/path/to/joomla/media/templates/site/mokoonyx/
|
||||
```
|
||||
|
||||
3. **Set proper permissions**:
|
||||
```bash
|
||||
# On your server
|
||||
cd /path/to/joomla
|
||||
chmod 755 templates/mokoonyx
|
||||
chmod 644 templates/mokoonyx/*
|
||||
chmod 755 templates/mokoonyx/html
|
||||
chmod 755 media/templates/site/mokoonyx
|
||||
```
|
||||
|
||||
### Method 2: Direct Copy to Existing Installation
|
||||
|
||||
If you have direct filesystem access (e.g., local development):
|
||||
|
||||
1. **Copy template files** (excluding media):
|
||||
```bash
|
||||
# From repository root
|
||||
cd src
|
||||
|
||||
# Copy to Joomla templates directory
|
||||
cp component.php /path/to/joomla/templates/mokoonyx/
|
||||
cp error.php /path/to/joomla/templates/mokoonyx/
|
||||
cp index.php /path/to/joomla/templates/mokoonyx/
|
||||
cp offline.php /path/to/joomla/templates/mokoonyx/
|
||||
cp templateDetails.xml /path/to/joomla/templates/mokoonyx/
|
||||
cp joomla.asset.json /path/to/joomla/templates/mokoonyx/
|
||||
|
||||
# Copy directories
|
||||
cp -r html /path/to/joomla/templates/mokoonyx/
|
||||
cp -r language /path/to/joomla/templates/mokoonyx/
|
||||
cp -r administrator /path/to/joomla/templates/mokoonyx/
|
||||
```
|
||||
|
||||
2. **Copy media files separately**:
|
||||
```bash
|
||||
# Copy media to the media directory
|
||||
cp -r media/* /path/to/joomla/media/templates/site/mokoonyx/
|
||||
```
|
||||
|
||||
3. **Clear Joomla cache**:
|
||||
- In Joomla admin: **System → Clear Cache**
|
||||
- Or delete: `/path/to/joomla/cache/*` and `/path/to/joomla/administrator/cache/*`
|
||||
|
||||
### Method 3: Symlink for Development (Linux/Mac only)
|
||||
|
||||
For active development where you want changes to immediately reflect:
|
||||
|
||||
1. **Create symlinks**:
|
||||
```bash
|
||||
# Remove existing directory if present
|
||||
rm -rf /path/to/joomla/templates/mokoonyx
|
||||
rm -rf /path/to/joomla/media/templates/site/mokoonyx
|
||||
|
||||
# Create parent directories if needed
|
||||
mkdir -p /path/to/joomla/templates
|
||||
mkdir -p /path/to/joomla/media/templates/site
|
||||
|
||||
# Symlink template files
|
||||
ln -s /path/to/MokoOnyx/src /path/to/joomla/templates/mokoonyx
|
||||
|
||||
# Symlink media files
|
||||
ln -s /path/to/MokoOnyx/src/media /path/to/joomla/media/templates/site/mokoonyx
|
||||
```
|
||||
|
||||
2. **Note**: This won't work as-is because the src directory includes the media folder. You'll need to:
|
||||
```bash
|
||||
# Better approach for symlinks:
|
||||
# Link everything except media at template root
|
||||
cd /path/to/joomla/templates
|
||||
mkdir -p mokoonyx
|
||||
cd mokoonyx
|
||||
|
||||
ln -s /path/to/MokoOnyx/src/component.php
|
||||
ln -s /path/to/MokoOnyx/src/error.php
|
||||
ln -s /path/to/MokoOnyx/src/index.php
|
||||
ln -s /path/to/MokoOnyx/src/offline.php
|
||||
ln -s /path/to/MokoOnyx/src/templateDetails.xml
|
||||
ln -s /path/to/MokoOnyx/src/joomla.asset.json
|
||||
ln -s /path/to/MokoOnyx/src/html
|
||||
ln -s /path/to/MokoOnyx/src/language
|
||||
ln -s /path/to/MokoOnyx/src/administrator
|
||||
|
||||
# Link media separately
|
||||
ln -s /path/to/MokoOnyx/src/media /path/to/joomla/media/templates/site/mokoonyx
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Language Files Not Loading
|
||||
|
||||
**Problem**: Language strings appear as language keys (e.g., `TPL_MOKOONYX_LABEL`)
|
||||
|
||||
**Solution**: Ensure the `language` and `administrator` folders are present in your template directory:
|
||||
|
||||
```bash
|
||||
# Check if folders exist
|
||||
ls -la /path/to/joomla/templates/mokoonyx/language
|
||||
ls -la /path/to/joomla/templates/mokoonyx/administrator
|
||||
```
|
||||
|
||||
The `templateDetails.xml` should contain (lines 54-55):
|
||||
```xml
|
||||
<files>
|
||||
<!-- ... other files ... -->
|
||||
<folder>language</folder>
|
||||
<folder>administrator</folder>
|
||||
</files>
|
||||
```
|
||||
|
||||
### CSS/JS Not Loading
|
||||
|
||||
**Problem**: Styles or scripts don't apply
|
||||
|
||||
**Solution**: Verify media files are in the correct location:
|
||||
|
||||
```bash
|
||||
# Check media directory structure
|
||||
ls -la /path/to/joomla/media/templates/site/mokoonyx/
|
||||
# Should show: css/, js/, images/, fonts/
|
||||
```
|
||||
|
||||
Clear Joomla cache:
|
||||
- Admin: **System → Clear Cache**
|
||||
- Check browser developer console for 404 errors
|
||||
|
||||
### Template Not Appearing in Template Manager
|
||||
|
||||
**Problem**: MokoOnyx doesn't show in **System → Site Templates**
|
||||
|
||||
**Solution**:
|
||||
1. Verify `templateDetails.xml` is present in `/path/to/joomla/templates/mokoonyx/`
|
||||
2. Check file permissions (should be readable by web server)
|
||||
3. Verify XML is well-formed:
|
||||
```bash
|
||||
xmllint --noout /path/to/joomla/templates/mokoonyx/templateDetails.xml
|
||||
```
|
||||
4. Check Joomla's error logs for XML parsing errors
|
||||
|
||||
### File Permission Issues
|
||||
|
||||
**Problem**: "Permission denied" or template files not readable
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Set proper ownership (replace www-data with your web server user)
|
||||
chown -R www-data:www-data /path/to/joomla/templates/mokoonyx
|
||||
chown -R www-data:www-data /path/to/joomla/media/templates/site/mokoonyx
|
||||
|
||||
# Set proper permissions
|
||||
find /path/to/joomla/templates/mokoonyx -type d -exec chmod 755 {} \;
|
||||
find /path/to/joomla/templates/mokoonyx -type f -exec chmod 644 {} \;
|
||||
find /path/to/joomla/media/templates/site/mokoonyx -type d -exec chmod 755 {} \;
|
||||
find /path/to/joomla/media/templates/site/mokoonyx -type f -exec chmod 644 {} \;
|
||||
```
|
||||
|
||||
## When to Use Manual Deployment
|
||||
|
||||
### ✅ Use Manual Deployment For:
|
||||
|
||||
- **Active Development**: Testing changes immediately without rebuilding packages
|
||||
- **Local Development**: Working on a local Joomla instance
|
||||
- **Quick Fixes**: Making emergency hotfixes directly on a development server
|
||||
- **Learning**: Understanding the template structure and Joomla's file organization
|
||||
|
||||
### ❌ Don't Use Manual Deployment For:
|
||||
|
||||
- **Production Sites**: Always use packaged ZIP files from releases
|
||||
- **Client Sites**: Use proper Joomla extension installation
|
||||
- **Version Control**: Can lead to inconsistent deployments
|
||||
- **Staging Environments**: Use CI/CD or release packages
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Always Test Locally First**: Don't deploy untested changes to production
|
||||
2. **Keep Backups**: Back up both template and media directories before updating
|
||||
3. **Use Version Control**: Track your customizations separately from manual deployments
|
||||
4. **Document Changes**: Note any manual file modifications
|
||||
5. **Clear Cache**: Always clear Joomla cache after manual file updates
|
||||
6. **Verify Permissions**: Ensure web server can read all files
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- **[Quick Start Guide](QUICK_START.md)** - Development environment setup
|
||||
- **[Joomla Development Guide](JOOMLA_DEVELOPMENT.md)** - Complete development workflows
|
||||
- **[Release Process](RELEASE_PROCESS.md)** - How to create proper release packages
|
||||
|
||||
## Support
|
||||
|
||||
If you encounter issues with manual deployment:
|
||||
|
||||
1. Check this troubleshooting guide first
|
||||
2. Review [Joomla's template documentation](https://docs.joomla.org/J4.x:Creating_a_Simple_Template)
|
||||
3. Open an issue on [GitHub](https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx/issues)
|
||||
4. Contact: hello@mokoconsulting.tech
|
||||
|
||||
---
|
||||
|
||||
**Document Version**: 1.0.0
|
||||
**Last Updated**: 2026-03-01
|
||||
**Status**: Active
|
||||
725
docs/MODULE_OVERRIDES.md
Normal file
725
docs/MODULE_OVERRIDES.md
Normal file
@@ -0,0 +1,725 @@
|
||||
<!--
|
||||
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
|
||||
|
||||
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: MokoOnyx.Documentation
|
||||
REPO: https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx
|
||||
FILE: docs/MODULE_OVERRIDES.md
|
||||
VERSION: 03.09.03
|
||||
BRIEF: Comprehensive guide to MokoOnyx mobile-responsive module overrides
|
||||
PATH: /docs/MODULE_OVERRIDES.md
|
||||
-->
|
||||
|
||||
# Module & Component Overrides — MokoOnyx
|
||||
|
||||
This document provides a comprehensive guide to all mobile-responsive module and component overrides included in MokoOnyx.
|
||||
|
||||
## Overview
|
||||
|
||||
MokoOnyx includes **16 mobile-responsive module overrides** and **12 component view overrides** designed to enhance the mobile user experience for third-party extensions and the Main Menu navigation.
|
||||
|
||||
**Important**: Following Cassiopeia template best practices, MokoOnyx avoids overriding standard Joomla core modules (such as mod_search, mod_login, mod_breadcrumbs) to ensure proper language loading and compatibility. **Exception**: mod_menu "Main Menu" override provides essential Bootstrap 5 collapsible dropdown functionality.
|
||||
|
||||
### Alternative Layouts, Not Replacements
|
||||
|
||||
**All MokoOnyx overrides use alternative layout names (`mobile.php`) instead of replacing default layouts (`default.php`).** This means:
|
||||
|
||||
- ✅ Default Joomla layouts continue to work unchanged
|
||||
- ✅ You must explicitly select the "mobile" layout in module/menu item settings
|
||||
- ✅ Joomla core updates don't break your site
|
||||
- ✅ Full control over which modules use enhanced layouts
|
||||
|
||||
**📖 See [OVERRIDE_PHILOSOPHY.md](OVERRIDE_PHILOSOPHY.md) for complete details on how to activate and use these alternative layouts.**
|
||||
|
||||
### Key Features
|
||||
|
||||
All module overrides share these characteristics:
|
||||
|
||||
- **Mobile-First Design**: Optimized for mobile devices with responsive breakpoints
|
||||
- **Touch Targets**: 48px on mobile, 44px on desktop (WCAG 2.1 compliant)
|
||||
- **Input Font Size**: 16px minimum on mobile (prevents iOS zoom)
|
||||
- **Accessibility**: Full ARIA labels, keyboard navigation, semantic HTML
|
||||
- **BEM Naming**: Consistent CSS class naming convention
|
||||
- **CSS Variables**: Integration with template color schemes
|
||||
- **Security**: Proper escaping, _JEXEC checks, index.html protection
|
||||
- **Documentation**: Each override includes comprehensive README
|
||||
|
||||
## Module Categories
|
||||
|
||||
### 1. VirtueMart E-Commerce Modules
|
||||
|
||||
Five comprehensive overrides for VirtueMart shopping functionality.
|
||||
|
||||
**Master Documentation**: [VIRTUEMART_MODULES_README.md](../src/html/VIRTUEMART_MODULES_README.md)
|
||||
|
||||
#### mod_virtuemart_cart
|
||||
**Location**: `src/html/mod_virtuemart_cart/`
|
||||
|
||||
Shopping cart display with product list and checkout button.
|
||||
|
||||
**Features**:
|
||||
- Responsive product cards
|
||||
- Remove item buttons with confirmations
|
||||
- Price display with currency formatting
|
||||
- Checkout button with prominent styling
|
||||
|
||||
#### mod_virtuemart_product
|
||||
**Location**: `src/html/mod_virtuemart_product/`
|
||||
|
||||
Product showcase with grid layouts.
|
||||
|
||||
**Features**:
|
||||
- Responsive grid: 1-4 columns based on screen size
|
||||
- Product images with hover effects
|
||||
- Price display and "Add to Cart" buttons
|
||||
- Rating display support
|
||||
|
||||
#### mod_virtuemart_currencies
|
||||
**Location**: `src/html/mod_virtuemart_currencies/`
|
||||
|
||||
Currency selector dropdown for multi-currency stores.
|
||||
|
||||
**Features**:
|
||||
- Accessible dropdown with proper labels
|
||||
- Currency symbol and name display
|
||||
- Responsive button styling
|
||||
|
||||
#### mod_virtuemart_category
|
||||
**Location**: `src/html/mod_virtuemart_category/`
|
||||
|
||||
Category navigation with hierarchical display.
|
||||
|
||||
**Features**:
|
||||
- Expandable subcategories
|
||||
- Product count display
|
||||
- Hierarchical indentation
|
||||
- Active category highlighting
|
||||
|
||||
#### mod_virtuemart_manufacturer
|
||||
**Location**: `src/html/mod_virtuemart_manufacturer/`
|
||||
|
||||
Manufacturer/brand display with grid layout.
|
||||
|
||||
**Features**:
|
||||
- Responsive grid: 2-4 columns
|
||||
- Logo display support
|
||||
- Product count per manufacturer
|
||||
|
||||
---
|
||||
|
||||
### 2. Main Menu & Community Builder Modules
|
||||
|
||||
Three essential Community Builder and navigation module overrides.
|
||||
|
||||
#### mod_menu (Main Menu)
|
||||
**Location**: `src/html/mod_menu/`
|
||||
|
||||
Bootstrap 5 responsive navigation menu with collapsible dropdown functionality.
|
||||
|
||||
**Files**:
|
||||
- `mainmenu.php` - Main layout with Bootstrap navbar
|
||||
- `mainmenu_component.php` - Component menu items
|
||||
- `mainmenu_heading.php` - Heading menu items
|
||||
- `mainmenu_separator.php` - Separator menu items
|
||||
- `mainmenu_url.php` - URL menu items
|
||||
|
||||
**Features**:
|
||||
- Bootstrap 5 navbar structure with collapsible hamburger menu
|
||||
- Multi-level dropdown support (hover on desktop, tap on mobile)
|
||||
- WCAG 2.1 compliant touch targets (48px mobile, 44px desktop)
|
||||
- BEM naming convention: `.mod-menu-main__*`
|
||||
- Active state indicators for current menu items
|
||||
- ARIA labels and keyboard navigation support
|
||||
- Alternative layout named `mainmenu.php` (not `default.php`)
|
||||
|
||||
**Activation**: Select "Mainmenu" layout in Joomla Administrator → Modules → Menu Module → Advanced Tab → Alternative Layout
|
||||
|
||||
**Note**: Unlike the broken mod_menu override removed in v03.08.01, this v03.08.03 version is properly structured based on Joomla core layouts and Bootstrap 5, ensuring language strings load correctly and menu functionality works as expected.
|
||||
|
||||
#### mod_cblogin
|
||||
**Location**: `src/html/mod_cblogin/`
|
||||
|
||||
Community Builder login with avatar display.
|
||||
|
||||
**Features**:
|
||||
- User avatar when logged in
|
||||
- CB-specific login form
|
||||
- Profile link
|
||||
- Logout button
|
||||
|
||||
#### mod_comprofilerOnline
|
||||
**Location**: `src/html/mod_comprofilerOnline/`
|
||||
|
||||
Community Builder online users display.
|
||||
|
||||
**Features**:
|
||||
- User count display
|
||||
- Avatar grid layout
|
||||
- Username display
|
||||
- Online status indicators
|
||||
|
||||
---
|
||||
|
||||
### 3. Industry Extension Modules
|
||||
|
||||
Eight popular third-party extension module overrides plus component views.
|
||||
|
||||
#### K2 Content Extension
|
||||
|
||||
##### mod_k2_content
|
||||
**Location**: `src/html/mod_k2_content/`
|
||||
|
||||
K2 content display with advanced layouts.
|
||||
|
||||
**Features**:
|
||||
- Responsive grid: 1-3 columns
|
||||
- Featured images with lazy loading
|
||||
- Category, author, date metadata
|
||||
- Excerpt support
|
||||
- Tag display
|
||||
|
||||
#### AcyMailing Newsletter
|
||||
|
||||
##### mod_acymailing
|
||||
**Location**: `src/html/mod_acymailing/`
|
||||
|
||||
Newsletter subscription form.
|
||||
|
||||
**Features**:
|
||||
- Email validation
|
||||
- Privacy checkbox
|
||||
- Success/error messaging
|
||||
- GDPR compliance fields
|
||||
|
||||
#### HikaShop E-Commerce
|
||||
|
||||
##### mod_hikashop_cart
|
||||
**Location**: `src/html/mod_hikashop_cart/`
|
||||
|
||||
HikaShop shopping cart module.
|
||||
|
||||
**Features**:
|
||||
- Product list with images
|
||||
- Quantity adjustment
|
||||
- Price totals
|
||||
- Checkout button
|
||||
|
||||
#### Kunena Forum
|
||||
|
||||
Four comprehensive forum modules plus component view.
|
||||
|
||||
##### mod_kunenalatest
|
||||
**Location**: `src/html/mod_kunenalatest/`
|
||||
|
||||
Latest forum posts display.
|
||||
|
||||
**Features**:
|
||||
- Post excerpts
|
||||
- Author avatars
|
||||
- Reply count
|
||||
- Post date
|
||||
|
||||
##### mod_kunenalogin
|
||||
**Location**: `src/html/mod_kunenalogin/`
|
||||
|
||||
Forum-specific login module.
|
||||
|
||||
**Features**:
|
||||
- User avatar display
|
||||
- Forum statistics
|
||||
- Quick login form
|
||||
- Profile link
|
||||
|
||||
##### mod_kunenasearch
|
||||
**Location**: `src/html/mod_kunenasearch/`
|
||||
|
||||
Forum search with button positions.
|
||||
|
||||
**Features**:
|
||||
- Multiple button positions (left, right, top)
|
||||
- Search placeholder text
|
||||
- Icon support
|
||||
- 48px touch targets
|
||||
|
||||
##### mod_kunenastats
|
||||
**Location**: `src/html/mod_kunenastats/`
|
||||
|
||||
Forum statistics display.
|
||||
|
||||
**Features**:
|
||||
- Visual stat cards
|
||||
- Member count
|
||||
- Topic/post totals
|
||||
- Latest member
|
||||
- Responsive grid layout
|
||||
|
||||
##### com_kunena (Component)
|
||||
**Location**: `src/html/com_kunena/`
|
||||
|
||||
Forum category list view.
|
||||
|
||||
**Views**:
|
||||
- `category/default.php` - Category listing with icons
|
||||
|
||||
#### OS Membership Pro
|
||||
|
||||
Module and component overrides for membership management.
|
||||
|
||||
##### mod_osmembership
|
||||
**Location**: `src/html/mod_osmembership/`
|
||||
|
||||
Membership plans module.
|
||||
|
||||
**Features**:
|
||||
- Plan cards with pricing
|
||||
- Feature lists
|
||||
- Signup buttons
|
||||
- Badge displays (popular, featured)
|
||||
|
||||
##### com_osmembership (Component)
|
||||
**Location**: `src/html/com_osmembership/`
|
||||
|
||||
Membership pricing tables.
|
||||
|
||||
**Views**:
|
||||
- `plans/default.php` - Responsive pricing table with comparison features
|
||||
|
||||
---
|
||||
|
||||
### 4. Community Builder Components
|
||||
|
||||
Four comprehensive component view overrides for Community Builder user management.
|
||||
|
||||
#### com_comprofiler
|
||||
**Location**: `src/html/com_comprofiler/`
|
||||
|
||||
Mobile-responsive views for Community Builder user profiles, registration, and login.
|
||||
|
||||
##### userprofile
|
||||
User profile display with tabbed interface.
|
||||
|
||||
**Features**:
|
||||
- Large avatar display (150px)
|
||||
- Tabbed interface for profile sections
|
||||
- Custom field display with labels
|
||||
- Online status indicator
|
||||
- Responsive layout: vertical mobile → horizontal desktop
|
||||
|
||||
##### userslist
|
||||
User directory with search and grid layout.
|
||||
|
||||
**Features**:
|
||||
- Search functionality with accessible form
|
||||
- Responsive grid: 1 column mobile → 2-3 columns desktop
|
||||
- User cards with avatars (80px)
|
||||
- Custom field display
|
||||
- Profile view buttons
|
||||
- Pagination support
|
||||
|
||||
##### registers
|
||||
Multi-step registration form with validation.
|
||||
|
||||
**Features**:
|
||||
- Fieldset organization with legends
|
||||
- Required field indicators (*)
|
||||
- Input validation and error display
|
||||
- Captcha support section
|
||||
- Terms & conditions checkbox
|
||||
- GDPR-compliant design
|
||||
- 16px input font on mobile
|
||||
|
||||
##### login
|
||||
Login page with remember me and helper links.
|
||||
|
||||
**Features**:
|
||||
- Centered login container (max-width: 450px)
|
||||
- Username/password fields with autocomplete
|
||||
- Remember me checkbox
|
||||
- Registration and password recovery links
|
||||
- CSRF token support
|
||||
- Responsive padding adjustments
|
||||
|
||||
### 5. JEM (Joomla Event Manager) Components
|
||||
|
||||
Five comprehensive component view overrides for JEM event management.
|
||||
|
||||
#### com_jem
|
||||
**Location**: `src/html/com_jem/`
|
||||
|
||||
Mobile-responsive views for JEM event listings, details, calendar, venues, and categories.
|
||||
|
||||
##### eventslist
|
||||
Event listing with card-based layout.
|
||||
|
||||
**Features**:
|
||||
- Event cards with date, time, and venue
|
||||
- Category badges with color coding
|
||||
- Responsive event grid layout
|
||||
- Event description excerpts
|
||||
- Read more buttons with clear calls-to-action
|
||||
- Pagination support
|
||||
- Empty state messaging
|
||||
|
||||
##### event
|
||||
Single event details view with comprehensive information.
|
||||
|
||||
**Features**:
|
||||
- Large event image display (responsive)
|
||||
- Date and time with structured data
|
||||
- Venue information with maps link
|
||||
- Event description with full content
|
||||
- Category display with badges
|
||||
- Registration information (if enabled)
|
||||
- Contact information display
|
||||
- Back to events navigation
|
||||
- Meta information with icons
|
||||
|
||||
##### calendar
|
||||
Monthly calendar view with event indicators.
|
||||
|
||||
**Features**:
|
||||
- Month navigation (previous/next)
|
||||
- Calendar grid with weekday headers
|
||||
- Event indicators on dates with events
|
||||
- Responsive calendar layout
|
||||
- Today highlighting
|
||||
- Event list for selected month
|
||||
- Event count per day display
|
||||
- Touch-friendly navigation buttons
|
||||
|
||||
##### venue
|
||||
Venue details with location and upcoming events.
|
||||
|
||||
**Features**:
|
||||
- Venue image display
|
||||
- Complete address information
|
||||
- Website link (external)
|
||||
- Google Maps integration
|
||||
- Venue description
|
||||
- Upcoming events at venue
|
||||
- Location coordinates display
|
||||
- Back navigation
|
||||
|
||||
##### categories
|
||||
Event category listing with descriptions.
|
||||
|
||||
**Features**:
|
||||
- Category cards with images
|
||||
- Category descriptions
|
||||
- Event count per category
|
||||
- View category buttons
|
||||
- Responsive grid layout
|
||||
- Empty state messaging
|
||||
- Pagination support
|
||||
|
||||
---
|
||||
|
||||
## CSS Architecture
|
||||
|
||||
All module styles are located in `src/media/css/template.css` with dedicated sections:
|
||||
|
||||
### CSS Sections
|
||||
|
||||
1. **MOD_SEARCH MOBILE RESPONSIVE STYLES** (Lines ~18400+)
|
||||
- Search box layouts
|
||||
- Button position variants
|
||||
- Input styling
|
||||
|
||||
2. **VIRTUEMART MODULE MOBILE RESPONSIVE STYLES** (Lines ~18500+)
|
||||
- Cart product cards
|
||||
- Product grids
|
||||
- Currency selector
|
||||
- Category navigation
|
||||
- Manufacturer displays
|
||||
|
||||
3. **STANDARD JOOMLA & COMMUNITY BUILDER MODULE STYLES** (Lines ~19300+)
|
||||
- Menu navigation
|
||||
- Breadcrumbs
|
||||
- Login forms
|
||||
- Article displays
|
||||
- CB module components
|
||||
|
||||
4. **INDUSTRY EXTENSION MODULE STYLES** (Lines ~19800+)
|
||||
- K2 content grids
|
||||
- AcyMailing forms
|
||||
- HikaShop cart
|
||||
- Kunena forum modules
|
||||
- OS Membership pricing
|
||||
|
||||
5. **COMMUNITY BUILDER COMPONENT STYLES** (Lines ~21000+)
|
||||
- User profile layouts
|
||||
- Users list grids
|
||||
- Registration forms
|
||||
- Login pages
|
||||
- Tab interfaces
|
||||
|
||||
6. **JEM COMPONENT STYLES** (Lines ~22000+)
|
||||
- Event list cards
|
||||
- Event details layout
|
||||
- Calendar grid
|
||||
- Venue information
|
||||
- Category displays
|
||||
|
||||
### CSS Variables Integration
|
||||
|
||||
All modules integrate with template CSS variables:
|
||||
|
||||
```css
|
||||
/* Common Variables Used */
|
||||
--body-color /* Text color */
|
||||
--link-color /* Link color */
|
||||
--link-hover-color /* Link hover color */
|
||||
--border-color /* Border color */
|
||||
--secondary-bg /* Background color */
|
||||
--border-radius /* Border radius */
|
||||
--input-bg /* Input background */
|
||||
--input-border-color /* Input border */
|
||||
--btn-primary-bg /* Primary button */
|
||||
--btn-primary-hover-bg /* Button hover */
|
||||
```
|
||||
|
||||
See [CSS_VARIABLES.md](CSS_VARIABLES.md) for complete reference.
|
||||
|
||||
---
|
||||
|
||||
## Responsive Breakpoints
|
||||
|
||||
All modules use Bootstrap-aligned breakpoints:
|
||||
|
||||
| Breakpoint | Size | Typical Changes |
|
||||
|------------|-----------|-----------------------------------|
|
||||
| `xs` | < 576px | Single column, stacked layouts |
|
||||
| `sm` | ≥ 576px | 2 columns for grids |
|
||||
| `md` | ≥ 768px | 3 columns, horizontal layouts |
|
||||
| `lg` | ≥ 992px | 4 columns, expanded spacing |
|
||||
| `xl` | ≥ 1200px | Maximum width, optimal spacing |
|
||||
| `xxl` | ≥ 1400px | Extra spacing |
|
||||
|
||||
---
|
||||
|
||||
## Accessibility Features
|
||||
|
||||
All overrides implement comprehensive accessibility:
|
||||
|
||||
### ARIA Labels
|
||||
- Descriptive labels for all interactive elements
|
||||
- `aria-label` for icon-only buttons
|
||||
- `aria-describedby` for form fields
|
||||
- `aria-live` for dynamic content
|
||||
|
||||
### Keyboard Navigation
|
||||
- Proper tab order
|
||||
- Focus states on all interactive elements
|
||||
- Keyboard-accessible dropdowns
|
||||
- Skip links where appropriate
|
||||
|
||||
### Screen Readers
|
||||
- Semantic HTML5 elements
|
||||
- Hidden text for icon-only elements
|
||||
- Proper heading hierarchy
|
||||
- Alternative text for images
|
||||
|
||||
### WCAG 2.1 Compliance
|
||||
- Touch targets: 48px minimum on mobile
|
||||
- Color contrast ratios meet AA standards
|
||||
- Text resizable to 200% without loss
|
||||
- No content relies on color alone
|
||||
|
||||
---
|
||||
|
||||
## Customization Guide
|
||||
|
||||
### Override Customization
|
||||
|
||||
Each module can be customized in two ways:
|
||||
|
||||
#### 1. CSS Customization
|
||||
|
||||
Edit `src/media/css/user.css` to add custom styles:
|
||||
|
||||
```css
|
||||
/* Example: Change product grid columns */
|
||||
@media (min-width: 768px) {
|
||||
.mod-vm-product__grid {
|
||||
grid-template-columns: repeat(3, 1fr);
|
||||
}
|
||||
}
|
||||
|
||||
/* Example: Customize cart button */
|
||||
.mod-vm-cart__checkout-button {
|
||||
background-color: #28a745;
|
||||
}
|
||||
```
|
||||
|
||||
#### 2. Template Override Customization
|
||||
|
||||
Copy the entire module directory and modify:
|
||||
|
||||
```bash
|
||||
# Keep original override as reference
|
||||
cp -r src/html/mod_virtuemart_cart src/html/mod_virtuemart_cart_original
|
||||
|
||||
# Modify your version
|
||||
# Edit src/html/mod_virtuemart_cart/default.php
|
||||
```
|
||||
|
||||
### CSS Variables Override
|
||||
|
||||
Override CSS variables in your custom color scheme:
|
||||
|
||||
```css
|
||||
/* src/media/css/theme/light.custom.css */
|
||||
:root {
|
||||
--vm-price-color: #28a745;
|
||||
--vm-cart-bg: #f8f9fa;
|
||||
--vm-button-primary: #007bff;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### When Using Overrides
|
||||
|
||||
1. **Test Across Devices**: Always test on actual mobile devices
|
||||
2. **Maintain Accessibility**: Don't remove ARIA labels or keyboard navigation
|
||||
3. **Keep BEM Naming**: Use established class naming patterns
|
||||
4. **Security First**: Always escape output and validate input
|
||||
5. **Document Changes**: Comment your customizations
|
||||
|
||||
### When Updating
|
||||
|
||||
1. **Backup First**: Always backup your site before updating
|
||||
2. **Review Changes**: Check CHANGELOG.md for breaking changes
|
||||
3. **Test Thoroughly**: Test all modules after updates
|
||||
4. **Custom Overrides**: May need adjustments after template updates
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### Module Not Displaying Correctly
|
||||
1. Clear Joomla cache (System → Clear Cache)
|
||||
2. Check module is published and assigned to correct position
|
||||
3. Verify template is assigned to menu items
|
||||
4. Check browser console for JavaScript errors
|
||||
|
||||
#### Styles Not Applying
|
||||
1. Clear browser cache (Ctrl+F5 / Cmd+Shift+R)
|
||||
2. Verify `template.css` is loading
|
||||
3. Check CSS specificity conflicts
|
||||
4. Review custom CSS in `user.css`
|
||||
|
||||
#### Mobile View Issues
|
||||
1. Test with browser dev tools responsive mode
|
||||
2. Check viewport meta tag in template
|
||||
3. Verify breakpoint media queries
|
||||
4. Test on actual devices when possible
|
||||
|
||||
#### Accessibility Issues
|
||||
1. Run WAVE or axe DevTools accessibility check
|
||||
2. Test with keyboard navigation only
|
||||
3. Verify screen reader compatibility
|
||||
4. Check color contrast ratios
|
||||
|
||||
### Getting Help
|
||||
|
||||
- **Documentation**: Check module-specific README files
|
||||
- **GitHub Issues**: [Report issues](https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx/issues)
|
||||
- **Support**: hello@mokoconsulting.tech
|
||||
|
||||
---
|
||||
|
||||
## How to Activate Alternative Layouts
|
||||
|
||||
All MokoOnyx overrides are **alternative layouts** that must be explicitly activated. They do not automatically replace default layouts.
|
||||
|
||||
### Quick Start: Enable Mobile Layout
|
||||
|
||||
1. **Go to Joomla Administrator** → Extensions → Modules
|
||||
2. **Open the module** you want to enhance (e.g., VirtueMart Cart)
|
||||
3. **Navigate to Advanced tab**
|
||||
4. **Find "Alternative Layout" field**
|
||||
5. **Select "MokoOnyx - mobile"** from dropdown
|
||||
6. **Save & Close**
|
||||
|
||||
### For Menu Items (Component Views)
|
||||
|
||||
1. **Go to Menus** → Select your menu
|
||||
2. **Open the menu item** (e.g., Events List)
|
||||
3. **Navigate to Advanced Options or Page Display tab**
|
||||
4. **Find "Alternative Layout" field**
|
||||
5. **Select "MokoOnyx - mobile"** from dropdown
|
||||
6. **Save & Close**
|
||||
|
||||
### Apply to All Modules in a Position
|
||||
|
||||
In your template's `index.php`, specify layout for entire module position:
|
||||
|
||||
```php
|
||||
<jdoc:include type="modules" name="sidebar-left" style="none" layout="mobile" />
|
||||
```
|
||||
|
||||
**📖 For complete documentation, see [OVERRIDE_PHILOSOPHY.md](OVERRIDE_PHILOSOPHY.md)**
|
||||
|
||||
---
|
||||
|
||||
## Version History
|
||||
|
||||
| Version | Date | Changes |
|
||||
|----------|------------|--------------------------------------------------|
|
||||
| 03.08.04 | 2026-02-27 | Added alternative layout activation instructions, JEM overrides |
|
||||
| 03.08.03 | 2026-02-25 | Removed mod_search override per Cassiopeia philosophy |
|
||||
| 03.08.00 | 2026-02-22 | Added Community Builder component overrides |
|
||||
| 03.07.00 | 2026-02-22 | Initial release of all mobile-responsive overrides |
|
||||
|
||||
---
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- **Override Philosophy**: [OVERRIDE_PHILOSOPHY.md](OVERRIDE_PHILOSOPHY.md) ⭐ **Start here**
|
||||
- **Main README**: [README.md](../README.md)
|
||||
- **Changelog**: [CHANGELOG.md](../CHANGELOG.md)
|
||||
- **CSS Variables**: [CSS_VARIABLES.md](CSS_VARIABLES.md)
|
||||
- **Repository**: [GitHub](https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx)
|
||||
|
||||
---
|
||||
|
||||
## Metadata
|
||||
|
||||
* Document: docs/MODULE_OVERRIDES.md
|
||||
* Repository: [https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx](https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx)
|
||||
* Path: /docs/MODULE_OVERRIDES.md
|
||||
* Owner: Moko Consulting
|
||||
* Version: 03.07.00
|
||||
* Status: Active
|
||||
* Effective Date: 2026-02-22
|
||||
* Classification: Public Open Source Documentation
|
||||
|
||||
## Revision History
|
||||
|
||||
| Date | Change Summary | Author |
|
||||
| ---------- | ----------------------------------------------------- | --------------- |
|
||||
| 2026-02-22 | Initial creation with comprehensive module override documentation | GitHub Copilot |
|
||||
332
docs/OVERRIDE_PHILOSOPHY.md
Normal file
332
docs/OVERRIDE_PHILOSOPHY.md
Normal file
@@ -0,0 +1,332 @@
|
||||
<!--
|
||||
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
|
||||
|
||||
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: MokoOnyx.Documentation
|
||||
REPO: https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx
|
||||
FILE: docs/OVERRIDE_PHILOSOPHY.md
|
||||
VERSION: 03.09.03
|
||||
BRIEF: Philosophy and implementation of non-replacing alternative layouts
|
||||
PATH: /docs/OVERRIDE_PHILOSOPHY.md
|
||||
-->
|
||||
|
||||
# Override Philosophy — MokoOnyx
|
||||
|
||||
## Core Principle: Add-On, Not Replacement
|
||||
|
||||
**MokoOnyx overrides are designed as alternative layouts, not replacements of default Joomla layouts.**
|
||||
|
||||
This means:
|
||||
- ✅ Default Joomla layouts continue to work unchanged
|
||||
- ✅ Site administrators can choose when to use our enhanced layouts
|
||||
- ✅ Updates to Joomla core layouts don't break the site
|
||||
- ✅ Compatibility with other extensions is maintained
|
||||
- ✅ Users have control over which layouts to use
|
||||
|
||||
---
|
||||
|
||||
## Technical Implementation
|
||||
|
||||
### Layout Naming Convention
|
||||
|
||||
All MokoOnyx overrides use **`mobile.php`** naming instead of **`default.php`**:
|
||||
|
||||
```
|
||||
❌ BAD (Replaces default):
|
||||
src/html/mod_virtuemart_cart/default.php
|
||||
|
||||
✅ GOOD (Alternative layout):
|
||||
src/html/mod_virtuemart_cart/mobile.php
|
||||
```
|
||||
|
||||
### How Joomla Handles Layouts
|
||||
|
||||
When a module or component looks for a layout, Joomla searches in this order:
|
||||
|
||||
1. **Template override with specified layout name**: `templates/mokoonyx/html/{extension}/{view}/{layout}.php`
|
||||
2. **Extension's specified layout**: `{extension}/tmpl/{view}/{layout}.php`
|
||||
3. **Template override for default layout**: `templates/mokoonyx/html/{extension}/{view}/default.php`
|
||||
4. **Extension's default layout**: `{extension}/tmpl/{view}/default.php`
|
||||
|
||||
By naming our overrides `mobile.php` instead of `default.php`, they become **step 1** alternatives that must be explicitly selected, rather than **step 3** replacements that are automatically used.
|
||||
|
||||
---
|
||||
|
||||
## How to Use Alternative Layouts
|
||||
|
||||
### Method 1: Module/Menu Item Settings
|
||||
|
||||
When editing a module or menu item in Joomla administrator:
|
||||
|
||||
1. Open the module/menu item for editing
|
||||
2. Navigate to the **Advanced** tab
|
||||
3. Find the **Alternative Layout** field
|
||||
4. Select **MokoOnyx - mobile** from the dropdown
|
||||
5. Save
|
||||
|
||||
### Method 2: Override in Module Position
|
||||
|
||||
If you want all modules in a specific position to use the mobile layout:
|
||||
|
||||
```php
|
||||
<!-- In your index.php template file -->
|
||||
<?php if ($this->countModules('sidebar-left')) : ?>
|
||||
<jdoc:include type="modules" name="sidebar-left" style="none" layout="mobile" />
|
||||
<?php endif; ?>
|
||||
```
|
||||
|
||||
### Method 3: Module Chrome (Advanced)
|
||||
|
||||
Create a custom module chrome in `templates/mokoonyx/html/layouts/chromes/` that automatically applies the mobile layout.
|
||||
|
||||
---
|
||||
|
||||
## Exception: Main Menu
|
||||
|
||||
**The only exception** to this philosophy is `mod_menu` with the "Main Menu" module type.
|
||||
|
||||
The template includes files like:
|
||||
- `src/html/mod_menu/mainmenu.php`
|
||||
- `src/html/mod_menu/mainmenu_component.php`
|
||||
- `src/html/mod_menu/mainmenu_heading.php`
|
||||
- `src/html/mod_menu/mainmenu_url.php`
|
||||
- `src/html/mod_menu/mainmenu_separator.php`
|
||||
|
||||
These use a **custom layout name** (`mainmenu`) instead of replacing `default.php`, which allows the site to:
|
||||
- Use the enhanced Bootstrap 5 collapsible menu for main navigation
|
||||
- Keep standard Joomla menus working in other positions
|
||||
- Provide better mobile navigation without breaking existing menus
|
||||
|
||||
To use this layout, set the module's **Alternative Layout** to **MokoOnyx - mainmenu**.
|
||||
|
||||
---
|
||||
|
||||
## Override Inventory
|
||||
|
||||
### Module Overrides (16 total)
|
||||
|
||||
All use `mobile.php` naming (alternative layout):
|
||||
|
||||
**VirtueMart (5)**:
|
||||
- `mod_virtuemart_cart/mobile.php`
|
||||
- `mod_virtuemart_product/mobile.php`
|
||||
- `mod_virtuemart_currencies/mobile.php`
|
||||
- `mod_virtuemart_category/mobile.php`
|
||||
- `mod_virtuemart_manufacturer/mobile.php`
|
||||
|
||||
**Community Builder (2)**:
|
||||
- `mod_cblogin/mobile.php`
|
||||
- `mod_comprofilerOnline/mobile.php`
|
||||
|
||||
**Main Menu (1)**:
|
||||
- `mod_menu/mainmenu.php` (custom layout name)
|
||||
|
||||
**Industry Extensions (8)**:
|
||||
- `mod_k2_content/mobile.php`
|
||||
- `mod_acymailing/mobile.php`
|
||||
- `mod_hikashop_cart/mobile.php`
|
||||
- `mod_kunenalatest/mobile.php`
|
||||
- `mod_kunenalogin/mobile.php`
|
||||
- `mod_kunenasearch/mobile.php`
|
||||
- `mod_kunenastats/mobile.php`
|
||||
- `mod_osmembership/mobile.php`
|
||||
|
||||
### Component View Overrides (12 total)
|
||||
|
||||
All use `mobile.php` naming (alternative layout):
|
||||
|
||||
**Community Builder (4)**:
|
||||
- `com_comprofiler/userprofile/mobile.php`
|
||||
- `com_comprofiler/userslist/mobile.php`
|
||||
- `com_comprofiler/registers/mobile.php`
|
||||
- `com_comprofiler/login/mobile.php`
|
||||
|
||||
**JEM - Joomla Event Manager (5)**:
|
||||
- `com_jem/eventslist/mobile.php`
|
||||
- `com_jem/event/mobile.php`
|
||||
- `com_jem/calendar/mobile.php`
|
||||
- `com_jem/venue/mobile.php`
|
||||
- `com_jem/categories/mobile.php`
|
||||
|
||||
**Kunena Forum (1)**:
|
||||
- `com_kunena/category/mobile.php`
|
||||
|
||||
**OSMembership (2)**:
|
||||
- `com_osmembership/plan/mobile.php`
|
||||
- `com_osmembership/plans/mobile.php`
|
||||
|
||||
**Joomla Core (2)**:
|
||||
- `com_content/article/toc-left.php` (custom layout name)
|
||||
- `com_content/article/toc-right.php` (custom layout name)
|
||||
|
||||
---
|
||||
|
||||
## Benefits of This Approach
|
||||
|
||||
### 1. **Zero Breaking Changes**
|
||||
|
||||
Existing sites continue to work exactly as before. No layouts are forcibly changed.
|
||||
|
||||
### 2. **Gradual Adoption**
|
||||
|
||||
Site administrators can:
|
||||
- Test mobile layouts on specific modules first
|
||||
- Roll out changes module-by-module
|
||||
- Keep some modules using default layouts if needed
|
||||
- Easily revert by changing the Alternative Layout setting
|
||||
|
||||
### 3. **Extension Compatibility**
|
||||
|
||||
Third-party extensions' default layouts remain untouched, preventing conflicts with:
|
||||
- Extension updates
|
||||
- Other templates
|
||||
- Custom development
|
||||
|
||||
### 4. **Joomla Core Updates**
|
||||
|
||||
When Joomla core updates:
|
||||
- Default layouts get new features/bug fixes automatically
|
||||
- Mobile layouts remain stable and tested
|
||||
- No emergency fixes needed after Joomla updates
|
||||
|
||||
### 5. **Multi-Language Support**
|
||||
|
||||
Joomla's language system loads extension language files properly because:
|
||||
- Extensions aren't hijacked by template overrides
|
||||
- Language strings come from the correct source
|
||||
- Translations work as expected
|
||||
|
||||
---
|
||||
|
||||
## Standards Not Overridden
|
||||
|
||||
Following Cassiopeia template best practices, MokoOnyx **does not override** standard Joomla core modules:
|
||||
|
||||
- ❌ `mod_breadcrumbs` - Use Joomla core layout
|
||||
- ❌ `mod_login` - Use Joomla core layout
|
||||
- ❌ `mod_articles_latest` - Use Joomla core layout
|
||||
- ❌ `mod_articles_category` - Use Joomla core layout
|
||||
- ❌ `mod_articles_news` - Use Joomla core layout
|
||||
- ❌ `mod_search` - Use Joomla core layout (removed in v03.08.03)
|
||||
|
||||
**Reason**: These modules have robust core layouts with proper language loading, accessibility, and ongoing Joomla maintenance.
|
||||
|
||||
---
|
||||
|
||||
## Developer Guidelines
|
||||
|
||||
When adding new overrides to MokoOnyx:
|
||||
|
||||
### ✅ DO:
|
||||
|
||||
1. Name files `mobile.php` or use descriptive custom names (`mainmenu.php`, `toc-left.php`)
|
||||
2. Document the alternative layout in MODULE_OVERRIDES.md
|
||||
3. Add CSS with BEM naming: `.{extension}-{view}__element`
|
||||
4. Test that default layouts still work
|
||||
5. Provide clear instructions for selecting the layout
|
||||
|
||||
### ❌ DON'T:
|
||||
|
||||
1. Create `default.php` files that replace core layouts
|
||||
2. Override standard Joomla core modules without strong justification
|
||||
3. Break backward compatibility
|
||||
4. Assume users will automatically get your layout
|
||||
5. Forget to document how to enable the alternative layout
|
||||
|
||||
---
|
||||
|
||||
## Migration from Replacing Overrides
|
||||
|
||||
If you're migrating from a template that used `default.php` overrides:
|
||||
|
||||
### Step 1: Identify Replaced Layouts
|
||||
|
||||
```bash
|
||||
find templates/oldtemplate/html -name "default.php"
|
||||
```
|
||||
|
||||
### Step 2: Rename to Alternative Layouts
|
||||
|
||||
```bash
|
||||
# For each default.php found:
|
||||
mv default.php mobile.php
|
||||
```
|
||||
|
||||
### Step 3: Update Module Settings
|
||||
|
||||
For each module using the old override:
|
||||
1. Edit module in administrator
|
||||
2. Advanced tab → Alternative Layout
|
||||
3. Select "mobile" from dropdown
|
||||
4. Save
|
||||
|
||||
### Step 4: Test
|
||||
|
||||
- Verify module displays correctly
|
||||
- Check that other modules still use default layouts
|
||||
- Confirm language strings load properly
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### My Alternative Layout Doesn't Appear in Dropdown
|
||||
|
||||
**Check:**
|
||||
1. File is in correct location: `templates/mokoonyx/html/{extension}/{view}/`
|
||||
2. File has `.php` extension
|
||||
3. File is not named `default.php`
|
||||
4. Cache is cleared (System → Clear Cache)
|
||||
|
||||
### Module Still Uses Default Layout
|
||||
|
||||
**Check:**
|
||||
1. Module's Alternative Layout setting in administrator
|
||||
2. Module position's `layout` parameter in `<jdoc:include>` tag
|
||||
3. File permissions (must be readable)
|
||||
4. Template is assigned to correct pages
|
||||
|
||||
### Layout Works But Looks Wrong
|
||||
|
||||
**Check:**
|
||||
1. CSS is loaded: inspect element and check for `.{extension}-{view}__` classes
|
||||
2. `template.css` is up to date
|
||||
3. Browser cache is cleared
|
||||
4. CSS variables are defined in template
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- [Joomla Docs: Layout Overrides](https://docs.joomla.org/Layout_Overrides_in_Joomla)
|
||||
- [Joomla Docs: Alternative Layouts](https://docs.joomla.org/J3.x:How_to_use_the_alternative_layout_feature)
|
||||
- [MODULE_OVERRIDES.md](MODULE_OVERRIDES.md) - Complete override inventory
|
||||
- [CSS_VARIABLES.md](CSS_VARIABLES.md) - Template styling system
|
||||
|
||||
---
|
||||
|
||||
## Version History
|
||||
|
||||
- **03.08.04**: Created OVERRIDE_PHILOSOPHY.md document
|
||||
- **03.08.03**: Removed mod_search override to align with philosophy
|
||||
- **03.08.02**: Removed standard Joomla module overrides for proper language loading
|
||||
- **Earlier**: Renamed all overrides from default.php to mobile.php (21 files)
|
||||
333
docs/QUICK_START.md
Normal file
333
docs/QUICK_START.md
Normal file
@@ -0,0 +1,333 @@
|
||||
# Quick Start Guide - MokoOnyx Development
|
||||
|
||||
Get up and running with MokoOnyx development in minutes.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before you begin, ensure you have:
|
||||
|
||||
- **Git** - For version control
|
||||
- **PHP 8.0+** - Required runtime
|
||||
- **Composer** - PHP dependency manager
|
||||
- **Make** (optional) - For convenient commands
|
||||
- **Code Editor** - VS Code recommended (tasks pre-configured)
|
||||
|
||||
## 5-Minute Setup
|
||||
|
||||
### 1. Clone the Repository
|
||||
|
||||
```bash
|
||||
git clone https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx.git
|
||||
cd MokoOnyx
|
||||
```
|
||||
|
||||
### 2. Install Development Dependencies
|
||||
|
||||
```bash
|
||||
# Using Make (recommended)
|
||||
make dev-setup
|
||||
|
||||
# Or manually
|
||||
composer global require "squizlabs/php_codesniffer:^3.0"
|
||||
composer global require phpstan/phpstan
|
||||
composer global require "phpcompatibility/php-compatibility:^9.0"
|
||||
composer global require codeception/codeception
|
||||
```
|
||||
|
||||
### 3. Validate Everything Works
|
||||
|
||||
```bash
|
||||
# Quick validation
|
||||
make validate-required
|
||||
|
||||
# Or comprehensive validation
|
||||
make validate
|
||||
```
|
||||
|
||||
## Common Tasks
|
||||
|
||||
### Development Workflow
|
||||
|
||||
```bash
|
||||
# 1. Make your changes
|
||||
vim src/index.php
|
||||
|
||||
# 2. Validate locally
|
||||
make validate-required
|
||||
|
||||
# 3. Check code quality
|
||||
make quality
|
||||
|
||||
# 4. Commit
|
||||
git add -A
|
||||
git commit -m "feat: add new feature"
|
||||
# (pre-commit hook runs automatically)
|
||||
|
||||
# 5. Push
|
||||
git push origin your-branch
|
||||
```
|
||||
|
||||
### Testing
|
||||
|
||||
```bash
|
||||
# Run all tests
|
||||
make test
|
||||
|
||||
# Run unit tests only
|
||||
make test-unit
|
||||
|
||||
# Run acceptance tests only
|
||||
make test-acceptance
|
||||
```
|
||||
|
||||
### Code Quality
|
||||
|
||||
```bash
|
||||
# Check everything
|
||||
make quality
|
||||
|
||||
# PHP CodeSniffer only
|
||||
make phpcs
|
||||
|
||||
# Auto-fix PHPCS issues
|
||||
make phpcs-fix
|
||||
|
||||
# PHPStan only
|
||||
make phpstan
|
||||
|
||||
# PHP compatibility check
|
||||
make phpcompat
|
||||
```
|
||||
|
||||
### Creating a Release Package
|
||||
|
||||
```bash
|
||||
# Package with auto-detected version
|
||||
make package
|
||||
|
||||
# Check package contents
|
||||
ls -lh dist/
|
||||
unzip -l dist/mokoonyx-*.zip
|
||||
```
|
||||
|
||||
## VS Code Integration
|
||||
|
||||
If using VS Code, press `Ctrl+Shift+P` (or `Cmd+Shift+P` on Mac) and type "Run Task" to see available tasks:
|
||||
|
||||
- **Validate All** - Run all validation scripts (default test task)
|
||||
- **Validate Required** - Run only required validations
|
||||
- **PHP CodeSniffer** - Check code style
|
||||
- **PHP CodeSniffer - Auto Fix** - Fix code style issues
|
||||
- **PHPStan** - Static analysis
|
||||
- **Run Tests** - Execute all tests
|
||||
- **Create Package** - Build distribution ZIP
|
||||
- **Install Git Hooks** - Set up pre-commit hooks
|
||||
|
||||
## Available Make Commands
|
||||
|
||||
Run `make help` to see all available commands:
|
||||
|
||||
```bash
|
||||
make help # Show all commands
|
||||
make dev-setup # Complete environment setup
|
||||
make validate # Run all validations
|
||||
make test # Run all tests
|
||||
make quality # Check code quality
|
||||
make package # Create distribution package
|
||||
make clean # Remove generated files
|
||||
make check # Quick check (validate + quality)
|
||||
make all # Complete build pipeline
|
||||
```
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
moko-cassiopeia/
|
||||
├── src/ # Joomla template source (template root)
|
||||
│ ├── component.php # Component template file
|
||||
│ ├── index.php # Main template file
|
||||
│ ├── offline.php # Offline page template
|
||||
│ ├── error.php # Error page template
|
||||
│ ├── templateDetails.xml # Template manifest
|
||||
│ ├── html/ # Module & component overrides
|
||||
│ ├── media/ # Assets (CSS, JS, images, fonts)
|
||||
│ ├── language/ # Frontend language files (en-GB, en-US)
|
||||
│ └── administrator/ # Backend files
|
||||
│ └── language/ # Backend language files
|
||||
├── tests/ # Test suites
|
||||
├── docs/ # Documentation
|
||||
├── scripts/ # Build scripts
|
||||
├── .github/workflows/ # CI/CD workflows
|
||||
├── Makefile # Make commands
|
||||
└── README.md # Project overview
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
### Learning the Workflow
|
||||
|
||||
1. **Read the Workflow Guide**: [docs/WORKFLOW_GUIDE.md](./WORKFLOW_GUIDE.md)
|
||||
2. **Review Joomla Development**: [docs/JOOMLA_DEVELOPMENT.md](./JOOMLA_DEVELOPMENT.md)
|
||||
|
||||
### Creating Your First Feature
|
||||
|
||||
1. **Create a version branch** via GitHub Actions:
|
||||
- Go to Actions → Create version branch
|
||||
- Enter version (e.g., 03.06.00)
|
||||
- Select branch prefix: `dev/`
|
||||
- Run workflow
|
||||
|
||||
2. **Checkout the branch**:
|
||||
```bash
|
||||
git fetch origin
|
||||
git checkout dev/03.06.00
|
||||
```
|
||||
|
||||
3. **Make changes and test**:
|
||||
```bash
|
||||
# Edit files
|
||||
vim src/index.php
|
||||
|
||||
# Validate
|
||||
make validate-required
|
||||
|
||||
# Check quality
|
||||
make quality
|
||||
```
|
||||
|
||||
4. **Commit and push**:
|
||||
```bash
|
||||
git add -A
|
||||
git commit -m "feat: your feature description"
|
||||
git push origin dev/03.06.00
|
||||
```
|
||||
|
||||
5. **Watch CI**: Check GitHub Actions for automated testing
|
||||
|
||||
### Understanding the Release Process
|
||||
|
||||
```
|
||||
Development → RC → Stable → Production
|
||||
(dev/) (rc/) (version/) (main)
|
||||
```
|
||||
|
||||
1. **dev/X.Y.Z** - Active development
|
||||
2. **rc/X.Y.Z** - Release candidate testing
|
||||
3. **version/X.Y.Z** - Stable release
|
||||
4. **main** - Production (auto-merged from version/)
|
||||
|
||||
Use the Release Pipeline workflow to promote between stages.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Scripts Not Executable
|
||||
|
||||
```bash
|
||||
make fix-permissions
|
||||
### PHPStan/PHPCS Not Found
|
||||
|
||||
```bash
|
||||
make install
|
||||
# Or manually:
|
||||
composer global require "squizlabs/php_codesniffer:^3.0" phpstan/phpstan
|
||||
```
|
||||
|
||||
### CI Workflow Fails
|
||||
|
||||
1. Check the workflow logs in GitHub Actions
|
||||
2. Run validation locally:
|
||||
```bash
|
||||
make validate-required
|
||||
make quality
|
||||
```
|
||||
|
||||
### Need Help?
|
||||
|
||||
- **Documentation**: Check [docs/](../docs/) directory
|
||||
- **Issues**: Open an issue on GitHub
|
||||
- **Contributing**: See [CONTRIBUTING.md](../CONTRIBUTING.md)
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Before Committing
|
||||
|
||||
```bash
|
||||
# Always validate first
|
||||
make validate-required
|
||||
|
||||
# Check quality for PHP changes
|
||||
make quality
|
||||
|
||||
# Run tests if you changed functionality
|
||||
make test
|
||||
```
|
||||
|
||||
### Code Style
|
||||
|
||||
- Follow PSR-12 standards
|
||||
- Use `make phpcs-fix` to auto-fix issues
|
||||
- Add SPDX license headers to new files
|
||||
- Keep functions small and focused
|
||||
|
||||
### Documentation
|
||||
|
||||
- Update docs when changing workflows
|
||||
- Add comments for complex logic
|
||||
- Update CHANGELOG.md with changes
|
||||
- Keep README.md current
|
||||
|
||||
### Version Management
|
||||
|
||||
- Use semantic versioning: Major.Minor.Patch (03.06.00)
|
||||
- Update CHANGELOG.md with all changes
|
||||
- Follow the version hierarchy: dev → rc → version → main
|
||||
- Never skip stages in the release process
|
||||
|
||||
## Useful Resources
|
||||
|
||||
- [Joomla Documentation](https://docs.joomla.org/)
|
||||
- [PSR-12 Coding Standard](https://www.php-fig.org/psr/psr-12/)
|
||||
- [Semantic Versioning](https://semver.org/)
|
||||
- [Conventional Commits](https://www.conventionalcommits.org/)
|
||||
|
||||
## Quick Reference Card
|
||||
|
||||
```bash
|
||||
# Setup
|
||||
make dev-setup # Initial setup
|
||||
|
||||
# Development
|
||||
make validate-required # Quick validation
|
||||
make quality # Code quality
|
||||
make test # Run tests
|
||||
|
||||
# Building
|
||||
make package # Create ZIP
|
||||
|
||||
# Maintenance
|
||||
make clean # Clean generated files
|
||||
make fix-permissions # Fix script permissions
|
||||
|
||||
# Help
|
||||
make help # Show all commands
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Metadata
|
||||
|
||||
* Document: docs/QUICK_START.md
|
||||
* Repository: [https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx](https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx)
|
||||
* Path: /docs/QUICK_START.md
|
||||
* Owner: Moko Consulting
|
||||
* Version: 03.06.03
|
||||
* Status: Active
|
||||
* Effective Date: 2026-01-30
|
||||
* Classification: Public Open Source Documentation
|
||||
|
||||
## Revision History
|
||||
|
||||
| Date | Change Summary | Author |
|
||||
| ---------- | ----------------------------------------------------- | --------------- |
|
||||
| 2026-01-30 | Updated metadata to MokoStandards format | GitHub Copilot |
|
||||
| 2025-01-04 | Initial quick start guide created | GitHub Copilot |
|
||||
188
docs/README.md
Normal file
188
docs/README.md
Normal file
@@ -0,0 +1,188 @@
|
||||
<!--
|
||||
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
|
||||
|
||||
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: MokoOnyx.Documentation
|
||||
REPO: https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx
|
||||
FILE: docs/README.md
|
||||
VERSION: 03.09.03
|
||||
BRIEF: Documentation index for MokoOnyx template
|
||||
PATH: /docs/README.md
|
||||
-->
|
||||
|
||||
# MokoOnyx Documentation
|
||||
|
||||
This directory contains comprehensive documentation for the MokoOnyx Joomla template.
|
||||
|
||||
## Documentation Overview
|
||||
|
||||
### Developer Documentation
|
||||
|
||||
* **[Quick Start Guide](QUICK_START.md)** - Get up and running in 5 minutes
|
||||
* Development environment setup
|
||||
* Essential commands and workflows
|
||||
* First-time contributor guide
|
||||
|
||||
* **[Workflow Guide](WORKFLOW_GUIDE.md)** - Complete workflow reference
|
||||
* Git branching strategy
|
||||
* Development workflow
|
||||
* Pull request guidelines
|
||||
|
||||
* **[Release Process](RELEASE_PROCESS.md)** ⭐ - Complete release documentation
|
||||
* Automated release workflow with GitHub Actions
|
||||
* Manual release procedures
|
||||
* Update server configuration
|
||||
* Testing and rollback procedures
|
||||
* Build scripts and tools
|
||||
|
||||
* **[Joomla Development Guide](JOOMLA_DEVELOPMENT.md)** - Joomla-specific development
|
||||
* Testing with Codeception
|
||||
* PHP quality checks (PHPStan, PHPCS)
|
||||
* Joomla extension packaging
|
||||
* Multi-version testing
|
||||
|
||||
* **[Manual Deployment Guide](MANUAL_DEPLOYMENT.md)** - Deploy src directory without building
|
||||
* Understanding src vs. installed structure
|
||||
* Manual deployment methods (copy, symlink)
|
||||
* Troubleshooting language files and media
|
||||
* Best practices for development deployments
|
||||
|
||||
* **[CSS Variables Reference](CSS_VARIABLES.md)** - Complete CSS customization guide
|
||||
* All available CSS variables
|
||||
* Custom color palette creation
|
||||
* Usage examples and tips
|
||||
* Light and dark mode theming
|
||||
|
||||
* **[Module & Component Overrides](MODULE_OVERRIDES.md)** - Mobile-responsive overrides guide
|
||||
* 16 module overrides + 12 component overrides
|
||||
* VirtueMart, Community Builder, JEM, Kunena, industry extensions
|
||||
* Mobile-first responsive design patterns
|
||||
* Accessibility features and customization
|
||||
|
||||
* **[Override Philosophy](OVERRIDE_PHILOSOPHY.md)** ⭐ - Alternative layouts, not replacements
|
||||
* Why overrides use `mobile.php` naming instead of `default.php`
|
||||
* How to activate alternative layouts in Joomla
|
||||
* Benefits of non-replacing overrides
|
||||
* Developer guidelines and best practices
|
||||
|
||||
* **[Roadmap](ROADMAP.md)** - Version-specific roadmap
|
||||
* Current features (v03.07.00)
|
||||
* Feature evolution timeline
|
||||
* Planned enhancements
|
||||
* Development priorities
|
||||
|
||||
### User Documentation
|
||||
|
||||
For end-user documentation, installation instructions, and feature guides, see the main [README.md](../README.md) in the repository root.
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
moko-cassiopeia/
|
||||
├── docs/ # Documentation (you are here)
|
||||
│ ├── README.md # This file - documentation index
|
||||
│ ├── QUICK_START.md # Quick start guide for developers
|
||||
│ ├── WORKFLOW_GUIDE.md # Development workflow guide
|
||||
│ ├── JOOMLA_DEVELOPMENT.md # Joomla-specific development guide
|
||||
│ ├── CSS_VARIABLES.md # CSS variables reference
|
||||
│ ├── MODULE_OVERRIDES.md # Module & component overrides guide
|
||||
│ └── ROADMAP.md # Version-specific roadmap
|
||||
├── src/ # Template source code (Joomla template root)
|
||||
│ ├── component.php # Component template
|
||||
│ ├── index.php # Main template file
|
||||
│ ├── offline.php # Offline template
|
||||
│ ├── error.php # Error page template
|
||||
│ ├── templateDetails.xml # Template manifest
|
||||
│ ├── html/ # Module & component overrides (16 modules, 12 components)
|
||||
│ ├── media/ # Assets (CSS, JS, images, fonts)
|
||||
│ │ ├── css/ # Stylesheets
|
||||
│ │ │ └── colors/ # Color schemes
|
||||
│ │ │ ├── light/ # Light mode color files (colors_standard.css)
|
||||
│ │ │ └── dark/ # Dark mode color files (colors_standard.css)
|
||||
│ │ ├── js/ # JavaScript files
|
||||
│ │ ├── images/ # Image assets
|
||||
│ │ └── fonts/ # Font files
|
||||
│ ├── language/ # Frontend language files
|
||||
│ │ ├── en-GB/ # English (UK) translations
|
||||
│ │ └── en-US/ # English (US) translations
|
||||
│ └── administrator/ # Backend files
|
||||
│ └── language/ # Backend language files
|
||||
│ ├── en-GB/ # English (UK) system translations
|
||||
│ └── en-US/ # English (US) system translations
|
||||
├── templates/ # Reserved for future template files
|
||||
│ └── README.md # Templates directory guide
|
||||
├── scripts/ # Build and utility scripts
|
||||
├── tests/ # Automated tests
|
||||
└── .github/ # GitHub configuration and workflows
|
||||
```
|
||||
|
||||
## Contributing
|
||||
|
||||
Before contributing, please read:
|
||||
|
||||
1. **[CONTRIBUTING.md](../CONTRIBUTING.md)** - Contribution guidelines and standards
|
||||
2. **[CODE_OF_CONDUCT.md](../CODE_OF_CONDUCT.md)** - Community standards and expectations
|
||||
3. **[SECURITY.md](../SECURITY.md)** - Security policy and reporting procedures
|
||||
|
||||
## Standards Compliance
|
||||
|
||||
This project adheres to [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/MokoStandards) for:
|
||||
|
||||
* Coding standards and formatting
|
||||
* Documentation requirements
|
||||
* Git workflow and branching
|
||||
* CI/CD pipeline configuration
|
||||
* Security scanning and dependency management
|
||||
|
||||
## Additional Resources
|
||||
|
||||
* **Repository**: [https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx](https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx)
|
||||
* **Issue Tracker**: [GitHub Issues](https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx/issues)
|
||||
* **Changelog**: [CHANGELOG.md](../CHANGELOG.md)
|
||||
* **License**: [GPL-3.0-or-later](../LICENSE)
|
||||
|
||||
## Support
|
||||
|
||||
* **Email**: hello@mokoconsulting.tech
|
||||
* **Website**: https://mokoconsulting.tech/support/joomla-cms/moko-cassiopeia-roadmap
|
||||
|
||||
---
|
||||
|
||||
## Metadata
|
||||
|
||||
* Document: docs/README.md
|
||||
* Repository: [https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx](https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx)
|
||||
* Path: /docs/README.md
|
||||
* Owner: Moko Consulting
|
||||
* Version: 03.07.00
|
||||
* Status: Active
|
||||
* Effective Date: 2026-01-30
|
||||
* Classification: Public Open Source Documentation
|
||||
|
||||
## Revision History
|
||||
|
||||
| Date | Change Summary | Author |
|
||||
| ---------- | ----------------------------------------------------- | --------------- |
|
||||
| 2026-02-22 | Added MODULE_OVERRIDES.md reference, updated version to 03.07.00 | GitHub Copilot |
|
||||
| 2026-01-30 | Added CSS Variables reference, updated version to 03.06.03 | GitHub Copilot |
|
||||
| 2026-01-09 | Initial documentation index created for MokoStandards compliance. | GitHub Copilot |
|
||||
| 2026-01-27 | Updated with roadmap link and version to 03.05.01. | GitHub Copilot |
|
||||
638
docs/RELEASE_PROCESS.md
Normal file
638
docs/RELEASE_PROCESS.md
Normal file
@@ -0,0 +1,638 @@
|
||||
<!--
|
||||
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
|
||||
|
||||
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: MokoOnyx.Documentation
|
||||
REPO: https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx
|
||||
FILE: docs/RELEASE_PROCESS.md
|
||||
VERSION: 03.09.03
|
||||
BRIEF: Complete release process documentation for MokoOnyx
|
||||
PATH: /docs/RELEASE_PROCESS.md
|
||||
-->
|
||||
|
||||
# Release Process — MokoOnyx
|
||||
|
||||
This document describes the complete release process for MokoOnyx Joomla template, including automated workflows and manual procedures.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Overview](#overview)
|
||||
2. [Release Types](#release-types)
|
||||
3. [Automated Release Process](#automated-release-process)
|
||||
4. [Manual Release Process](#manual-release-process)
|
||||
5. [Update Server Configuration](#update-server-configuration)
|
||||
6. [Testing Releases](#testing-releases)
|
||||
7. [Rollback Procedures](#rollback-procedures)
|
||||
8. [Troubleshooting](#troubleshooting)
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
MokoOnyx uses an automated release system powered by GitHub Actions. The system:
|
||||
|
||||
- **Builds** installation packages automatically
|
||||
- **Generates** checksums for security verification
|
||||
- **Creates** GitHub Releases with downloadable artifacts
|
||||
- **Updates** the Joomla update server (`updates.xml`) automatically
|
||||
- **Validates** package integrity with SHA-256 hashes
|
||||
|
||||
### Key Components
|
||||
|
||||
1. **Release Workflow** (`.github/workflows/release.yml`): Builds and publishes releases
|
||||
2. **Auto-Update SHA** (`.github/workflows/auto-update-sha.yml`): Updates `updates.xml` after release
|
||||
3. **Build Script** (`scripts/build-release.sh`): Local development builds
|
||||
4. **Update Server** (`updates.xml`): Joomla update server manifest
|
||||
|
||||
---
|
||||
|
||||
## Release Types
|
||||
|
||||
### Patch Release (Third Digit)
|
||||
|
||||
**Format**: `XX.XX.XX` → `XX.XX.XX+1` (e.g., `03.08.03` → `03.08.04`)
|
||||
|
||||
**When to use**:
|
||||
- Bug fixes
|
||||
- Security patches
|
||||
- Documentation updates
|
||||
- Minor CSS/styling tweaks
|
||||
- No breaking changes
|
||||
|
||||
**Example**: `03.08.03` → `03.08.04`
|
||||
|
||||
### Minor Release (Second Digit)
|
||||
|
||||
**Format**: `XX.XX.00` → `XX.XX+1.00` (e.g., `03.08.03` → `03.09.00`)
|
||||
|
||||
**When to use**:
|
||||
- New features
|
||||
- New module/component overrides
|
||||
- Significant styling changes
|
||||
- Backward-compatible changes
|
||||
|
||||
**Example**: `03.08.03` → `03.09.00`
|
||||
|
||||
### Major Release (First Digit)
|
||||
|
||||
**Format**: `XX.00.00` → `XX+1.00.00` (e.g., `03.08.03` → `04.00.00`)
|
||||
|
||||
**When to use**:
|
||||
- Breaking changes
|
||||
- Major architecture changes
|
||||
- Joomla version upgrades
|
||||
- Complete redesigns
|
||||
|
||||
**Example**: `03.08.03` → `04.00.00`
|
||||
|
||||
---
|
||||
|
||||
## Automated Release Process
|
||||
|
||||
**Recommended for most releases**
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- [ ] All changes merged to `main` branch
|
||||
- [ ] Tests passing
|
||||
- [ ] Documentation updated
|
||||
- [ ] CHANGELOG.md updated
|
||||
- [ ] Local testing completed
|
||||
|
||||
### Step 1: Prepare Release Branch
|
||||
|
||||
```bash
|
||||
# Create release branch
|
||||
git checkout main
|
||||
git pull
|
||||
git checkout -b release/03.08.04
|
||||
|
||||
# Update version in templateDetails.xml
|
||||
# Edit: src/templateDetails.xml
|
||||
# Change: <version>03.08.03</version>
|
||||
# To: <version>03.08.04</version>
|
||||
|
||||
# Update CHANGELOG.md
|
||||
# Add new section:
|
||||
## [03.08.04] - 2026-02-27
|
||||
|
||||
### Added
|
||||
- Feature descriptions
|
||||
|
||||
### Fixed
|
||||
- Bug fix descriptions
|
||||
|
||||
### Changed
|
||||
- Change descriptions
|
||||
|
||||
# Commit changes
|
||||
git add src/templateDetails.xml CHANGELOG.md
|
||||
git commit -m "chore: Prepare release 03.08.04"
|
||||
git push origin release/03.08.04
|
||||
```
|
||||
|
||||
### Step 2: Create Pull Request
|
||||
|
||||
1. Go to GitHub repository
|
||||
2. Click "Pull requests" → "New pull request"
|
||||
3. Base: `main`, Compare: `release/03.08.04`
|
||||
4. Title: `Release 03.08.04`
|
||||
5. Description: Copy relevant CHANGELOG entries
|
||||
6. Create pull request
|
||||
7. Review and merge
|
||||
|
||||
### Step 3: Create and Push Tag
|
||||
|
||||
```bash
|
||||
# Switch to main and pull changes
|
||||
git checkout main
|
||||
git pull
|
||||
|
||||
# Create tag
|
||||
git tag 03.08.04
|
||||
|
||||
# Push tag (triggers release workflow)
|
||||
git push origin 03.08.04
|
||||
```
|
||||
|
||||
### Step 4: Monitor Automated Process
|
||||
|
||||
1. **Go to GitHub Actions tab**
|
||||
2. **Watch "Create Release" workflow**:
|
||||
- Builds package
|
||||
- Generates checksums
|
||||
- Creates GitHub Release
|
||||
- Uploads artifacts
|
||||
|
||||
3. **Watch "Auto-Update SHA Hash" workflow**:
|
||||
- Downloads release package
|
||||
- Calculates SHA-256 hash
|
||||
- Updates `updates.xml`
|
||||
- Commits to main branch
|
||||
|
||||
### Step 5: Verify Release
|
||||
|
||||
1. **Check GitHub Release**:
|
||||
- Go to Releases tab
|
||||
- Verify release `03.08.04` exists
|
||||
- Download ZIP package
|
||||
- Verify checksums match
|
||||
|
||||
2. **Check updates.xml**:
|
||||
```bash
|
||||
git pull
|
||||
cat updates.xml
|
||||
```
|
||||
- Verify version is `03.08.04`
|
||||
- Verify download URL is correct
|
||||
- Verify SHA-256 hash is present
|
||||
|
||||
3. **Test Joomla Update**:
|
||||
- Install previous version in Joomla
|
||||
- Go to Extensions → Update
|
||||
- Verify update is detected
|
||||
- Perform update
|
||||
- Verify template works correctly
|
||||
|
||||
---
|
||||
|
||||
## Manual Release Process
|
||||
|
||||
**Use when automation fails or for local testing**
|
||||
|
||||
### Step 1: Prepare Repository
|
||||
|
||||
```bash
|
||||
# Update version numbers
|
||||
# Edit: src/templateDetails.xml
|
||||
# Edit: CHANGELOG.md
|
||||
|
||||
# Commit changes
|
||||
git add src/templateDetails.xml CHANGELOG.md
|
||||
git commit -m "chore: Prepare release 03.08.04"
|
||||
git push
|
||||
```
|
||||
|
||||
### Step 2: Build Package Locally
|
||||
|
||||
```bash
|
||||
# Run build script
|
||||
./scripts/build-release.sh 03.08.04
|
||||
|
||||
# Output will be in build/ directory:
|
||||
# - mokoonyx-src-03.08.04.zip
|
||||
# - mokoonyx-src-03.08.04.zip.sha256
|
||||
# - mokoonyx-src-03.08.04.zip.md5
|
||||
```
|
||||
|
||||
### Step 3: Test Package
|
||||
|
||||
```bash
|
||||
# Install in Joomla test environment
|
||||
# Extensions → Manage → Install → Upload Package File
|
||||
# Select: build/mokoonyx-src-03.08.04.zip
|
||||
|
||||
# Test all features:
|
||||
# - Template displays correctly
|
||||
# - Module overrides work
|
||||
# - Alternative layouts selectable
|
||||
# - Dark mode works
|
||||
# - No JavaScript errors
|
||||
```
|
||||
|
||||
### Step 4: Create GitHub Release
|
||||
|
||||
1. **Go to GitHub Releases**
|
||||
2. **Click "Create a new release"**
|
||||
3. **Tag**: `03.08.04` (create new tag)
|
||||
4. **Release title**: `Release 03.08.04`
|
||||
5. **Description**: Copy from CHANGELOG.md
|
||||
6. **Upload files**:
|
||||
- `mokoonyx-src-03.08.04.zip`
|
||||
- `mokoonyx-src-03.08.04.zip.sha256`
|
||||
- `mokoonyx-src-03.08.04.zip.md5`
|
||||
7. **Publish release**
|
||||
|
||||
### Step 5: Update updates.xml Manually
|
||||
|
||||
```bash
|
||||
# Extract SHA-256 hash
|
||||
cat build/mokoonyx-src-03.08.04.zip.sha256
|
||||
# Example output: a1b2c3d4e5f6...
|
||||
|
||||
# Edit updates.xml
|
||||
# Update <version>03.08.04</version>
|
||||
# Update <creationDate>2026-02-27</creationDate>
|
||||
# Update <downloadurl>https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx/releases/download/03.08.04/mokoonyx-src-03.08.04.zip</downloadurl>
|
||||
# Update <sha256>sha256:a1b2c3d4e5f6...</sha256>
|
||||
|
||||
# Commit and push
|
||||
git add updates.xml
|
||||
git commit -m "chore: Update updates.xml for release 03.08.04"
|
||||
git push
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Update Server Configuration
|
||||
|
||||
### updates.xml Structure
|
||||
|
||||
```xml
|
||||
<updates>
|
||||
<update>
|
||||
<name>MokoOnyx</name>
|
||||
<description>Moko Consulting's site template based on Cassiopeia.</description>
|
||||
<element>mokoonyx</element>
|
||||
<type>template</type>
|
||||
<client>site</client>
|
||||
|
||||
<version>03.08.04</version>
|
||||
<creationDate>2026-02-27</creationDate>
|
||||
<author>Jonathan Miller || Moko Consulting</author>
|
||||
<authorEmail>hello@mokoconsulting.tech</authorEmail>
|
||||
<copyright>(C)GNU General Public License Version 3 - 2026 Moko Consulting</copyright>
|
||||
|
||||
<infourl title='MokoOnyx'>https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx</infourl>
|
||||
|
||||
<downloads>
|
||||
<downloadurl type='full' format='zip'>https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx/releases/download/03.08.04/mokoonyx-src-03.08.04.zip</downloadurl>
|
||||
<sha256>sha256:a1b2c3d4e5f6...</sha256>
|
||||
</downloads>
|
||||
|
||||
<tags>
|
||||
<tag>stable</tag>
|
||||
</tags>
|
||||
|
||||
<maintainer>Moko Consulting</maintainer>
|
||||
<maintainerurl>https://www.mokoconsulting.tech</maintainerurl>
|
||||
|
||||
<targetplatform name='joomla' version='5.*'/>
|
||||
</update>
|
||||
</updates>
|
||||
```
|
||||
|
||||
### Hosting Update Server
|
||||
|
||||
The `updates.xml` file is hosted directly on GitHub:
|
||||
|
||||
**URL**: `https://raw.githubusercontent.com/mokoconsulting-tech/MokoOnyx/main/updates.xml`
|
||||
|
||||
This URL is configured in `src/templateDetails.xml`:
|
||||
|
||||
```xml
|
||||
<updateservers>
|
||||
<server type="extension" name="MokoOnyx Updates" priority="1">
|
||||
https://raw.githubusercontent.com/mokoconsulting-tech/MokoOnyx/main/updates.xml
|
||||
</server>
|
||||
</updateservers>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Testing Releases
|
||||
|
||||
### Pre-Release Testing
|
||||
|
||||
```bash
|
||||
# 1. Build package locally
|
||||
./scripts/build-release.sh
|
||||
|
||||
# 2. Set up Joomla test environment
|
||||
# - Clean Joomla 5.x installation
|
||||
# - Previous MokoOnyx version installed
|
||||
|
||||
# 3. Test current version features
|
||||
# - All module overrides
|
||||
# - Alternative layouts
|
||||
# - Dark mode toggle
|
||||
# - Responsive behavior
|
||||
|
||||
# 4. Install new package
|
||||
# Extensions → Manage → Install → Upload Package
|
||||
|
||||
# 5. Verify upgrade process
|
||||
# - No errors during installation
|
||||
# - Settings preserved
|
||||
# - Custom modifications retained
|
||||
|
||||
# 6. Test new features
|
||||
# - New functionality works
|
||||
# - Bug fixes applied
|
||||
# - No regressions
|
||||
```
|
||||
|
||||
### Update Server Testing
|
||||
|
||||
```bash
|
||||
# 1. Install previous version in Joomla
|
||||
# 2. Go to: Extensions → Update
|
||||
# 3. Click "Find Updates"
|
||||
# 4. Verify update shows: "MokoOnyx 03.08.04"
|
||||
# 5. Click "Update"
|
||||
# 6. Verify successful update
|
||||
# 7. Test template functionality
|
||||
```
|
||||
|
||||
### Checklist
|
||||
|
||||
- [ ] Package installs without errors
|
||||
- [ ] Template activates correctly
|
||||
- [ ] All module overrides work
|
||||
- [ ] Alternative layouts selectable
|
||||
- [ ] Dark mode functions
|
||||
- [ ] Responsive on mobile/tablet/desktop
|
||||
- [ ] No JavaScript console errors
|
||||
- [ ] No PHP errors in Joomla logs
|
||||
- [ ] Update server detects new version
|
||||
- [ ] Update process completes successfully
|
||||
|
||||
---
|
||||
|
||||
## Rollback Procedures
|
||||
|
||||
### Rollback Release
|
||||
|
||||
If a release has critical issues:
|
||||
|
||||
1. **Delete GitHub Release**:
|
||||
- Go to Releases
|
||||
- Click release to delete
|
||||
- Click "Delete"
|
||||
- Confirm deletion
|
||||
|
||||
2. **Delete Git Tag**:
|
||||
```bash
|
||||
# Delete local tag
|
||||
git tag -d 03.08.04
|
||||
|
||||
# Delete remote tag
|
||||
git push --delete origin 03.08.04
|
||||
```
|
||||
|
||||
3. **Revert updates.xml**:
|
||||
```bash
|
||||
# Revert to previous version
|
||||
git revert <commit-hash-of-auto-update>
|
||||
git push
|
||||
```
|
||||
|
||||
4. **Notify Users**:
|
||||
- Create GitHub issue explaining the problem
|
||||
- Pin the issue
|
||||
- Provide rollback instructions for users
|
||||
|
||||
### User Rollback Instructions
|
||||
|
||||
For users who installed the problematic version:
|
||||
|
||||
1. **Download previous version** from GitHub Releases
|
||||
2. **Uninstall current version**:
|
||||
- Extensions → Manage → Manage
|
||||
- Find MokoOnyx
|
||||
- Click "Uninstall"
|
||||
3. **Install previous version**:
|
||||
- Extensions → Manage → Install
|
||||
- Upload previous version ZIP
|
||||
4. **Verify functionality**
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Release Workflow Fails
|
||||
|
||||
**Problem**: Build fails with "rsync: command not found"
|
||||
|
||||
**Solution**: The GitHub Actions runner always has rsync installed. If this occurs, check the workflow file syntax.
|
||||
|
||||
**Problem**: ZIP creation fails
|
||||
|
||||
**Solution**: Check that `src/` and `src/media/` directories exist and contain files.
|
||||
|
||||
**Problem**: Version update fails
|
||||
|
||||
**Solution**: Verify `sed` commands in workflow match actual XML structure.
|
||||
|
||||
### Auto-Update SHA Fails
|
||||
|
||||
**Problem**: Cannot download release package
|
||||
|
||||
**Solution**:
|
||||
- Verify release was published (not draft)
|
||||
- Check package naming: `mokoonyx-src-{version}.zip`
|
||||
- Verify release tag format
|
||||
|
||||
**Problem**: SHA-256 hash mismatch
|
||||
|
||||
**Solution**:
|
||||
- Package may have been modified after calculation
|
||||
- Re-run the workflow manually
|
||||
- Verify package integrity
|
||||
|
||||
**Problem**: Commit fails
|
||||
|
||||
**Solution**:
|
||||
- Check workflow has write permissions
|
||||
- Verify no branch protection rules blocking bot commits
|
||||
|
||||
### Manual Build Issues
|
||||
|
||||
**Problem**: `./scripts/build-release.sh: Permission denied`
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
chmod +x scripts/build-release.sh
|
||||
./scripts/build-release.sh
|
||||
```
|
||||
|
||||
**Problem**: Build directory exists
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
rm -rf build/
|
||||
./scripts/build-release.sh
|
||||
```
|
||||
|
||||
### Update Server Issues
|
||||
|
||||
**Problem**: Joomla doesn't detect update
|
||||
|
||||
**Solution**:
|
||||
1. Check `updates.xml` is accessible:
|
||||
```bash
|
||||
curl https://raw.githubusercontent.com/mokoconsulting-tech/MokoOnyx/main/updates.xml
|
||||
```
|
||||
2. Verify version number is higher than installed version
|
||||
3. Clear Joomla cache: System → Clear Cache
|
||||
4. Check update URL in templateDetails.xml
|
||||
|
||||
**Problem**: Update fails with "Invalid package"
|
||||
|
||||
**Solution**:
|
||||
- Verify SHA-256 hash matches
|
||||
- Re-download package and check integrity
|
||||
- Verify package structure is correct
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Version Numbering
|
||||
|
||||
- **Always increment** version numbers sequentially
|
||||
- **Never reuse** version numbers
|
||||
- **Use consistent** format: `XX.XX.XX`
|
||||
|
||||
### Changelog
|
||||
|
||||
- **Update before** release
|
||||
- **Include all changes** since last version
|
||||
- **Categorize** changes: Added, Changed, Fixed, Removed
|
||||
- **Write clear descriptions** for users
|
||||
|
||||
### Testing
|
||||
|
||||
- **Test locally** before pushing tag
|
||||
- **Test update process** from previous version
|
||||
- **Test on clean** Joomla installation
|
||||
- **Test different** configurations
|
||||
|
||||
### Communication
|
||||
|
||||
- **Announce releases** on GitHub Discussions
|
||||
- **Document breaking changes** clearly
|
||||
- **Provide migration guides** for major changes
|
||||
- **Respond promptly** to issue reports
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Automated Release Commands
|
||||
|
||||
```bash
|
||||
# 1. Create release branch
|
||||
git checkout -b release/03.08.04
|
||||
|
||||
# 2. Update version and CHANGELOG
|
||||
# (edit files)
|
||||
|
||||
# 3. Commit and push
|
||||
git add .
|
||||
git commit -m "chore: Prepare release 03.08.04"
|
||||
git push origin release/03.08.04
|
||||
|
||||
# 4. Create and merge PR (via GitHub UI)
|
||||
|
||||
# 5. Create and push tag
|
||||
git checkout main
|
||||
git pull
|
||||
git tag 03.08.04
|
||||
git push origin 03.08.04
|
||||
|
||||
# 6. Wait for automation to complete
|
||||
```
|
||||
|
||||
### Manual Release Commands
|
||||
|
||||
```bash
|
||||
# Build locally
|
||||
./scripts/build-release.sh 03.08.04
|
||||
|
||||
# Test installation
|
||||
# (manual Joomla testing)
|
||||
|
||||
# Create release on GitHub
|
||||
# (via GitHub UI)
|
||||
|
||||
# Update updates.xml
|
||||
# (edit file with SHA-256)
|
||||
git add updates.xml
|
||||
git commit -m "chore: Update updates.xml for 03.08.04"
|
||||
git push
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- **Build Scripts**: [scripts/README.md](../scripts/README.md)
|
||||
- **Workflow Guide**: [WORKFLOW_GUIDE.md](WORKFLOW_GUIDE.md)
|
||||
- **Contributing**: [CONTRIBUTING.md](../CONTRIBUTING.md)
|
||||
- **Changelog**: [CHANGELOG.md](../CHANGELOG.md)
|
||||
|
||||
---
|
||||
|
||||
## Support
|
||||
|
||||
- **Issues**: [GitHub Issues](https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx/issues)
|
||||
- **Discussions**: [GitHub Discussions](https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx/discussions)
|
||||
- **Email**: hello@mokoconsulting.tech
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
Copyright (C) 2026 Moko Consulting
|
||||
|
||||
This documentation is licensed under GPL-3.0-or-later.
|
||||
917
docs/ROADMAP.md
Normal file
917
docs/ROADMAP.md
Normal file
@@ -0,0 +1,917 @@
|
||||
<!--
|
||||
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
|
||||
|
||||
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: MokoOnyx.Documentation
|
||||
REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-cassiopeia
|
||||
FILE: docs/ROADMAP.md
|
||||
VERSION: 03.09.03
|
||||
BRIEF: Version-specific roadmap for MokoOnyx template
|
||||
PATH: /docs/ROADMAP.md
|
||||
-->
|
||||
|
||||
# MokoOnyx Roadmap (VERSION: 03.09.03)
|
||||
|
||||
This document provides a comprehensive, version-specific roadmap for the MokoOnyx Joomla template, tracking feature evolution, current capabilities, and planned enhancements.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Version Timeline](#version-timeline)
|
||||
- [Past Releases](#past-releases)
|
||||
- [Future Roadmap (5-Year Plan)](#future-roadmap-5-year-plan)
|
||||
- [Current Release (v03.06.03)](#current-release-v030603)
|
||||
- [Implemented Features](#implemented-features)
|
||||
- [Planned Features](#planned-features)
|
||||
- [Development Priorities](#development-priorities)
|
||||
- [Long-term Vision](#long-term-vision)
|
||||
- [External Resources](#external-resources)
|
||||
|
||||
---
|
||||
|
||||
## Version Timeline
|
||||
|
||||
### Past Releases
|
||||
|
||||
### v03.05.01 (2026-01-09) - Standards & Security
|
||||
**Status**: Released (CHANGELOG entry exists, code files pending version update)
|
||||
|
||||
**Added**:
|
||||
- Dependency review workflow for vulnerability scanning
|
||||
- Standards compliance workflow for MokoStandards validation
|
||||
- Dependabot configuration for automated security updates
|
||||
- Documentation index (`docs/README.md`)
|
||||
|
||||
**Changed**:
|
||||
- Removed custom CodeQL workflow (using GitHub's default setup)
|
||||
- Enforced repository compliance with MokoStandards
|
||||
- Improved security posture with automated scanning
|
||||
|
||||
### v03.06.00 (2026-01-28) - Version Update
|
||||
**Status**: Current Release (in code)
|
||||
|
||||
**Changed**:
|
||||
- Updated version to 03.06.00 across all files
|
||||
|
||||
### v03.05.00 (2026-01-04) - Workflow & Governance
|
||||
**Status**: Mentioned in CHANGELOG (v03.05.00)
|
||||
|
||||
**Added**:
|
||||
- `.github/workflows` directory structure
|
||||
- CODE_OF_CONDUCT.md from MokoStandards
|
||||
- CONTRIBUTING.md from MokoStandards
|
||||
|
||||
**Changed**:
|
||||
- TODO items to be split to separate file (tracked)
|
||||
|
||||
### v03.01.00 (2025-12-16) - CI/CD Foundation
|
||||
**Added**:
|
||||
- Initial GitHub Actions workflows
|
||||
|
||||
### v03.00.00 (2025-12-09) - Font Awesome 7 Upgrade
|
||||
**Updated**:
|
||||
- Copyright headers to MokoCodingDefaults standards
|
||||
- Fixed color style injection in `index.php`
|
||||
- Upgraded Font Awesome 6 to Font Awesome 7 Free
|
||||
- Added Font Awesome 7 Free style fallback
|
||||
|
||||
**Removed**:
|
||||
- Deprecated CODE_OF_CONDUCT.md
|
||||
- Deprecated CONTRIBUTING.md
|
||||
|
||||
### v02.01.05 (2025-09-04) - CSS Refinement
|
||||
**Fixed**:
|
||||
- Removed vmbasic.css
|
||||
- Repaired template.css and colors_standard.css
|
||||
|
||||
### v02.00.00 (2025-08-30) - Dark Mode & TOC
|
||||
**Major Features**:
|
||||
- **Dark Mode Toggle System**
|
||||
- Frontend toggle switch with localStorage persistence
|
||||
- Admin-configurable default mode
|
||||
- CSS rules for light/dark themes
|
||||
- JavaScript-powered mode switching
|
||||
|
||||
- **Enhanced Template Parameters**
|
||||
- Logo parameter support
|
||||
- GTM container ID configuration
|
||||
- Dark mode defaults in settings
|
||||
- Updated metadata and copyright headers
|
||||
|
||||
- **Expanded Table of Contents**
|
||||
- Automatic TOC injection
|
||||
- User-selectable placement (`toc-left` or `toc-right`)
|
||||
- Article options integration
|
||||
|
||||
**Improvements**:
|
||||
- Cleaned up `index.php` (removed duplicate skip-to-content calls)
|
||||
- Consolidated JavaScript asset loading
|
||||
- Streamlined CSS for toggle switch
|
||||
- Accessibility refinements (typography, color contrast)
|
||||
- Fixed missing logo parameter in header
|
||||
- Corrected stylesheet inconsistencies
|
||||
- Patched redundant script includes
|
||||
|
||||
### v01.00.00 - Initial Public Release
|
||||
**Core Features**:
|
||||
- Font Awesome 6 integration
|
||||
- Bootstrap 5 helpers and utilities
|
||||
- Automatic Table of Contents (TOC) utility
|
||||
- Moko Expansions: Google Tag Manager / GA4 hooks
|
||||
- Built on Joomla's Cassiopeia template
|
||||
|
||||
---
|
||||
|
||||
### Future Roadmap (5-Year Plan)
|
||||
|
||||
The following versions represent our planned annual major releases, each building upon the previous version's foundation.
|
||||
|
||||
#### v04.00.00 (Q4 2027) - Enhanced Accessibility & Performance
|
||||
**Status**: Planned
|
||||
**Target Release**: December 2027
|
||||
|
||||
**Major Template Features**:
|
||||
- **WCAG 2.1 AA Compliance**
|
||||
- Full accessibility audit and remediation
|
||||
- High-contrast theme options
|
||||
- Screen reader optimizations
|
||||
- Keyboard navigation enhancements
|
||||
- ARIA landmark improvements
|
||||
- Skip navigation enhancements
|
||||
|
||||
- **Template Performance Optimizations**
|
||||
- Critical CSS inlining for faster first paint
|
||||
- Lazy loading for images and below-fold content
|
||||
- WebP image support with automatic fallbacks
|
||||
- Advanced asset bundling and minification
|
||||
- Template asset caching (CSS/JS bundles)
|
||||
|
||||
- **Enhanced Layout System**
|
||||
- Additional responsive grid layouts
|
||||
- Flexible module position system
|
||||
- Column layout presets (2-col, 3-col, 4-col variations)
|
||||
- Grid/masonry article layouts
|
||||
- Sticky sidebar options
|
||||
|
||||
- **Typography Enhancements**
|
||||
- Advanced typography controls in template settings
|
||||
- Additional font pairing presets
|
||||
- Custom font upload support
|
||||
- Line height and letter spacing controls
|
||||
- Responsive typography scaling
|
||||
|
||||
- **Developer Experience**
|
||||
- Development mode enablement (unminified assets, debug output)
|
||||
- Live reload during development
|
||||
- Enhanced error logging and diagnostics
|
||||
- Template debugging tools
|
||||
- Style guide generator
|
||||
|
||||
- **Content Display Features**
|
||||
- Soft offline mode (category-based access during maintenance)
|
||||
- Enhanced article layouts (grid, masonry, timeline)
|
||||
- Image caption styling options
|
||||
- Quote block styling variations
|
||||
- Enhanced breadcrumb customization
|
||||
|
||||
**Template Infrastructure**:
|
||||
- Expanded template parameter validation
|
||||
- Enhanced template override detection
|
||||
- Automated template compatibility testing
|
||||
- Template performance profiling tools
|
||||
|
||||
---
|
||||
|
||||
#### v05.00.00 (Q4 2028) - Advanced Layouts & Template Customization
|
||||
**Status**: Planned
|
||||
**Target Release**: December 2028
|
||||
|
||||
**Major Template Features**:
|
||||
- **Enhanced Layout Builder**
|
||||
- Template-based page layout variations
|
||||
- Configurable layout options via template parameters
|
||||
- Layout presets library (blog, portfolio, business, magazine)
|
||||
- Module position layout manager
|
||||
- Visual layout preview in admin
|
||||
|
||||
- **Advanced Styling System**
|
||||
- Extended color palette management (unlimited custom palettes)
|
||||
- CSS variable editor in template settings
|
||||
- Style presets for different site types
|
||||
- Border radius and spacing controls
|
||||
- Box shadow and effect controls
|
||||
|
||||
- **Template Component Enhancements**
|
||||
- Enhanced menu styling options (mega menu support)
|
||||
- Advanced header variations (transparent, sticky, minimal)
|
||||
- Footer layout options (column variations, widgets)
|
||||
- Sidebar styling and behavior options
|
||||
- Hero section templates and variations
|
||||
|
||||
- **Content Display Options**
|
||||
- Article intro/full text display controls
|
||||
- Category layout variations (grid, list, masonry, cards)
|
||||
- Featured content sections
|
||||
- Related articles display options
|
||||
- Author bio box styling
|
||||
|
||||
- **Responsive Design Improvements**
|
||||
- Mobile-first navigation patterns
|
||||
- Tablet-specific layout controls
|
||||
- Responsive image sizing options
|
||||
- Mobile header variations
|
||||
- Touch-friendly interface elements
|
||||
|
||||
- **Template Integration Features**
|
||||
- Enhanced VirtueMart template overrides
|
||||
- Contact form styling variations
|
||||
- Search result layout options
|
||||
- Error page customization
|
||||
- Archive page templates
|
||||
|
||||
**Template Infrastructure**:
|
||||
- Joomla 6.x template compatibility (if released)
|
||||
- PHP 8.2+ support
|
||||
- Template child theme support
|
||||
- Template preset import/export functionality
|
||||
|
||||
---
|
||||
|
||||
#### v06.00.00 (Q4 2029) - Template Extensions & Advanced Features
|
||||
**Status**: Planned
|
||||
**Target Release**: December 2029
|
||||
|
||||
**Major Template Features**:
|
||||
- **Template Marketplace & Extensions**
|
||||
- Template addon system for modular features
|
||||
- Community-contributed template extensions
|
||||
- Template preset marketplace
|
||||
- Style pack distribution system
|
||||
- Template component library
|
||||
|
||||
- **Advanced Module System**
|
||||
- Custom module chrome options
|
||||
- Module animation effects
|
||||
- Module visibility controls (scroll, time-based)
|
||||
- Module group management
|
||||
- Module style inheritance
|
||||
|
||||
- **Enhanced Media Handling**
|
||||
- Background image options per page/section
|
||||
- Image overlay controls
|
||||
- Parallax scrolling effects
|
||||
- Video background support
|
||||
- Gallery template variations
|
||||
|
||||
- **Template Branding Options**
|
||||
- Multiple logo upload (standard, retina, mobile)
|
||||
- Favicon and app icon management
|
||||
- Custom loading screen/animations
|
||||
- Watermark options
|
||||
- Brand color scheme generator
|
||||
|
||||
- **Advanced Header/Footer**
|
||||
- Multiple header layout presets
|
||||
- Sticky header variations and behaviors
|
||||
- Header transparency controls
|
||||
- Footer widget areas expansion
|
||||
- Floating action buttons
|
||||
|
||||
- **Content Enhancement Features**
|
||||
- Reading progress indicator
|
||||
- Social sharing buttons (template-integrated)
|
||||
- Print-friendly styles
|
||||
- Reading time estimation display
|
||||
- Content table enhancements
|
||||
|
||||
- **Template SEO Features**
|
||||
- Schema markup templates for common types
|
||||
- Open Graph tag management
|
||||
- Twitter Card support
|
||||
- Breadcrumb schema integration
|
||||
- Meta tag template controls
|
||||
|
||||
**Template Infrastructure**:
|
||||
- Template versioning system
|
||||
- Template backup/restore functionality
|
||||
- Template A/B testing support
|
||||
- Multi-language template variations
|
||||
- Template documentation generator
|
||||
|
||||
---
|
||||
|
||||
#### v07.00.00 (Q4 2030) - Modern Template Standards & Enhancements
|
||||
**Status**: Planned
|
||||
**Target Release**: December 2030
|
||||
|
||||
**Major Template Features**:
|
||||
- **Modern CSS Features**
|
||||
- CSS Grid layout system integration
|
||||
- CSS Container Queries support
|
||||
- CSS Cascade Layers implementation (layered style priority system)
|
||||
- Custom properties (CSS variables) UI
|
||||
- Modern filter and backdrop effects
|
||||
|
||||
- **Progressive Template Features**
|
||||
- Offline-capable template assets
|
||||
- Service worker template integration
|
||||
- App manifest generation
|
||||
- Install to home screen support
|
||||
- Template asset preloading strategies
|
||||
|
||||
- **Animation & Interaction**
|
||||
- Scroll-triggered animations
|
||||
- Hover effect library
|
||||
- Page transition effects
|
||||
- Micro-interactions for UI elements
|
||||
- Loading animation options
|
||||
|
||||
- **Advanced Responsive Features**
|
||||
- Container-based responsive design
|
||||
- Element visibility by viewport
|
||||
- Responsive navigation patterns library
|
||||
- Mobile-optimized interactions
|
||||
- Adaptive image loading
|
||||
|
||||
- **Template Accessibility Features**
|
||||
- Focus indicators customization
|
||||
- Reduced motion preferences support
|
||||
- High contrast mode automation
|
||||
- Keyboard navigation patterns
|
||||
- ARIA live regions for dynamic content
|
||||
|
||||
- **Content Presentation**
|
||||
- Advanced blockquote styles
|
||||
- Code snippet highlighting themes
|
||||
- Table styling variations
|
||||
- List styling options
|
||||
- Custom content block templates
|
||||
|
||||
- **Template Performance**
|
||||
- Resource hints (preconnect, prefetch)
|
||||
- Optimal asset delivery strategies
|
||||
- Image format optimization (AVIF support)
|
||||
- Font loading optimization
|
||||
- Template metrics dashboard
|
||||
|
||||
**Template Infrastructure**:
|
||||
- Template pattern library
|
||||
- Design token system
|
||||
- Template component documentation
|
||||
- Automated template testing suite
|
||||
- Template performance monitoring
|
||||
|
||||
---
|
||||
|
||||
#### v08.00.00 (Q4 2031) - Next-Generation Template Features
|
||||
**Status**: Conceptual
|
||||
**Target Release**: December 2031
|
||||
|
||||
**Major Template Features**:
|
||||
- **Advanced Layout Systems**
|
||||
- Subgrid support for complex layouts
|
||||
- Multi-column layout variations
|
||||
- Asymmetric grid systems
|
||||
- Dynamic layout switching
|
||||
- Layout constraint system
|
||||
|
||||
- **Enhanced Visual Customization**
|
||||
- Real-time style editor
|
||||
- Template style variations manager
|
||||
- Custom CSS injection with validation
|
||||
- Style inheritance and override system
|
||||
- Visual design tokens editor
|
||||
|
||||
- **Template Component Library**
|
||||
- Comprehensive UI component set
|
||||
- Reusable template blocks
|
||||
- Component variation system
|
||||
- Template snippet library
|
||||
- Pattern library integration
|
||||
|
||||
- **Advanced Typography System**
|
||||
- Variable font support
|
||||
- Advanced typographic scales
|
||||
- Font pairing recommendations
|
||||
- Fluid typography system
|
||||
- Custom font fallback chains
|
||||
|
||||
- **Template Integration Features**
|
||||
- Enhanced component overrides
|
||||
- Template hooks system
|
||||
- Event-based template modifications
|
||||
- Custom field rendering templates
|
||||
- Module position API enhancements
|
||||
|
||||
- **Responsive & Adaptive Design**
|
||||
- Advanced breakpoint management
|
||||
- Element-specific responsive controls
|
||||
- Adaptive images with art direction
|
||||
- Responsive typography system
|
||||
- Context-aware component rendering
|
||||
|
||||
- **Template Ecosystem**
|
||||
- Child template framework
|
||||
- Template derivative system
|
||||
- Community template marketplace
|
||||
- Template rating and review system
|
||||
- Professional template support network
|
||||
|
||||
- **Template Quality & Maintenance**
|
||||
- Automated accessibility testing
|
||||
- Template performance auditing
|
||||
- Code quality monitoring
|
||||
- Update notification system
|
||||
- Template health dashboard
|
||||
|
||||
**Template Infrastructure**:
|
||||
- Template API for extensibility
|
||||
- Template package manager
|
||||
- Template development CLI tools
|
||||
- Template migration utilities
|
||||
- Comprehensive template documentation system
|
||||
|
||||
---
|
||||
|
||||
## Current Release (v03.06.03)
|
||||
|
||||
### System Requirements
|
||||
- **Joomla**: 4.4.x or 5.x
|
||||
- **PHP**: 8.0+
|
||||
- **Database**: MySQL/MariaDB compatible
|
||||
|
||||
### Architecture
|
||||
- **Base Template**: Joomla Cassiopeia
|
||||
- **Enhancement Layer**: Non-invasive overrides
|
||||
- **Asset Management**: Joomla Web Asset Manager (WAM)
|
||||
- **Frontend Framework**: Bootstrap 5
|
||||
- **Icon Library**: Font Awesome 7 Free
|
||||
|
||||
---
|
||||
|
||||
## Implemented Features
|
||||
|
||||
### 🎨 Theming & Visual Design
|
||||
|
||||
#### Color Palette System
|
||||
- **3 Built-in Palettes**: Standard, Alternative, Custom
|
||||
- **Dual Mode Support**: Separate light and dark configurations
|
||||
- **Custom Palettes**: User-definable via `colors_custom.css`
|
||||
- **Location**: `src/media/css/colors/{light|dark}/`
|
||||
|
||||
#### Dark Mode System
|
||||
- **Toggle Controls**: Switch (Light↔Dark) or Radios (Light/Dark/System)
|
||||
- **Default Mode**: Admin-configurable (system, light, or dark)
|
||||
- **Persistence**: localStorage for user preferences
|
||||
- **Auto-Detection**: Optional system preference detection
|
||||
- **Meta Tags**: `color-scheme` and `theme-color` support
|
||||
- **ARIA Bridge**: Bootstrap ARIA compatibility
|
||||
|
||||
#### Typography
|
||||
- **Font Schemes**:
|
||||
- Local: Roboto
|
||||
- Web (Google Fonts): Fira Sans, Roboto + Noto Sans
|
||||
- **Admin-Configurable**: Template settings dropdown
|
||||
|
||||
#### Branding
|
||||
- **Logo Support**: Custom logo upload
|
||||
- **Site Title**: Text-based branding option
|
||||
- **Site Description**: Tagline/subtitle field
|
||||
- **Font Awesome Kit**: Optional custom kit integration
|
||||
|
||||
### 📐 Layout & Structure
|
||||
|
||||
#### Module Positions (23 Total)
|
||||
**Header Area**:
|
||||
- topbar, below-topbar, below-logo, menu, search, banner
|
||||
|
||||
**Content Area**:
|
||||
- top-a, top-b, main-top, main-bottom, breadcrumbs
|
||||
- sidebar-left, sidebar-right
|
||||
|
||||
**Footer Area**:
|
||||
- bottom-a, bottom-b, footer-menu, footer
|
||||
|
||||
**Special**:
|
||||
- debug, offline-header, offline, offline-footer
|
||||
- drawer-left, drawer-right
|
||||
|
||||
#### Layout Options
|
||||
- **Container Type**: Fluid or Static
|
||||
- **Sticky Header**: Optional fixed navigation
|
||||
- **Back-to-Top Button**: Scrollable page support
|
||||
|
||||
### 📝 Content Features
|
||||
|
||||
#### Table of Contents (TOC)
|
||||
- **Automatic Generation**: From article headings
|
||||
- **Placement Options**: `toc-left` or `toc-right` layouts
|
||||
- **Article Integration**: Via Options → Layout dropdown
|
||||
- **Responsive**: Mobile-friendly sidebar placement
|
||||
|
||||
#### Article Layouts
|
||||
- **Default**: Standard Cassiopeia layout
|
||||
- **TOC Variants**: Left-sidebar or right-sidebar TOC
|
||||
- **Custom Overrides**: Located in `html/com_content/article/`
|
||||
|
||||
### 📊 Analytics & Tracking
|
||||
|
||||
#### Google Tag Manager (GTM)
|
||||
- **Enable/Disable**: Admin toggle
|
||||
- **Container ID**: Template parameter field
|
||||
- **Implementation**: Head and body script injection
|
||||
- **GDPR-Ready**: Configurable consent defaults
|
||||
|
||||
#### Google Analytics 4 (GA4)
|
||||
- **Enable/Disable**: Admin toggle
|
||||
- **Property ID**: Template parameter field
|
||||
- **Universal Analytics Fallback**: Legacy UA support
|
||||
- **Privacy-First**: Conditional loading based on settings
|
||||
|
||||
### 🎛️ Customization & Developer Tools
|
||||
|
||||
#### Custom Code Injection
|
||||
- **Head Start**: Custom HTML/JS before `</head>`
|
||||
- **Head End**: Custom HTML/JS at end of `<head>`
|
||||
- **Raw HTML**: Unfiltered code injection for advanced users
|
||||
|
||||
#### Drawer System
|
||||
- **Left/Right Drawers**: Offcanvas menu areas
|
||||
- **Icon Customization**: Font Awesome icon selection
|
||||
- **Default Icons**:
|
||||
- Left: `fa-solid fa-chevron-right`
|
||||
- Right: `fa-solid fa-chevron-left`
|
||||
|
||||
#### Asset Management
|
||||
- **Joomla WAM**: Complete asset registry in `joomla.asset.json`
|
||||
- **Development/Production Modes**: Minified and unminified assets
|
||||
- **Dependency Management**: Automatic script/style loading
|
||||
|
||||
### 🏗️ Template Overrides
|
||||
|
||||
#### Component Overrides
|
||||
**Content (com_content)**:
|
||||
- Article layouts (default, toc-left, toc-right)
|
||||
- Category layouts (blog, list)
|
||||
- Featured articles
|
||||
|
||||
**Contact (com_contact)**:
|
||||
- Contact form layouts
|
||||
|
||||
**Engage (com_engage)**:
|
||||
- Comment system integration
|
||||
|
||||
#### Module Overrides
|
||||
**Menu (mod_menu)**:
|
||||
- Metis dropdown menu
|
||||
- Offcanvas navigation
|
||||
|
||||
**VirtueMart**:
|
||||
- Product display (`mod_virtuemart_product`)
|
||||
- Shopping cart (`mod_virtuemart_cart`)
|
||||
- Manufacturer display (`mod_virtuemart_manufacturer`)
|
||||
- Category display (`mod_virtuemart_category`)
|
||||
- Currency selector (`mod_virtuemart_currencies`)
|
||||
|
||||
**Other Modules**:
|
||||
- Custom HTML (`mod_custom`)
|
||||
- GABble social integration (`mod_gabble`)
|
||||
|
||||
**Membership System (OS Membership)**:
|
||||
- Plan layouts (default, pricing tables)
|
||||
- Member management interfaces
|
||||
|
||||
### 🔧 Configuration Parameters
|
||||
|
||||
#### Theme Tab
|
||||
**General**:
|
||||
- `theme_enabled` - Enable/disable theme system
|
||||
- `theme_control_type` - Toggle UI type (switch/radios/none)
|
||||
- `theme_default_choice` - Default mode (system/light/dark)
|
||||
- `theme_auto_dark` - Auto-detect system preference
|
||||
- `theme_meta_color_scheme` - Inject `color-scheme` meta tag
|
||||
- `theme_meta_theme_color` - Inject `theme-color` meta tag
|
||||
- `theme_bridge_bs_aria` - Bootstrap ARIA compatibility
|
||||
|
||||
**Variables & Palettes**:
|
||||
- `colorLightName` - Light mode color scheme
|
||||
- `colorDarkName` - Dark mode color scheme
|
||||
|
||||
**Typography**:
|
||||
- `useFontScheme` - Font selection (local/web)
|
||||
|
||||
**Branding & Icons**:
|
||||
- `brand` - Show/hide branding
|
||||
- `logoFile` - Logo upload path
|
||||
- `siteTitle` - Site title text
|
||||
- `siteDescription` - Site tagline
|
||||
- `fA6KitCode` - Font Awesome kit code
|
||||
|
||||
**Header & Navigation**:
|
||||
- `stickyHeader` - Fixed navigation
|
||||
- `backTop` - Back-to-top button
|
||||
|
||||
**Toggle UI**:
|
||||
- `theme_fab_enabled` - Floating action button for theme toggle
|
||||
- `theme_fab_pos` - FAB position (br/bl/tr/tl)
|
||||
|
||||
#### Google Tab
|
||||
- `googletagmanager` - Enable GTM
|
||||
- `googletagmanagerid` - GTM container ID
|
||||
- `googleanalytics` - Enable GA4
|
||||
- `googleanalyticsid` - GA4 property ID
|
||||
|
||||
#### Custom Code Tab
|
||||
- `custom_head_start` - Custom code at head start
|
||||
- `custom_head_end` - Custom code at head end
|
||||
|
||||
#### Drawers Tab
|
||||
- `drawerLeftIcon` - Left drawer icon (Font Awesome class)
|
||||
- `drawerRightIcon` - Right drawer icon (Font Awesome class)
|
||||
|
||||
#### Advanced Tab
|
||||
- `fluidContainer` - Container layout (static/fluid)
|
||||
|
||||
### 🛠️ Development Tools
|
||||
|
||||
#### Quality Assurance
|
||||
- **Codeception**: Automated testing framework
|
||||
- **PHPStan**: Static analysis (level 8+)
|
||||
- **PHPCS**: Code style validation (PSR-12)
|
||||
- **PHPCompatibility**: PHP 8.0+ compatibility checks
|
||||
|
||||
#### CI/CD Workflows
|
||||
- **Dependency Review**: Vulnerability scanning
|
||||
- **Standards Compliance**: MokoStandards validation
|
||||
- **CodeQL**: Security analysis (GitHub default)
|
||||
- **Dependabot**: Automated dependency updates
|
||||
|
||||
#### Documentation
|
||||
- **Quick Start**: 5-minute developer setup
|
||||
- **Workflow Guide**: Git strategy, branching, releases
|
||||
- **Joomla Development**: Testing, packaging, multi-version support
|
||||
|
||||
---
|
||||
|
||||
## Planned Features
|
||||
|
||||
### 🚧 In Development
|
||||
|
||||
#### Soft Offline Mode (v03.07.00 - Planned)
|
||||
**Status**: Planned for v03.07.00
|
||||
**Priority**: High
|
||||
**Description**: Keep selected categories accessible during site maintenance mode with persistent links to essential pages
|
||||
|
||||
**Use Cases**:
|
||||
- Legal documents remain viewable during downtime
|
||||
- Policy pages accessible for compliance requirements
|
||||
- Terms of service always available to users
|
||||
- Privacy policy accessible at all times
|
||||
- Essential public information during maintenance
|
||||
|
||||
**Technical Specifications**:
|
||||
- **Configuration Method**: Template parameters in `templateDetails.xml`
|
||||
- **Category Access**: Category IDs stored as comma-separated values
|
||||
- **Persistent Links**: Direct article/menu item links always visible
|
||||
- **Access Control**: Check in `offline.php` template file
|
||||
- **Content Rendering**: Use Joomla's content component to fetch articles
|
||||
- **Security**: Maintain proper access levels and permissions
|
||||
|
||||
**Implementation Plan**:
|
||||
1. Add category selection field to template parameters
|
||||
2. Add persistent link configuration (Terms of Service, Privacy Policy, etc.)
|
||||
3. Modify `offline.php` to check for allowed categories
|
||||
4. Add persistent link display in offline mode header/footer
|
||||
5. Implement category content fetching during offline mode
|
||||
6. Add styling for offline mode category display and persistent links
|
||||
7. Test with various category and link configurations
|
||||
8. Document admin configuration steps
|
||||
|
||||
**Configuration Interface**:
|
||||
- **Category Field Type**: Category multiselect in template settings
|
||||
- **Label**: "Categories Accessible During Offline Mode"
|
||||
- **Default**: None (all content hidden by default)
|
||||
- **Persistent Links**: Text fields for essential always-available links
|
||||
- **Terms of Service URL**: Direct link to TOS article/page
|
||||
- **Privacy Policy URL**: Direct link to privacy policy
|
||||
- **Contact URL**: Optional contact page link
|
||||
- **Custom Link 1-3**: Additional persistent links if needed
|
||||
- **Admin Path**: System → Site Templates → MokoOnyx → Advanced → Offline Mode Settings
|
||||
|
||||
**Persistent Links Feature**:
|
||||
- **Display Location**: Footer of offline page
|
||||
- **Styling**: Clearly visible, accessible links
|
||||
- **Format**: "Terms of Service | Privacy Policy | Contact"
|
||||
- **Behavior**: Links bypass offline mode restrictions
|
||||
- **Validation**: Check if URLs are valid Joomla routes
|
||||
|
||||
**Benefits**:
|
||||
- ✅ Compliance: Keep legal pages accessible
|
||||
- ✅ Transparency: Users can access essential information
|
||||
- ✅ Flexibility: Admin control over which categories remain visible
|
||||
- ✅ Security: Respects Joomla access levels
|
||||
- ✅ Legal Protection: Terms of Service always accessible
|
||||
- ✅ User Trust: Privacy policy always available
|
||||
|
||||
**Milestone**: Target release v03.07.00 (Q2 2026)
|
||||
|
||||
#### TODO Tracking System
|
||||
**Status**: Mentioned in CHANGELOG (v03.05.00)
|
||||
**Description**: Separate TODO tracking file
|
||||
**Purpose**: Centralized issue and feature tracking outside changelog
|
||||
|
||||
### 🔮 Future Enhancements
|
||||
|
||||
#### Development Mode (Commented Out)
|
||||
**Status**: Code exists but disabled
|
||||
**Location**: `templateDetails.xml` line 91
|
||||
**Description**: Comprehensive development mode toggle
|
||||
**Potential Features**:
|
||||
- Unminified asset loading
|
||||
- Debug output
|
||||
- Performance profiling
|
||||
- Template cache bypass
|
||||
|
||||
#### Potential Features (Community Requested)
|
||||
*Note: These are conceptual and not yet officially planned*
|
||||
|
||||
**Enhanced Accessibility**:
|
||||
- WCAG 2.1 AAA compliance mode
|
||||
- High-contrast themes
|
||||
- Screen reader optimizations
|
||||
- Keyboard navigation improvements
|
||||
|
||||
**Template Layout Features**:
|
||||
- Advanced responsive grid layouts
|
||||
- Multiple column variations
|
||||
- Custom module position system
|
||||
- Layout preset library
|
||||
|
||||
**Template Styling Features**:
|
||||
- Extended color palette management
|
||||
- Custom font upload support
|
||||
- Typography scale controls
|
||||
- Visual style editor
|
||||
|
||||
---
|
||||
|
||||
## Development Priorities
|
||||
|
||||
### Immediate Focus (v03.x - 2026)
|
||||
1. **Bootstrap TOC Integration**: Complete and document v1.0.1 implementation ✅
|
||||
2. **Soft Offline Mode**: Implement category-based offline access (Target: v03.07.00)
|
||||
3. **TODO Tracking System**: Implement separate file for issue tracking
|
||||
4. **Security Updates**: Maintain Dependabot and CodeQL scans
|
||||
5. **Documentation**: Keep docs synchronized with features
|
||||
6. **Bug Fixes**: Address reported issues and edge cases
|
||||
|
||||
### v04.00.00 Priorities (2027) - Template Foundation
|
||||
1. **WCAG 2.1 AA Compliance**: Full template accessibility audit and implementation
|
||||
2. **Template Performance**: Critical CSS, lazy loading, WebP support
|
||||
3. **Layout System**: Enhanced responsive grid and module positions
|
||||
4. **Development Mode**: Enable comprehensive template developer tools
|
||||
|
||||
### v05.00.00 Priorities (2028) - Template Customization
|
||||
1. **Layout Builder**: Template-based page layout system
|
||||
2. **Styling System**: Extended color palettes and CSS variable management
|
||||
3. **Template Components**: Enhanced header, footer, and menu variations
|
||||
4. **Responsive Design**: Mobile-first navigation and layout improvements
|
||||
|
||||
### v06.00.00 Priorities (2029) - Template Extensions
|
||||
1. **Template Marketplace**: Addon system and community extensions
|
||||
2. **Module System**: Advanced module chrome and animation options
|
||||
3. **Media Handling**: Background images, parallax, video backgrounds
|
||||
4. **Template SEO**: Schema markup templates and meta tag controls
|
||||
|
||||
### v07.00.00+ Priorities (2030+) - Modern Standards
|
||||
1. **Modern CSS**: Grid, Container Queries, Cascade Layers
|
||||
2. **Progressive Template**: Offline-capable assets and PWA features
|
||||
3. **Animation System**: Scroll-triggered effects and micro-interactions
|
||||
4. **Template Performance**: Advanced optimization and monitoring
|
||||
|
||||
---
|
||||
|
||||
## Long-term Vision
|
||||
|
||||
### Mission Statement
|
||||
MokoOnyx aims to be the **most developer-friendly, user-customizable, and standards-compliant Joomla template** while maintaining minimal core overrides for maximum upgrade compatibility.
|
||||
|
||||
### Core Principles
|
||||
1. **Non-Invasive**: Minimal Cassiopeia overrides
|
||||
2. **Standards-First**: MokoStandards compliance
|
||||
3. **Accessibility**: WCAG 2.1 compliance
|
||||
4. **Performance**: Fast, optimized delivery
|
||||
5. **Developer Experience**: Clear docs, easy setup, powerful tools
|
||||
6. **Template-Focused**: Pure template features without complex external dependencies
|
||||
|
||||
### 5-Year Strategic Roadmap (Template Features)
|
||||
|
||||
#### 2027 (v04.00.00) - Accessibility & Performance
|
||||
- Achieve WCAG 2.1 AA compliance for all template elements
|
||||
- Implement critical template performance optimizations
|
||||
- Enhance template layout system with flexible grids
|
||||
- Enable comprehensive development mode for template developers
|
||||
|
||||
#### 2028 (v05.00.00) - Layouts & Customization
|
||||
- Launch template-based layout builder system
|
||||
- Deploy extended styling and customization options
|
||||
- Enhance template component variations (headers, footers, menus)
|
||||
- Improve responsive design patterns for all devices
|
||||
|
||||
#### 2029 (v06.00.00) - Extensions & Enhancements
|
||||
- Introduce template addon and extension system
|
||||
- Launch template preset marketplace
|
||||
- Deploy advanced module styling and animation features
|
||||
- Implement comprehensive template SEO controls
|
||||
|
||||
#### 2030 (v07.00.00) - Modern Standards
|
||||
- Adopt modern CSS standards (Grid, Container Queries, Cascade Layers)
|
||||
- Implement progressive template features (PWA support)
|
||||
- Deploy advanced animation and interaction system
|
||||
- Enhance template performance monitoring and optimization
|
||||
|
||||
#### 2031 (v08.00.00) - Next-Generation Template
|
||||
- Advanced layout systems with subgrid support
|
||||
- Comprehensive template component library
|
||||
- Enhanced visual customization tools
|
||||
- Template ecosystem with child themes and derivatives
|
||||
|
||||
---
|
||||
|
||||
## External Resources
|
||||
|
||||
### Official Links
|
||||
- **Full Roadmap**: [https://mokoconsulting.tech/support/joomla-cms/mokoonyx-roadmap](https://mokoconsulting.tech/support/joomla-cms/mokoonyx-roadmap)
|
||||
- **Repository**: [https://git.mokoconsulting.tech/MokoConsulting/moko-cassiopeia](https://git.mokoconsulting.tech/MokoConsulting/moko-cassiopeia)
|
||||
- **Issue Tracker**: [GitHub Issues](https://git.mokoconsulting.tech/MokoConsulting/moko-cassiopeia/issues)
|
||||
- **Changelog**: [CHANGELOG.md](../CHANGELOG.md)
|
||||
|
||||
### Community
|
||||
- **Email Support**: hello@mokoconsulting.tech
|
||||
- **Contributing**: [CONTRIBUTING.md](../CONTRIBUTING.md)
|
||||
- **Code of Conduct**: [CODE_OF_CONDUCT.md](../CODE_OF_CONDUCT.md)
|
||||
|
||||
### Documentation
|
||||
- **Quick Start**: [docs/QUICK_START.md](./QUICK_START.md)
|
||||
- **Workflow Guide**: [docs/WORKFLOW_GUIDE.md](./WORKFLOW_GUIDE.md)
|
||||
- **Joomla Development**: [docs/JOOMLA_DEVELOPMENT.md](./JOOMLA_DEVELOPMENT.md)
|
||||
- **Main README**: [README.md](../README.md)
|
||||
|
||||
---
|
||||
|
||||
## Contributing to the Roadmap
|
||||
|
||||
Have ideas for future features? We welcome community input!
|
||||
|
||||
**How to Suggest Features**:
|
||||
1. Check the [GitHub Issues](https://git.mokoconsulting.tech/MokoConsulting/moko-cassiopeia/issues) for existing requests
|
||||
2. Open a new issue with the `enhancement` label
|
||||
3. Provide clear use cases and benefits
|
||||
4. Engage in community discussion
|
||||
|
||||
**Feature Evaluation Criteria**:
|
||||
- Alignment with core principles
|
||||
- User demand and use cases
|
||||
- Technical feasibility
|
||||
- Maintenance burden
|
||||
- Performance impact
|
||||
- Security implications
|
||||
|
||||
---
|
||||
|
||||
## Metadata
|
||||
|
||||
* Document: docs/ROADMAP.md
|
||||
* Repository: [https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx](https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx)
|
||||
* Path: /docs/ROADMAP.md
|
||||
* Owner: Moko Consulting
|
||||
* Version: 03.06.03
|
||||
* Status: Active
|
||||
* Effective Date: 2026-01-30
|
||||
* Classification: Public Open Source Documentation
|
||||
|
||||
## Revision History
|
||||
|
||||
| Date | Change Summary | Author |
|
||||
| ---------- | ----------------------------------------------------- | --------------- |
|
||||
| 2026-01-27 | Initial version-specific roadmap generated from codebase scan. | GitHub Copilot |
|
||||
| 2026-01-27 | Added 5-year future roadmap with annual major version releases (v04-v08). | GitHub Copilot |
|
||||
| 2026-01-27 | Refocused roadmap to concentrate on template-oriented features only. | GitHub Copilot |
|
||||
459
docs/WORKFLOW_GUIDE.md
Normal file
459
docs/WORKFLOW_GUIDE.md
Normal file
@@ -0,0 +1,459 @@
|
||||
# Workflow Guide - Moko Cassiopeia
|
||||
|
||||
Quick reference guide for GitHub Actions workflows and common development tasks.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Overview](#overview)
|
||||
- [Workflow Quick Reference](#workflow-quick-reference)
|
||||
- [Common Development Tasks](#common-development-tasks)
|
||||
- [Troubleshooting](#troubleshooting)
|
||||
- [Best Practices](#best-practices)
|
||||
|
||||
## Overview
|
||||
|
||||
This repository uses GitHub Actions for continuous integration, testing, quality checks, and deployment. All workflows are located in `.github/workflows/`.
|
||||
|
||||
### Workflow Execution Model
|
||||
|
||||
```
|
||||
┌─────────────────┐
|
||||
│ Code Changes │
|
||||
└────────┬────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ CI Pipeline │ ← Validation, Testing, Quality
|
||||
└────────┬────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ Version Branch │ ← Create dev/X.Y.Z branch
|
||||
└────────┬────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ Release Pipeline│ ← dev → rc → version → main
|
||||
└────────┬────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ Distribution │ ← ZIP package + GitHub Release
|
||||
└─────────────────┘
|
||||
```
|
||||
|
||||
## Workflow Quick Reference
|
||||
|
||||
### Continuous Integration (ci.yml)
|
||||
|
||||
**Trigger:** Automatic on push/PR to main, dev/*, rc/*, version/* branches
|
||||
|
||||
**Purpose:** Validates code quality and repository structure
|
||||
|
||||
**What it does:**
|
||||
- ✅ Validates Joomla manifest XML
|
||||
- ✅ Checks XML well-formedness
|
||||
- ✅ Validates GitHub Actions workflows
|
||||
- ✅ Runs PHP syntax checks
|
||||
- ✅ Checks for secrets in code
|
||||
- ✅ Validates license headers
|
||||
- ✅ Verifies version alignment
|
||||
|
||||
**When to check:** After every commit
|
||||
|
||||
**How to view results:**
|
||||
```bash
|
||||
# Via GitHub CLI
|
||||
gh run list --workflow=ci.yml --limit 5
|
||||
gh run view <run-id> --log
|
||||
```
|
||||
|
||||
### PHP Quality Checks (php_quality.yml)
|
||||
|
||||
**Trigger:** Automatic on push/PR to main, dev/*, rc/*, version/* branches
|
||||
|
||||
**Purpose:** Ensures PHP code quality and compatibility
|
||||
|
||||
**What it does:**
|
||||
- 🔍 PHPStan static analysis (level 5)
|
||||
- 📏 PHP_CodeSniffer with PSR-12 standards
|
||||
- ✔️ PHP 8.0+ compatibility checks
|
||||
|
||||
**Matrix:** PHP 8.0, 8.1, 8.2, 8.3
|
||||
|
||||
**When to check:** Before committing PHP changes
|
||||
|
||||
**How to run locally:**
|
||||
```bash
|
||||
# Install tools
|
||||
composer global require "squizlabs/php_codesniffer:^3.0" --with-all-dependencies
|
||||
composer global require "phpstan/phpstan:^1.0" --with-all-dependencies
|
||||
|
||||
# Run checks
|
||||
phpcs --standard=phpcs.xml src/
|
||||
phpstan analyse --configuration=phpstan.neon
|
||||
```
|
||||
|
||||
### Joomla Testing (joomla_testing.yml)
|
||||
|
||||
**Trigger:** Automatic on push/PR to main, dev/*, rc/* branches
|
||||
|
||||
**Purpose:** Tests template compatibility with Joomla versions
|
||||
|
||||
**What it does:**
|
||||
- 📦 Downloads and installs Joomla (4.4, 5.0, 5.1)
|
||||
- 🔧 Installs template into Joomla
|
||||
- ✅ Validates template installation
|
||||
- 🧪 Runs Codeception tests
|
||||
|
||||
**Matrix:** Joomla 4.4/5.0/5.1 × PHP 8.0/8.1/8.2/8.3
|
||||
|
||||
**When to check:** Before releasing new versions
|
||||
|
||||
**How to test locally:**
|
||||
```bash
|
||||
# See docs/JOOMLA_DEVELOPMENT.md for local testing setup
|
||||
codecept run
|
||||
```
|
||||
|
||||
### Version Branch Creation (version_branch.yml)
|
||||
|
||||
**Trigger:** Manual workflow dispatch
|
||||
|
||||
**Purpose:** Creates a new version branch and bumps version numbers
|
||||
|
||||
**What it does:**
|
||||
- 🏷️ Creates dev/*, rc/*, or version/* branch
|
||||
- 📝 Updates version in all files
|
||||
- 📅 Updates manifest dates
|
||||
- 📋 Moves CHANGELOG unreleased to version
|
||||
- ✅ Validates version hierarchy
|
||||
|
||||
**When to use:** Starting work on a new version
|
||||
|
||||
**How to run:**
|
||||
1. Go to Actions → Create version branch
|
||||
2. Click "Run workflow"
|
||||
3. Enter version (e.g., 03.06.00)
|
||||
4. Select branch prefix (dev/, rc/, or version/)
|
||||
5. Click "Run workflow"
|
||||
|
||||
**Example:**
|
||||
```yaml
|
||||
new_version: 03.06.00
|
||||
branch_prefix: dev/
|
||||
version_text: beta
|
||||
```
|
||||
|
||||
### Release Pipeline (release_pipeline.yml)
|
||||
|
||||
**Trigger:** Manual workflow dispatch or release event
|
||||
|
||||
**Purpose:** Promotes branches through release stages and creates distributions
|
||||
|
||||
**What it does:**
|
||||
- 🔄 Promotes branches: dev → rc → version → main
|
||||
- 📅 Normalizes dates in manifest and CHANGELOG
|
||||
- 📦 Builds distributable ZIP package
|
||||
- 🚀 Uploads to SFTP server
|
||||
- 🏷️ Creates Git tag
|
||||
- 📋 Creates GitHub Release
|
||||
- 🔒 Attests build provenance
|
||||
|
||||
**When to use:** Promoting a version through release stages
|
||||
|
||||
**How to run:**
|
||||
1. Go to Actions → Release Pipeline
|
||||
2. Click "Run workflow"
|
||||
3. Select classification (auto/rc/stable)
|
||||
4. Click "Run workflow"
|
||||
|
||||
**Release flow:**
|
||||
```
|
||||
dev/X.Y.Z → rc/X.Y.Z → version/X.Y.Z → main
|
||||
(dev) (RC) (stable) (production)
|
||||
```
|
||||
|
||||
### Deploy to Staging (deploy_staging.yml)
|
||||
|
||||
**Trigger:** Manual workflow dispatch
|
||||
|
||||
**Purpose:** Deploys template to staging/development environments
|
||||
|
||||
**What it does:**
|
||||
- ✅ Validates deployment prerequisites
|
||||
- 📦 Builds deployment package
|
||||
- 🚀 Uploads via SFTP to environment
|
||||
- 📝 Creates deployment summary
|
||||
|
||||
**When to use:** Testing in staging before production release
|
||||
|
||||
**How to run:**
|
||||
1. Go to Actions → Deploy to Staging
|
||||
2. Click "Run workflow"
|
||||
3. Select environment (staging/development/preview)
|
||||
4. Optionally specify version
|
||||
5. Click "Run workflow"
|
||||
|
||||
**Required secrets:**
|
||||
- `STAGING_HOST` - SFTP hostname
|
||||
- `STAGING_USER` - SFTP username
|
||||
- `STAGING_KEY` - SSH private key (or `STAGING_PASSWORD`)
|
||||
- `STAGING_PATH` - Remote deployment path
|
||||
|
||||
### Repository Health (repo_health.yml)
|
||||
|
||||
**Trigger:** Manual workflow dispatch (admin only)
|
||||
|
||||
**Purpose:** Comprehensive repository health and configuration checks
|
||||
|
||||
**What it does:**
|
||||
- 🔐 Validates release configuration
|
||||
- 🌐 Tests SFTP connectivity
|
||||
- 📂 Checks scripts governance
|
||||
- 📄 Validates required artifacts
|
||||
- 🔍 Extended checks (SPDX, ShellCheck, etc.)
|
||||
|
||||
**When to use:** Before major releases or when debugging deployment issues
|
||||
|
||||
**How to run:**
|
||||
1. Go to Actions → Repo Health
|
||||
2. Click "Run workflow"
|
||||
3. Select profile (all/release/repo)
|
||||
4. Click "Run workflow"
|
||||
|
||||
**Profiles:**
|
||||
- `all` - Run all checks
|
||||
- `release` - Release configuration and SFTP only
|
||||
- `scripts` - Scripts governance only
|
||||
- `repo` - Repository health only
|
||||
|
||||
## Common Development Tasks
|
||||
|
||||
### Starting a New Feature
|
||||
|
||||
```bash
|
||||
# 1. Create a new version branch via GitHub Actions
|
||||
# Actions → Create version branch → dev/X.Y.Z
|
||||
|
||||
# 2. Clone and checkout the new branch
|
||||
git fetch origin
|
||||
git checkout dev/X.Y.Z
|
||||
|
||||
# 3. Make your changes
|
||||
vim src/index.php
|
||||
|
||||
# 4. Validate locally
|
||||
make validate-required
|
||||
|
||||
# 5. Commit and push
|
||||
git add -A
|
||||
git commit -m "feat: add new feature"
|
||||
git push origin dev/X.Y.Z
|
||||
```
|
||||
|
||||
### Running All Validations Locally
|
||||
|
||||
```bash
|
||||
# Run comprehensive validation suite
|
||||
make validate-required
|
||||
|
||||
# Run quality checks
|
||||
make quality
|
||||
```
|
||||
|
||||
### Creating a Release Package
|
||||
|
||||
```bash
|
||||
# Package with auto-detected version
|
||||
```bash
|
||||
# Package with auto-detected version
|
||||
make package
|
||||
|
||||
# Verify package contents
|
||||
unzip -l dist/moko-cassiopeia-*.zip
|
||||
```
|
||||
|
||||
### Updating Version Numbers
|
||||
|
||||
```bash
|
||||
# Via GitHub Actions (recommended)
|
||||
# Actions → Release Management workflow
|
||||
```
|
||||
|
||||
### Updating CHANGELOG
|
||||
|
||||
Update CHANGELOG.md manually or via pull request following the existing format.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### CI Failures
|
||||
|
||||
#### PHP Syntax Errors
|
||||
|
||||
```bash
|
||||
# Check specific file
|
||||
php -l src/index.php
|
||||
|
||||
# Run validation
|
||||
make validate-required
|
||||
```
|
||||
|
||||
#### Manifest Validation Failed
|
||||
|
||||
```bash
|
||||
# Validate manifest and XML files
|
||||
make validate-required
|
||||
```
|
||||
|
||||
#### Version Alignment Issues
|
||||
|
||||
```bash
|
||||
# Check version consistency
|
||||
make validate-required
|
||||
```
|
||||
|
||||
### Workflow Failures
|
||||
|
||||
#### "Branch already exists"
|
||||
|
||||
```bash
|
||||
# Check existing branches
|
||||
git branch -r | grep dev/
|
||||
|
||||
# Delete remote branch if needed (carefully!)
|
||||
git push origin --delete dev/03.06.00
|
||||
```
|
||||
|
||||
#### "Missing required secrets"
|
||||
|
||||
Go to repository Settings → Secrets and variables → Actions, and add:
|
||||
- `FTP_SERVER`
|
||||
- `FTP_USER`
|
||||
- `FTP_KEY` or `FTP_PASSWORD`
|
||||
- `FTP_PATH`
|
||||
|
||||
#### SFTP Connection Failed
|
||||
|
||||
1. Verify credentials in repo_health workflow:
|
||||
- Actions → Repo Health → profile: release
|
||||
|
||||
2. Check SSH key format (OpenSSH, not PuTTY PPK)
|
||||
|
||||
3. Verify server allows connections from GitHub IPs
|
||||
|
||||
### Quality Check Failures
|
||||
|
||||
#### PHPStan Errors
|
||||
|
||||
```bash
|
||||
# Run locally to see full output
|
||||
phpstan analyse --configuration=phpstan.neon
|
||||
|
||||
# Generate baseline to ignore existing issues
|
||||
phpstan analyse --configuration=phpstan.neon --generate-baseline
|
||||
```
|
||||
|
||||
#### PHPCS Violations
|
||||
|
||||
```bash
|
||||
# Check violations
|
||||
phpcs --standard=phpcs.xml src/
|
||||
|
||||
# Auto-fix where possible
|
||||
phpcbf --standard=phpcs.xml src/
|
||||
|
||||
# Show specific error codes
|
||||
phpcs --standard=phpcs.xml --report=source src/
|
||||
```
|
||||
|
||||
#### Joomla Testing Failed
|
||||
|
||||
1. Check PHP/Joomla version matrix compatibility
|
||||
2. Review MySQL connection errors
|
||||
3. Verify template manifest structure
|
||||
4. Check template file paths
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Version Management
|
||||
|
||||
1. **Always use version branches:** dev/X.Y.Z, rc/X.Y.Z, version/X.Y.Z
|
||||
2. **Follow hierarchy:** dev → rc → version → main
|
||||
3. **Update CHANGELOG:** Document all changes in Unreleased section
|
||||
4. **Semantic versioning:** Major.Minor.Patch (03.06.00)
|
||||
|
||||
### Code Quality
|
||||
|
||||
1. **Run validations locally** before pushing
|
||||
2. **Fix PHPStan warnings** at level 5
|
||||
3. **Follow PSR-12** coding standards
|
||||
4. **Add SPDX license headers** to new files
|
||||
5. **Keep functions small** and well-documented
|
||||
|
||||
### Workflow Usage
|
||||
|
||||
1. **Use CI for every commit** - automated validation
|
||||
2. **Run repo_health before releases** - comprehensive checks
|
||||
3. **Test on staging first** - never deploy directly to production
|
||||
4. **Monitor workflow runs** - fix failures promptly
|
||||
5. **Review workflow logs** - understand what changed
|
||||
|
||||
### Release Process
|
||||
|
||||
1. **Create dev branch** → Work on features
|
||||
2. **Promote to rc** → Release candidate testing
|
||||
3. **Promote to version** → Stable release
|
||||
4. **Merge to main** → Production (auto-merged via PR)
|
||||
5. **Create GitHub Release** → Public distribution
|
||||
|
||||
### Security
|
||||
|
||||
1. **Never commit secrets** - use GitHub Secrets
|
||||
2. **Use SSH keys** for SFTP (not passwords)
|
||||
3. **Scan for secrets** - runs automatically in CI
|
||||
4. **Keep dependencies updated** - security patches
|
||||
5. **Review security advisories** - GitHub Dependabot
|
||||
|
||||
### Documentation
|
||||
|
||||
1. **Update docs with code** - keep in sync
|
||||
2. **Document workflow changes** - update this guide
|
||||
3. **Add examples** - show, don't just tell
|
||||
4. **Link to relevant docs** - cross-reference
|
||||
5. **Keep README current** - first impression matters
|
||||
|
||||
## Quick Links
|
||||
|
||||
- [Main README](../README.md) - Project overview
|
||||
- [Joomla Development Guide](./JOOMLA_DEVELOPMENT.md) - Testing and quality
|
||||
- [CHANGELOG](../CHANGELOG.md) - Version history
|
||||
- [CONTRIBUTING](../CONTRIBUTING.md) - Contribution guidelines
|
||||
|
||||
## Getting Help
|
||||
|
||||
1. **Check workflow logs** - Most issues have clear error messages
|
||||
2. **Review this guide** - Common solutions documented
|
||||
3. **Run validation scripts** - Identify specific issues
|
||||
4. **Open an issue** - For bugs or questions
|
||||
5. **Contact maintainers** - For access or configuration issues
|
||||
|
||||
---
|
||||
|
||||
## Metadata
|
||||
|
||||
* Document: docs/WORKFLOW_GUIDE.md
|
||||
* Repository: [https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx](https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx)
|
||||
* Path: /docs/WORKFLOW_GUIDE.md
|
||||
* Owner: Moko Consulting
|
||||
* Version: 03.06.03
|
||||
* Status: Active
|
||||
* Effective Date: 2026-01-30
|
||||
* Classification: Public Open Source Documentation
|
||||
|
||||
## Revision History
|
||||
|
||||
| Date | Change Summary | Author |
|
||||
| ---------- | ----------------------------------------------------- | --------------- |
|
||||
| 2026-01-30 | Updated metadata to MokoStandards format | GitHub Copilot |
|
||||
| 2025-01-04 | Initial workflow guide created | GitHub Copilot |
|
||||
Reference in New Issue
Block a user