From ac51405b06d67565792b663494c05ae6d4af35fc Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 20 Feb 2026 01:06:58 +0000 Subject: [PATCH] Add comprehensive client fork README template and documentation Co-authored-by: jmiller-moko <230051081+jmiller-moko@users.noreply.github.com> --- CLIENT_FORK_README.md | 453 +++++++++++++++++++++++ README.md | 18 +- docs/README.md | 14 +- templates/CLIENT_FORK_README_TEMPLATE.md | 57 +++ 4 files changed, 537 insertions(+), 5 deletions(-) create mode 100644 CLIENT_FORK_README.md create mode 100644 templates/CLIENT_FORK_README_TEMPLATE.md diff --git a/CLIENT_FORK_README.md b/CLIENT_FORK_README.md new file mode 100644 index 0000000..a0ab7e6 --- /dev/null +++ b/CLIENT_FORK_README.md @@ -0,0 +1,453 @@ + + +# [CLIENT NAME] - MokoCassiopeia Custom Fork + +**Custom Joomla Template Fork for [CLIENT NAME]** + +This is a customized fork of the [MokoCassiopeia](https://github.com/mokoconsulting-tech/MokoCassiopeia) Joomla template, tailored specifically for [CLIENT NAME]'s website. + +--- + +## 📋 About This Fork + +This repository contains client-specific customizations built on top of the MokoCassiopeia template. The template provides a modern, lightweight enhancement layer for Joomla with advanced theming, Font Awesome 7, Bootstrap 5, and dark mode support. + +### Customization Strategy + +This fork maintains the following customizations: +- **Custom Color Schemes**: Brand-specific colors for light and dark modes +- **Custom Code**: Client-specific HTML, CSS, and JavaScript customizations +- **Configuration**: Pre-configured template settings for the client environment + +All customizations are designed to be preserved when syncing with upstream MokoCassiopeia updates. + +--- + +## 🚀 Quick Start + +### Prerequisites + +- **Joomla**: 4.4.x or 5.x +- **PHP**: 8.0 or higher +- **Git**: For version control and syncing with upstream +- **Local Development**: MAMP/XAMPP/Docker for local testing + +### Installation for Development + +1. **Clone this repository**: + ```bash + git clone [YOUR-FORK-URL] + cd [YOUR-FORK-NAME] + ``` + +2. **Set up upstream remote** (for syncing updates): + ```bash + git remote add upstream https://github.com/mokoconsulting-tech/MokoCassiopeia.git + git fetch upstream + ``` + +3. **Install into Joomla**: + - Copy the `src/` directory contents to your Joomla installation: + - `src/templates/` → `[joomla]/templates/` + - `src/media/` → `[joomla]/media/templates/site/mokocassiopeia/` + - `src/language/` → `[joomla]/language/` + - `src/administrator/language/` → `[joomla]/administrator/language/` + +4. **Enable the template**: + - Log into Joomla admin + - Navigate to **System → Site Templates** + - Set **MokoCassiopeia** as the default template + +--- + +## 🎨 Custom Branding & Colors + +### Custom Color Schemes + +This fork includes custom color schemes specific to [CLIENT NAME]'s brand: + +**Location**: +- Light mode: `src/media/css/colors/light/colors_custom.css` +- Dark mode: `src/media/css/colors/dark/colors_custom.css` + +**Note**: These files are gitignored in the upstream repository to prevent conflicts, but are tracked in this fork. + +### Modifying Brand Colors + +1. **Edit the custom color files**: + ```bash + # Light mode colors + edit src/media/css/colors/light/colors_custom.css + + # Dark mode colors + edit src/media/css/colors/dark/colors_custom.css + ``` + +2. **Key variables to customize**: + ```css + :root[data-bs-theme="light"] { + --color-primary: #YOUR-BRAND-COLOR; + --accent-color-primary: #YOUR-ACCENT-COLOR; + --color-link: #YOUR-LINK-COLOR; + --nav-bg-color: #YOUR-NAV-BG; + } + ``` + +3. **Test your changes**: + - Clear Joomla cache: System → Clear Cache + - Clear browser cache (Ctrl+Shift+R / Cmd+Shift+R) + - View your site in light and dark modes + +### Available CSS Variables + +For a complete reference of all customizable CSS variables, see the [CSS Variables Documentation](./docs/CSS_VARIABLES.md) in the upstream repository. + +--- + +## 🔧 Custom Code Injection + +### Using custom.php + +The `src/templates/custom.php` file allows for custom PHP functions and HTML snippets: + +**Location**: `src/templates/custom.php` + +**Example Use Cases**: +- Custom helper functions +- Client-specific HTML snippets +- Custom console logging +- Integration code + +**Example**: +```php +' . $js_code . ''; + } + echo $js_code; +} +?> + +``` + +### Custom Code via Joomla Template Settings + +You can also inject custom code via the Joomla admin interface: + +1. Navigate to **System → Site Templates → MokoCassiopeia** +2. Go to the **Custom Code** tab +3. Add custom HTML/CSS/JS in: + - **Custom Head Start**: Injected at the beginning of `` + - **Custom Head End**: Injected at the end of `` + +This approach is ideal for: +- Analytics tracking codes +- Custom meta tags +- External script includes +- Custom CSS snippets + +--- + +## 🔄 Syncing with Upstream Updates + +To keep your fork up-to-date with new features and bug fixes from the upstream MokoCassiopeia repository: + +### 1. Fetch Upstream Changes + +```bash +# Ensure upstream remote is configured +git remote -v +# If upstream is not listed, add it: +# git remote add upstream https://github.com/mokoconsulting-tech/MokoCassiopeia.git + +# Fetch latest changes +git fetch upstream +``` + +### 2. Review Changes + +```bash +# See what changed in upstream +git log HEAD..upstream/main --oneline + +# Review the diff +git diff HEAD..upstream/main +``` + +### 3. Merge Upstream Changes + +```bash +# Switch to your main branch +git checkout main + +# Merge upstream changes +git merge upstream/main + +# Or rebase (preserves cleaner history): +# git rebase upstream/main +``` + +### 4. Resolve Conflicts + +If conflicts occur (typically in custom files): + +1. **Check conflict status**: + ```bash + git status + ``` + +2. **Resolve conflicts manually** in your editor: + - Look for conflict markers: `<<<<<<<`, `=======`, `>>>>>>>` + - Keep your custom changes + - Remove conflict markers + +3. **Complete the merge**: + ```bash + git add . + git commit -m "Merge upstream updates and resolve conflicts" + ``` + +### 5. Test After Merging + +- Clear Joomla cache +- Test critical functionality: + - Homepage loads correctly + - Custom colors are preserved + - Dark mode toggle works + - Navigation functions properly + - Custom code still executes + +### Protected Files + +The following files contain your customizations and should be carefully reviewed during merges: + +- `src/media/css/colors/light/colors_custom.css` (custom light mode colors) +- `src/media/css/colors/dark/colors_custom.css` (custom dark mode colors) +- `src/templates/custom.php` (custom PHP code) +- Template configuration (stored in Joomla database, not in files) + +--- + +## 📦 Building & Deployment + +### Creating a Template Package + +To create an installable ZIP package of your customized template: + +1. **Prepare the package**: + ```bash + cd src + zip -r ../mokocassiopeia-[CLIENT-NAME]-[VERSION].zip . -x "*.git*" "*.DS_Store" + ``` + +2. **Install via Joomla**: + - Upload the ZIP file via **System → Install → Extensions** + - Or manually copy files to the Joomla installation + +### Deployment to Production + +**Recommended Deployment Methods**: + +1. **Via Joomla Extension Manager** (Easiest): + - Create a ZIP package as described above + - Upload via Joomla admin interface + - The template will automatically overwrite the existing installation + +2. **Via FTP/SFTP**: + - Upload changed files directly to the server + - Clear Joomla cache after deployment + +3. **Via Git** (Advanced): + - Push changes to a deployment branch + - Use Git hooks or CI/CD to deploy to production + - Ensure proper file permissions + +**Post-Deployment Checklist**: +- [ ] Clear Joomla cache (System → Clear Cache) +- [ ] Test homepage +- [ ] Test navigation and menus +- [ ] Verify custom colors appear correctly +- [ ] Test dark mode toggle +- [ ] Check mobile responsiveness +- [ ] Verify analytics tracking (if enabled) + +--- + +## 🛠 Local Development Setup + +### Setting Up a Local Joomla Environment + +1. **Install a local server stack**: + - **MAMP** (Mac/Windows): https://www.mamp.info/ + - **XAMPP** (Cross-platform): https://www.apachefriends.org/ + - **Docker**: https://github.com/joomla-docker/docker-joomla + +2. **Install Joomla**: + - Download Joomla from https://downloads.joomla.org/ + - Extract to your local server's web directory + - Follow the Joomla installation wizard + +3. **Install this template**: + - Copy files from this repository to your Joomla installation + - Or upload the ZIP package via Joomla's Extension Manager + +4. **Enable development mode**: + - Edit `configuration.php`: + ```php + public $debug = '1'; + public $error_reporting = 'maximum'; + ``` + +### Development Workflow + +1. **Make changes** to template files in your local Joomla installation +2. **Test changes** in your browser +3. **Copy changes back** to this repository: + ```bash + # From Joomla installation + cp [joomla]/templates/mokocassiopeia/* [repo]/src/templates/ + cp [joomla]/media/templates/site/mokocassiopeia/css/* [repo]/src/media/css/ + ``` +4. **Commit and push** to your fork +5. **Deploy** to staging/production when ready + +### Quick Testing Commands + +```bash +# Clear Joomla cache from command line +rm -rf [joomla]/cache/* +rm -rf [joomla]/administrator/cache/* + +# Watch for CSS changes (if using a build tool) +# npm run watch +``` + +--- + +## 📝 Customization Checklist + +Use this checklist when setting up or modifying your custom fork: + +### Initial Setup +- [ ] Fork the MokoCassiopeia repository +- [ ] Update this README with client name and details +- [ ] Configure custom brand colors +- [ ] Test light and dark modes +- [ ] Add custom code if needed +- [ ] Configure template settings in Joomla +- [ ] Set up analytics tracking (if required) +- [ ] Test on multiple devices and browsers + +### Ongoing Maintenance +- [ ] Sync with upstream periodically (monthly recommended) +- [ ] Review upstream changelog for breaking changes +- [ ] Test thoroughly after merging upstream updates +- [ ] Keep this README updated with customization notes +- [ ] Document any client-specific configurations +- [ ] Maintain backup before major updates + +--- + +## 📚 Documentation Resources + +### MokoCassiopeia Documentation + +- **[Main README](https://github.com/mokoconsulting-tech/MokoCassiopeia/blob/main/README.md)** - Features and overview +- **[CSS Variables Reference](./docs/CSS_VARIABLES.md)** - Complete CSS customization guide +- **[Development Guide](./docs/JOOMLA_DEVELOPMENT.md)** - Development and testing +- **[Quick Start](./docs/QUICK_START.md)** - Quick setup guide +- **[Changelog](./CHANGELOG.md)** - Version history + +### Joomla Resources + +- **[Joomla Documentation](https://docs.joomla.org/)** - Official Joomla docs +- **[Joomla Templates](https://docs.joomla.org/J4.x:How_to_Create_a_Joomla_Template)** - Template development guide +- **[Cassiopeia Documentation](https://docs.joomla.org/J4.x:Cassiopeia)** - Parent template docs + +--- + +## 🔒 Security & Best Practices + +### Security Considerations + +1. **Keep Joomla Updated**: Always run the latest stable Joomla version +2. **Update Dependencies**: Regularly sync with upstream MokoCassiopeia for security patches +3. **Secure Custom Code**: Review all custom code for security vulnerabilities +4. **Use HTTPS**: Always serve production sites over HTTPS +5. **Regular Backups**: Maintain regular backups of both files and database + +### Best Practices + +1. **Version Control**: Commit changes frequently with clear messages +2. **Testing**: Always test changes locally before deploying to production +3. **Documentation**: Document all customizations in this README +4. **Code Review**: Have changes reviewed before deploying to production +5. **Staging Environment**: Use a staging site to test updates before production + +--- + +## 📞 Support & Contact + +### Client-Specific Support + +**Client Contact**: [CLIENT CONTACT INFO] +**Developer Contact**: [DEVELOPER CONTACT INFO] +**Hosting Provider**: [HOSTING INFO] + +### Upstream MokoCassiopeia Support + +- **Repository**: https://github.com/mokoconsulting-tech/MokoCassiopeia +- **Issues**: https://github.com/mokoconsulting-tech/MokoCassiopeia/issues +- **Documentation**: https://github.com/mokoconsulting-tech/MokoCassiopeia/blob/main/README.md +- **Moko Consulting**: https://mokoconsulting.tech + +--- + +## 📄 License + +This fork maintains the original GPL-3.0-or-later license from MokoCassiopeia. + +- **MokoCassiopeia**: GPL-3.0-or-later +- **Client Customizations**: GPL-3.0-or-later (or as specified by client agreement) +- **Third-Party Libraries**: See [Included Libraries](https://github.com/mokoconsulting-tech/MokoCassiopeia#-included-libraries) + +--- + +## 📊 Fork Information + +- **Upstream Repository**: https://github.com/mokoconsulting-tech/MokoCassiopeia +- **Fork Repository**: [YOUR-FORK-URL] +- **Client**: [CLIENT NAME] +- **Created**: [DATE] +- **Last Synced with Upstream**: [DATE] +- **Current Version**: 03.06.03 + +--- + +## 🔄 Revision History + +| Date | Version | Change Summary | Author | +|------|---------|----------------|--------| +| [DATE] | 03.06.03 | Initial fork setup with custom colors and branding | [YOUR NAME] | + +--- + +**Maintained by [CLIENT NAME] / [DEVELOPER NAME]** diff --git a/README.md b/README.md index d1ef4b0..74aab56 100644 --- a/README.md +++ b/README.md @@ -328,9 +328,13 @@ See [Joomla Development Guide](./docs/JOOMLA_DEVELOPMENT.md) for packaging instr ### Customization Resources -- **[Template Files](./templates/)** - Ready-to-use color palette templates - - `colors_custom_light.css` - Light mode template - - `colors_custom_dark.css` - Dark mode template +- **[Template Files](./templates/)** - Ready-to-use templates for customization + - `colors_custom.css` - Custom color palette template + - `CLIENT_FORK_README_TEMPLATE.md` - Template for client fork documentation + +### Client Forks + +- **[Client Fork Guide](./CLIENT_FORK_README.md)** - Comprehensive guide for creating and maintaining client custom code forks ### Governance @@ -398,6 +402,14 @@ We welcome contributions! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for gu See [Workflow Guide](./docs/WORKFLOW_GUIDE.md) for detailed Git workflow. +### Client Custom Forks + +Creating a custom fork for client-specific branding and code? See our comprehensive [Client Fork Guide](./CLIENT_FORK_README.md) for: +- Setting up custom color schemes +- Maintaining fork-specific customizations +- Syncing with upstream updates +- Deployment workflows + --- ## 📦 Included Libraries diff --git a/docs/README.md b/docs/README.md index 4dceab9..87a11de 100644 --- a/docs/README.md +++ b/docs/README.md @@ -70,6 +70,15 @@ This directory contains comprehensive documentation for the MokoCassiopeia Jooml For end-user documentation, installation instructions, and feature guides, see the main [README.md](../README.md) in the repository root. +### Client Fork Documentation + +* **[Client Fork Guide](../CLIENT_FORK_README.md)** - Comprehensive guide for client custom code forks + * Setting up custom branding and colors + * Maintaining fork-specific customizations + * Syncing with upstream MokoCassiopeia + * Deployment and development workflows + * Template README for client forks + ## Project Structure ``` @@ -85,9 +94,10 @@ moko-cassiopeia/ │ ├── templates/ # Joomla template files │ └── media/ # Assets (CSS, JS, images) ├── templates/ # Template files for customization -│ ├── colors_custom_light.css # Light mode color template -│ └── colors_custom_dark.css # Dark mode color template +│ ├── colors_custom.css # Custom color palette template +│ └── CLIENT_FORK_README_TEMPLATE.md # Template for client fork docs ├── tests/ # Automated tests +├── CLIENT_FORK_README.md # Client fork guide └── .github/ # GitHub configuration and workflows ``` diff --git a/templates/CLIENT_FORK_README_TEMPLATE.md b/templates/CLIENT_FORK_README_TEMPLATE.md new file mode 100644 index 0000000..4b2d497 --- /dev/null +++ b/templates/CLIENT_FORK_README_TEMPLATE.md @@ -0,0 +1,57 @@ + + +# [CLIENT NAME] - MokoCassiopeia Custom + +Custom Joomla template fork for **[CLIENT NAME]**. + +--- + +## 🎨 Custom Branding + +**Brand Colors**: +- Primary: `[COLOR]` +- Accent: `[COLOR]` +- Background: `[COLOR]` + +**Custom Files**: +- Light mode colors: `src/media/css/colors/light/colors_custom.css` +- Dark mode colors: `src/media/css/colors/dark/colors_custom.css` +- Custom PHP code: `src/templates/custom.php` + +--- + +## 🔄 Syncing with Upstream + +```bash +# Add upstream remote (first time only) +git remote add upstream https://github.com/mokoconsulting-tech/MokoCassiopeia.git + +# Sync with upstream +git fetch upstream +git merge upstream/main +``` + +--- + +## 📚 Documentation + +- **Full Client Fork Guide**: [CLIENT_FORK_README.md](../CLIENT_FORK_README.md) +- **MokoCassiopeia Docs**: https://github.com/mokoconsulting-tech/MokoCassiopeia +- **CSS Variables**: [docs/CSS_VARIABLES.md](../docs/CSS_VARIABLES.md) + +--- + +## 📝 Quick Notes + +[Add your client-specific notes here] + +--- + +**Fork of**: [MokoCassiopeia](https://github.com/mokoconsulting-tech/MokoCassiopeia) v03.06.03 +**Last Synced**: [DATE] +**Contact**: [CONTACT INFO]