Jonathan Miller
3a30f1a088
Joomla: Extension CI / Tests (PHP 8.2) (pull_request) Has been cancelled
Joomla: Extension CI / Tests (PHP 8.3) (pull_request) Has been cancelled
Joomla: Extension CI / PHPStan Analysis (pull_request) Has been cancelled
Joomla: Extension CI / Build RC Pre-Release (pull_request) Has been cancelled
Generic: Repo Health / Release configuration (push) Has been cancelled
Generic: Repo Health / Scripts governance (push) Has been cancelled
Generic: Repo Health / Repository health (push) Has been cancelled
Universal: PR Check / Build RC Package (pull_request) Has been cancelled
Generic: Repo Health / Release configuration (pull_request) Has been cancelled
Generic: Repo Health / Scripts governance (pull_request) Has been cancelled
Generic: Repo Health / Repository health (pull_request) Has been cancelled
Generic: Repo Health / Site Health (push) Has been cancelled
Generic: Repo Health / Site Health (pull_request) Has been cancelled
Generic: Repo Health / Access control (push) Has been cancelled
Universal: PR Check / Branch Policy (pull_request) Has been cancelled
Generic: Repo Health / Access control (pull_request) Has been cancelled
Universal: Auto Version Bump / Version Bump (push) Has been cancelled
Joomla: Extension CI / Release Readiness Check (pull_request) Has been cancelled
Universal: Secret Scanning / Gitleaks Secret Scan (pull_request) Has been cancelled
Universal: PR Check / Validate PR (pull_request) Has been cancelled
Update Server / Update Server (push) Has been cancelled
Joomla: Extension CI / Lint & Validate (pull_request) Has been cancelled
# Conflicts: # .mokogitea/cascade-dev.yml # src/templateDetails.xml # updates.xml
120 lines
5.2 KiB
Markdown
120 lines
5.2 KiB
Markdown
[← Back to Home](Home)
|
|
|
|
# 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_styles` table
|
|
- 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 `mokocassiopeia` references with `mokoonyx`
|
|
|
|
### 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:
|
|
|
|
1. Install MokoOnyx via **System → Install → Extensions**
|
|
2. Go to **System → Site Templates** and verify MokoOnyx appears with your settings
|
|
3. Visit any page on your site to confirm the template is active
|
|
4. 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:
|
|
|
|
1. Uninstall MokoCassiopeia from **Extensions → Manage**
|
|
2. 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](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) -- Moko Consulting*
|
|
|
|
---
|
|
|
|
*Repo: [MokoOnyx](https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx) · [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)*
|
|
|
|
| Revision | Date | Author | Description |
|
|
|---|---|---|---|
|
|
| 1.0 | 2026-05-09 | Moko Consulting | Initial version |
|