From f1d06bba99ff9ee48c607b73f8863a0c2735c4dd Mon Sep 17 00:00:00 2001 From: Jonathan Miller <230051081+jmiller-moko@users.noreply.github.com> Date: Tue, 31 Mar 2026 16:54:46 -0500 Subject: [PATCH] docs: testing guide, expanded overrides, updated config docs - Added testing guide with 10 test suites covering install, uninstall, config changes, override preservation, and key coverage - Expanded admin overrides with 9 more Joomla Update component keys - Added frontend offline page and error page override keys - Updated configuration guide to v02.00.00 documenting brand_name, company_name, support_url params and two-layer override system Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/guides/configuration-guide.md | 148 +++++++++++---- docs/guides/testing-guide.md | 175 ++++++++++++++++++ .../language/overrides/en-GB.override.ini | 9 + .../language/overrides/en-US.override.ini | 9 + src/language/overrides/en-GB.override.ini | 8 + src/language/overrides/en-US.override.ini | 8 + 6 files changed, 322 insertions(+), 35 deletions(-) create mode 100644 docs/guides/testing-guide.md diff --git a/docs/guides/configuration-guide.md b/docs/guides/configuration-guide.md index ee2ebc97..20f7d166 100644 --- a/docs/guides/configuration-guide.md +++ b/docs/guides/configuration-guide.md @@ -10,13 +10,13 @@ DEFGROUP: Joomla.Plugin INGROUP: MokoWaaS.Guides REPO: https://github.com/mokoconsulting-tech/mokowaas - VERSION: 01.04.00 + VERSION: 02.00.00 PATH: /docs/guides/configuration-guide.md BRIEF: Configuration guide for the MokoWaaS system plugin NOTE: Defines plugin parameters, expected behaviors, and recommended defaults --> -# MokoWaaS Configuration Guide (VERSION: 01.04.00) +# MokoWaaS Configuration Guide (VERSION: 02.00.00) ## 1. Objective @@ -29,77 +29,155 @@ This guide outlines the configuration parameters available within the MokoWaaS s 3. Search for **MokoWaaS**. 4. Select the plugin name to open the configuration panel. -## 3. Configuration Sections +## 3. Plugin Parameters -The plugin provides several configuration areas designed to control branding behavior. +### 3.1 Enable Branding -### 3.1 Brand Terminology Controls +| Property | Value | +| -------- | ----- | +| Field name | `enable_branding` | +| Type | Radio (Yes/No) | +| Default | Yes | -These toggles replace Joomla native labels with WaaS aligned naming conventions. +Master switch for all branding overrides. When disabled, no language overrides are applied and the Joomla interface reverts to its default strings. -Use cases include: +### 3.2 Brand Name -* Standardizing administrator UI language -* Reinforcing WaaS platform identity across components +| Property | Value | +| -------- | ----- | +| Field name | `brand_name` | +| Type | Text | +| Default | `MokoWaaS` | -Recommended Default: **Enabled** +The brand name that replaces "Joomla" throughout the interface. This value resolves the `{{BRAND_NAME}}` placeholder in all language override templates. -### 3.2 Footer and Attribution Controls +**Affected areas:** +* Admin and site footer ("Powered by …") +* Control panel greetings +* Quick icon status messages +* System info and version labels +* Installer and update component text +* Error pages and system messages +* Privacy component headings -Controls platform level branding elements including: +### 3.3 Company Name -* Footer identification -* Powered By statements -* Attribution placements +| Property | Value | +| -------- | ----- | +| Field name | `company_name` | +| Type | Text | +| Default | `Moko Consulting` | -Recommended Default: **Enabled** +Your company name, used in support links and attribution. Resolves the `{{COMPANY_NAME}}` placeholder. -### 3.3 Visibility Controls +**Affected areas:** +* Admin login support links (forum, documentation, news) +* Frontend login support links -Options for concealing or modifying native Joomla identifiers when appropriate. +### 3.4 Support URL -Examples include: +| Property | Value | +| -------- | ----- | +| Field name | `support_url` | +| Type | URL | +| Default | `https://mokoconsulting.tech` | -* Hiding Joomla version labels -* Suppressing default metadata references +URL for support and documentation links. Resolves the `{{SUPPORT_URL}}` placeholder. -Recommended Default: **Enabled** for WaaS managed sites. +**Affected areas:** +* Dashboard welcome message links +* Documentation and support links -### 3.4 Rendering Enhancements +## 4. How Overrides Work -Controls adjustments to UI elements to ensure consistent presentation. +MokoWaaS uses a two-layer override system: -Examples: +### 4.1 Runtime Resolution (Primary) -* Header text alignment -* Replacement of naming strings +On every page load, the plugin reads override template files shipped with the plugin, resolves `{{BRAND_NAME}}`, `{{COMPANY_NAME}}`, and `{{SUPPORT_URL}}` from plugin params, and injects the resolved strings into Joomla's Language object. -Recommended Default: **Enabled** +**Effect:** Changing the brand name in plugin config takes effect on the next page load — no reinstall needed. -## 4. Configuration Change Workflow +### 4.2 Install-time Resolution (Fallback) + +During install/update, the install script resolves placeholders and writes the result into Joomla's global language override files inside a sentinel block: + +```ini +; ===== BEGIN MokoWaaS Overrides (do not edit this block) ===== +; Auto-generated on 2026-03-31 12:00:00 — do not edit manually. +TPL_ATUM_POWERED_BY="Powered by MokoWaaS" +... +; ===== END MokoWaaS Overrides ===== +``` + +Existing overrides outside this block are never touched. On uninstall, only the MokoWaaS block (and any legacy stray keys) are removed. + +## 5. Override Coverage + +### 5.1 Admin Overrides (administrator/language/overrides/) + +| Section | Keys | Description | +| ------- | ---- | ----------- | +| Footer & template | 2 | Powered by text in Atum template | +| Control panel | 5 | Welcome messages, beginners guide, stats | +| Help/Docs | 2 | Help site labels | +| Generic | 3 | Defaults, package type, library name | +| System messages | 2 | Error and field labels | +| Admin login | 4 | Login support links and page title | +| Error messages | 1 | Generic error layout | +| Admin branding | 4 | Control panel title, module/plugin headings | +| Extensions | 2 | Installer type and success message | +| Quick Icons | 3 | Update check status messages | +| System Info | 3 | Version, help, compat plugin | +| Installer | 5 | Upload, warnings, update notices | +| Global Config | 1 | Meta version label | +| Update component | 11 | Titles, descriptions, status messages | +| Privacy | 1 | Core capabilities heading | +| Library errors | 2 | Minimum version, XML setup file | +| Version/About | 3 | Powered by, documentation, support | + +### 5.2 Site/Frontend Overrides (language/overrides/) + +| Section | Keys | Description | +| ------- | ---- | ----------- | +| Footer & template | 2 | Powered by text in Cassiopeia template | +| Generic | 2 | Defaults, library name | +| System messages | 2 | Error and field labels | +| Error messages/pages | 4 | Error layout, 404, generic errors | +| Installer/Sample data | 6 | Site name, sample data sets | +| Login support | 3 | Forum, documentation, news links | +| Site offline | 1 | Maintenance message | +| Version/About | 1 | Powered by text | + +## 6. Configuration Change Workflow To ensure continuity across managed environments: 1. Document the change request. 2. Apply updates in a staging environment. -3. Validate branding presentation. +3. Validate branding presentation across admin and frontend. 4. Promote changes to production following WaaS change controls. -## 5. Troubleshooting Configuration Issues +## 7. Troubleshooting Configuration Issues * If changes do not appear, clear Joomla and browser cache. * Confirm that no template override is superseding plugin outputs. * Review logs for load order conflicts. * Confirm that extension priority does not conflict with other system plugins. +* If brand name change doesn't take effect, verify the plugin is enabled and the `enable_branding` param is set to Yes. -## 6. Validation Checklist +## 8. Validation Checklist -* Branding reads consistently across administrator screens. -* No Joomla specific identifiers remain where replacement is expected. -* Frontend and backend output align with WaaS design expectations. +* Brand name appears consistently across all administrator screens. +* Company name appears in login support links. +* Support URL points to correct destination. +* No "Joomla" identifiers remain in overridden locations. +* Frontend and backend output align with configured brand values. +* Existing site language overrides (outside the MokoWaaS block) are preserved. ## Revision History | Version | Date | Author | Description | | -------- | ---------- | ------------------------------- | ---------------------------------------------- | | 01.02.00 | 2025-12-11 | Jonathan Miller (@jmiller-moko) | Initial standalone configuration guide created | +| 02.00.00 | 2026-03-31 | Jonathan Miller (@jmiller-moko) | Template-based overrides, configurable brand name/company/URL, expanded override coverage | diff --git a/docs/guides/testing-guide.md b/docs/guides/testing-guide.md new file mode 100644 index 00000000..bb07de83 --- /dev/null +++ b/docs/guides/testing-guide.md @@ -0,0 +1,175 @@ + + +# MokoWaaS Testing Guide (VERSION: 02.00.00) + +## 1. Prerequisites + +| Requirement | Minimum | +| ----------- | ------- | +| Joomla | 5.0.0 | +| PHP | 8.1.0 | +| Browser | Latest Chrome, Firefox, or Safari | + +### 1.1 Test Environment Setup + +1. Clean Joomla 5.x installation OR existing site with custom language overrides. +2. Admin account with Super User access. +3. Build the plugin package: `make package` or zip the `src/` directory. + +## 2. Test Suites + +### 2.1 Fresh Install + +| # | Step | Expected Result | Pass | +|---|------|-----------------|------| +| 1 | Install plugin via Extensions > Install | "Installed frontend language overrides for en-GB" and "Installed administrator language overrides for en-GB" messages | [ ] | +| 2 | Navigate to Extensions > Plugins | Plugin appears as "System - MokoWaaS" (not raw key `PLG_SYSTEM_MOKOWAAS`) | [ ] | +| 3 | Open plugin config | Three fields visible: Brand Name (default "MokoWaaS"), Company Name (default "Moko Consulting"), Support URL (default "https://mokoconsulting.tech") | [ ] | +| 4 | Check admin dashboard | "Welcome to MokoWaaS!" appears in control panel | [ ] | +| 5 | Check admin footer | "Powered by MokoWaaS" appears | [ ] | +| 6 | Check admin login page | "MokoWaaS Administrator Login" title, support links show "Moko Consulting" | [ ] | +| 7 | Check frontend footer | "Powered by MokoWaaS" in Cassiopeia template | [ ] | +| 8 | Check Joomla override files at `administrator/language/overrides/en-GB.override.ini` | Contains `BEGIN MokoWaaS Overrides` sentinel block | [ ] | +| 9 | Check Joomla override files at `language/overrides/en-GB.override.ini` | Contains `BEGIN MokoWaaS Overrides` sentinel block | [ ] | + +### 2.2 Override Preservation (Install on Site with Existing Overrides) + +| # | Step | Expected Result | Pass | +|---|------|-----------------|------| +| 1 | Before install: add a custom override `MY_CUSTOM_KEY="My Value"` to `administrator/language/overrides/en-GB.override.ini` | Override file contains custom key | [ ] | +| 2 | Install MokoWaaS plugin | Success messages shown | [ ] | +| 3 | Open `administrator/language/overrides/en-GB.override.ini` | `MY_CUSTOM_KEY="My Value"` still present AND MokoWaaS sentinel block appended at end | [ ] | +| 4 | In Joomla admin: System > Language Overrides | Custom override still visible and functional | [ ] | + +### 2.3 Brand Name Configuration + +| # | Step | Expected Result | Pass | +|---|------|-----------------|------| +| 1 | Open plugin config, change Brand Name to "TestBrand" | Field accepts the value | [ ] | +| 2 | Save and close plugin config | Save succeeds | [ ] | +| 3 | Reload admin dashboard | "Welcome to TestBrand!" appears (not "MokoWaaS") | [ ] | +| 4 | Check admin footer | "Powered by TestBrand" | [ ] | +| 5 | Check frontend page | "Powered by TestBrand" in footer | [ ] | +| 6 | Check Quick Icons area | "TestBrand is up to date." | [ ] | +| 7 | Navigate to System > System Information | "TestBrand Version" label | [ ] | + +### 2.4 Company Name Configuration + +| # | Step | Expected Result | Pass | +|---|------|-----------------|------| +| 1 | Change Company Name to "TestCo" in plugin config, save | Save succeeds | [ ] | +| 2 | Check admin login page support links | "TestCo Support", "TestCo News" | [ ] | +| 3 | Check frontend login module (if enabled) | "TestCo Support", "TestCo News" | [ ] | + +### 2.5 Support URL Configuration + +| # | Step | Expected Result | Pass | +|---|------|-----------------|------| +| 1 | Change Support URL to "https://example.com" in plugin config, save | Save succeeds | [ ] | +| 2 | Check admin dashboard welcome message | Links point to "https://example.com" | [ ] | + +### 2.6 Enable/Disable Branding + +| # | Step | Expected Result | Pass | +|---|------|-----------------|------| +| 1 | Set Enable Branding to "No", save | Save succeeds | [ ] | +| 2 | Reload admin dashboard | Default Joomla strings appear (e.g., "Welcome to Joomla!") | [ ] | +| 3 | Check frontend footer | Default "Powered by Joomla" or Cassiopeia default | [ ] | +| 4 | Set Enable Branding back to "Yes", save | Branding strings restored immediately | [ ] | + +### 2.7 Update (Upgrade from Previous Version) + +| # | Step | Expected Result | Pass | +|---|------|-----------------|------| +| 1 | Install v01.x of MokoWaaS first | Old version installed | [ ] | +| 2 | Install v02.00.00 over it | Upgrade succeeds with "Installed" messages | [ ] | +| 3 | Check override files | MokoWaaS sentinel block present, no duplicate keys | [ ] | +| 4 | Verify old inline overrides (from v01.x) are cleaned up | No stray MokoWaaS keys outside the sentinel block | [ ] | + +### 2.8 Uninstall + +| # | Step | Expected Result | Pass | +|---|------|-----------------|------| +| 1 | Uninstall MokoWaaS via Extensions > Manage | "Removed frontend language overrides" and "Removed administrator language overrides" messages | [ ] | +| 2 | Check `administrator/language/overrides/en-GB.override.ini` | MokoWaaS sentinel block removed; any custom overrides (e.g., `MY_CUSTOM_KEY`) still present | [ ] | +| 3 | Check `language/overrides/en-GB.override.ini` | MokoWaaS block removed; file deleted if no other overrides remain | [ ] | +| 4 | Reload admin dashboard | Default Joomla strings restored | [ ] | + +### 2.9 Admin Override Key Coverage + +Verify the following admin areas no longer show "Joomla": + +| # | Location | Expected Brand Text | Pass | +|---|----------|-------------------|------| +| 1 | Admin footer | "Powered by {brand}" | [ ] | +| 2 | Dashboard greeting | "Welcome to {brand}!" | [ ] | +| 3 | Dashboard beginners box | "{brand} Documentation" / "{brand} Support" links | [ ] | +| 4 | Quick Icons | "Checking {brand}…" / "{brand} is up to date." | [ ] | +| 5 | System Information | "{brand} Version" | [ ] | +| 6 | Joomla Update page title | "{brand} Update" | [ ] | +| 7 | Extension Manager upload | "Upload & Install {brand} Extension" | [ ] | +| 8 | Global Configuration > meta | "{brand} Version" label | [ ] | +| 9 | Admin login page title | "{brand} Administrator Login" | [ ] | +| 10 | Login support links | "{company} Support" / "{company} News" | [ ] | +| 11 | Privacy component | "{brand} Core Capabilities" | [ ] | + +### 2.10 Frontend Override Key Coverage + +| # | Location | Expected Brand Text | Pass | +|---|----------|-------------------|------| +| 1 | Cassiopeia footer | "Powered by {brand}" | [ ] | +| 2 | Site offline page | Maintenance message (no Joomla reference) | [ ] | +| 3 | 404 error page | "Page Not Found" (no Joomla reference) | [ ] | +| 4 | Frontend login support | "{company} Support" / "{brand} Documentation" | [ ] | + +## 3. Edge Cases + +| # | Scenario | Expected Behavior | +|---|----------|-------------------| +| 1 | Brand Name field left empty | Falls back to default "MokoWaaS" | +| 2 | Brand Name with special characters (`