Jonathan Miller
3a30f1a088
# Conflicts: # .mokogitea/cascade-dev.yml # src/templateDetails.xml # updates.xml
5.2 KiB
Migration from MokoCassiopeia
MokoOnyx is the successor to MokoCassiopeia. The migration runs automatically during install/update -- no manual steps are required beyond installing MokoOnyx.
When Does Migration Run?
The migration runs in the postflight() method of the installer script (script.php), which executes during both install and update operations. It checks for existing MokoCassiopeia template styles in the database and only runs if they are found.
What Gets Migrated
1. Template Styles and Parameters
- All MokoCassiopeia template styles are detected from the
#__template_stylestable - For each MokoCassiopeia style, a matching MokoOnyx style is created with the same parameters
- The first MokoCassiopeia style's parameters are applied to the installer-created default MokoOnyx style
- Additional styles are created as new entries
- Parameter values are updated to replace
mokocassiopeiareferences withmokoonyx
2. Default Template Assignment
If MokoCassiopeia was set as the default site template (home = 1), MokoOnyx automatically takes over as the default. The MokoCassiopeia style is unset as default.
3. Custom User Files
The following files are copied from the MokoCassiopeia media directory to MokoOnyx (only if the destination file does not already exist):
| File | Purpose |
|---|---|
css/theme/light.custom.css |
Custom light palette |
css/theme/dark.custom.css |
Custom dark palette |
css/theme/light.custom.min.css |
Minified custom light palette |
css/theme/dark.custom.min.css |
Minified custom dark palette |
css/user.css |
Custom CSS overrides |
css/user.min.css |
Minified custom CSS |
js/user.js |
Custom JavaScript |
js/user.min.js |
Minified custom JavaScript |
Source: media/templates/site/mokocassiopeia/
Destination: media/templates/site/mokoonyx/
4. Content References
All references to "MokoCassiopeia" and "mokocassiopeia" in article content (introtext and fulltext columns) and module content are automatically replaced with "MokoOnyx" and "mokoonyx". This covers:
- Image paths (e.g.,
media/templates/site/mokocassiopeia/...) - Template name references in custom HTML modules
- Any other text references in content
5. Additional Post-Install Tasks
These tasks run during every install/update (not just migration):
| Task | Description |
|---|---|
| Favicon stamp cleared | Deletes .favicon_generated stamp so favicons regenerate. Also removes the old /images/favicons/ directory and root-level favicon files from previous versions. |
| Media folder cleaned | Removes stale .min.css and .min.js files (regenerated by MokoMinifyHelper), unminified vendor files, and deprecated files (custom.css, custom.js, template-rtl.css). |
| Extension locked | Sets locked = 1 in #__extensions to prevent accidental uninstallation. |
How to Trigger Migration
Migration runs automatically during installation. If you need to observe the results:
- Install MokoOnyx via System → Install → Extensions
- Go to System → Site Templates and verify MokoOnyx appears with your settings
- Visit any page on your site to confirm the template is active
- Check administrator/logs/mokoonyx.log.php for migration log entries
Re-Running Migration
The migration runs on every install/update operation via the postflight() method. It is safe to re-run because:
- Style creation checks for existing styles before creating duplicates
- File copies only occur when the destination file does not exist
- Content replacements are idempotent (replacing "MokoOnyx" with "MokoOnyx" is a no-op)
To force a fresh migration, you can reinstall MokoOnyx by uploading the ZIP package again.
After Migration
Once you have confirmed everything is working:
- Uninstall MokoCassiopeia from Extensions → Manage
- Optionally clean up any remaining MokoCassiopeia files in
media/templates/site/mokocassiopeia/
Troubleshooting
| Issue | Solution |
|---|---|
| Settings not migrated | Check administrator/logs/mokoonyx.log.php for error messages. Verify MokoCassiopeia styles exist in #__template_styles. |
| Custom theme files missing | Verify files exist in media/templates/site/mokocassiopeia/css/theme/. The copy only runs if the destination does not already exist -- if MokoOnyx files are already present, they are not overwritten. |
| Content references not updated | Check the log for "Content replacement failed" or "Module replacement failed" warnings. Database permissions may be insufficient. |
| PHP version error | MokoOnyx requires PHP 8.1+. The preflight check blocks installation if this is not met. |
| Joomla version error | MokoOnyx requires Joomla 4.4+. The preflight check blocks installation if this is not met. |
Built with moko-platform -- Moko Consulting
Repo: MokoOnyx · moko-platform
| Revision | Date | Author | Description |
|---|---|---|---|
| 1.0 | 2026-05-09 | Moko Consulting | Initial version |