MokoConsulting/MokoCassiopeia
1
1
Fork 0
Code Issues 4 Pull Requests Actions Packages Releases 1 Activity
Files
a5ffa1fe75124a08f00bf54754d4ec51a582c76b
MokoCassiopeia/CLIENT_FORK_README.md
copilot-swe-agent[bot] f1c1841cea Fix workflow YAML syntax and update documentation references 
Co-authored-by: jmiller-moko <230051081+jmiller-moko@users.noreply.github.com>
2026-02-20 01:39:36 +00:00

13 KiB
Raw Blame History

[CLIENT NAME] - MokoCassiopeia Custom Fork

Custom Joomla Template Fork for [CLIENT NAME]

This is a customized fork of the MokoCassiopeia Joomla template, tailored specifically for [CLIENT NAME]'s website.

💡 Tip: This fork was likely created using the automated Client Fork Workflow. If you're creating a new client fork, use the workflow for instant setup!

📋 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:

    git clone [YOUR-FORK-URL]
cd [YOUR-FORK-NAME]

  2. Set up upstream remote (for syncing updates):

    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:

    # 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:

    :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 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
// Custom helper function
function console_log($output, $with_script_tags = true) {
    $js_code = 'console.log(' . json_encode($output, JSON_HEX_TAG) . ');';
    if ($with_script_tags) {
        $js_code = '<script>' . $js_code . '</script>';
    }
    echo $js_code;
}
?>
<!--
    Custom HTML code can be added here
-->

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 <head>
    • Custom Head End: Injected at the end of <head>

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

# 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

# See what changed in upstream
git log HEAD..upstream/main --oneline

# Review the diff
git diff HEAD..upstream/main

3. Merge Upstream Changes

# 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:

    git status

  2. Resolve conflicts manually in your editor:

    • Look for conflict markers: <<<<<<<, =======, >>>>>>>
    • Keep your custom changes
    • Remove conflict markers

  3. Complete the merge:

    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:

    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:

  2. Install Joomla:

  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: 
      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: 
    # 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

# 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

Joomla Resources

🔒 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

📄 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

📊 Fork Information

🔄 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]

Reference in New Issue View Git Blame Copy Permalink