MokoConsulting/MokoSuiteClient
0
0
Fork 0
Code Issues 110 Pull Requests Releases 1 Wiki Activity

docs: testing guide, expanded overrides, updated config docs

Browse Source 
- 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) <noreply@anthropic.com>
This commit is contained in:
Jonathan Miller
2026-03-31 16:54:46 -05:00
parent 9542dd7f39
commit f1d06bba99
6 changed files with 322 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/guides/configuration-guide.md
+113 -35
View File
@@ -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 |
docs/guides/testing-guide.md
+175
View File
@@ -0,0 +1,175 @@
<!--
Copyright (C) 2025 Moko Consulting <hello@mokoconsulting.tech>
This file is part of a Moko Consulting project.
SPDX-LICENSE-IDENTIFIER: GPL-3.0-or-later
# FILE INFORMATION
DEFGROUP: Joomla.Plugin
INGROUP: MokoWaaS.Guides
REPO: https://github.com/mokoconsulting-tech/mokowaas
VERSION: 02.00.00
PATH: /docs/guides/testing-guide.md
BRIEF: Testing guide for MokoWaaS v02.00.00
NOTE: Covers manual test procedures for language overrides, install/uninstall, and configuration
-->
# 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 (`<script>`, `"`, `&`) | Characters appear escaped/safe, no XSS |
| 3 | Very long brand name (100+ chars) | Renders without breaking layout |
| 4 | Plugin disabled but override files exist | Sentinel block in Joomla override files still provides static branding |
| 5 | Multiple language tags installed (en-GB + en-US) | Both override files updated correctly |
| 6 | Non-English language tag (e.g., fr-FR) | No override file written (only en-GB/en-US supported); no errors |
## 4. Automated Validation
Run from the project root:
```bash
# Lint all PHP files
php -l src/script.php
php -l src/Extension/MokoWaaS.php
# Verify all override files have placeholders (no hardcoded "MokoWaaS" in values)
grep -r '"MokoWaaS' src/language/overrides/ src/administrator/language/overrides/
# Expected: no output (all values should use {{BRAND_NAME}})
# Verify sentinel constants match
grep -c 'BLOCK_START\|BLOCK_END' src/script.php
# Expected: 6+ references
# Verify all .ini files have version 02.00.00
grep -r 'Version:' src/**/*.ini | grep -v '02.00.00'
# Expected: no output
```
## Revision History
| Version | Date | Author | Description |
| -------- | ---------- | ------------------------------- | ------------------------------- |
| 02.00.00 | 2026-03-31 | Jonathan Miller (@jmiller-moko) | Initial testing guide for v2.0 |
src/administrator/language/overrides/en-GB.override.ini
+9
View File
@@ -83,6 +83,15 @@ COM_CONFIG_FIELD_METAVERSION_LABEL="{{BRAND_NAME}} Version"
; ===== Update component =====
COM_JOOMLAUPDATE_CONFIGURATION="{{BRAND_NAME}} Update: Options"
COM_JOOMLAUPDATE_CONFIG_UPDATESOURCE_NEXT="{{BRAND_NAME}} Next"
COM_JOOMLAUPDATE_CONFIG_SOURCES_DESC="Configure where {{BRAND_NAME}} gets its update information from."
COM_JOOMLAUPDATE_CONFIG_UPDATESOURCE_LABEL="Update Channel"
COM_JOOMLAUPDATE_VIEW_DEFAULT_TITLE="{{BRAND_NAME}} Update"
COM_JOOMLAUPDATE_VIEW_DEFAULT_DESCRIPTION="{{BRAND_NAME}} Update Component"
COM_JOOMLAUPDATE_NOCHANGE="{{BRAND_NAME}} is up to date."
COM_JOOMLAUPDATE_PREUPDATE_CHECK="{{BRAND_NAME}} Pre-Update Check"
COM_JOOMLAUPDATE_UPDATE_HEADER="{{BRAND_NAME}} Update"
COM_JOOMLAUPDATE_LIVEUPDATE="Live Update"
COM_JOOMLAUPDATE_CHECKEDFOR_UPDATES="Checked for {{BRAND_NAME}} updates."
; ===== Privacy =====
COM_PRIVACY_HEADING_CORE_CAPABILITIES="{{BRAND_NAME}} Core Capabilities"
src/administrator/language/overrides/en-US.override.ini
+9
View File
@@ -83,6 +83,15 @@ COM_CONFIG_FIELD_METAVERSION_LABEL="{{BRAND_NAME}} Version"
; ===== Update component =====
COM_JOOMLAUPDATE_CONFIGURATION="{{BRAND_NAME}} Update: Options"
COM_JOOMLAUPDATE_CONFIG_UPDATESOURCE_NEXT="{{BRAND_NAME}} Next"
COM_JOOMLAUPDATE_CONFIG_SOURCES_DESC="Configure where {{BRAND_NAME}} gets its update information from."
COM_JOOMLAUPDATE_CONFIG_UPDATESOURCE_LABEL="Update Channel"
COM_JOOMLAUPDATE_VIEW_DEFAULT_TITLE="{{BRAND_NAME}} Update"
COM_JOOMLAUPDATE_VIEW_DEFAULT_DESCRIPTION="{{BRAND_NAME}} Update Component"
COM_JOOMLAUPDATE_NOCHANGE="{{BRAND_NAME}} is up to date."
COM_JOOMLAUPDATE_PREUPDATE_CHECK="{{BRAND_NAME}} Pre-Update Check"
COM_JOOMLAUPDATE_UPDATE_HEADER="{{BRAND_NAME}} Update"
COM_JOOMLAUPDATE_LIVEUPDATE="Live Update"
COM_JOOMLAUPDATE_CHECKEDFOR_UPDATES="Checked for {{BRAND_NAME}} updates."
; ===== Privacy =====
COM_PRIVACY_HEADING_CORE_CAPABILITIES="{{BRAND_NAME}} Core Capabilities"
src/language/overrides/en-GB.override.ini
+8
View File
@@ -43,5 +43,13 @@ MOD_LOGINSUPPORT_FORUM="{{COMPANY_NAME}} Support"
MOD_LOGINSUPPORT_DOCUMENTATION="{{BRAND_NAME}} Documentation"
MOD_LOGINSUPPORT_NEWS="{{COMPANY_NAME}} News"
; ===== Site offline =====
JOFFLINE_MESSAGE="This site is down for maintenance.<br>Please check back again soon."
; ===== Error pages =====
JERROR_PAGE_NOT_FOUND="Page Not Found"
JERROR_AN_ERROR_HAS_OCCURRED="An error has occurred."
JLIB_APPLICATION_ERROR_COMPONENT_NOT_FOUND="Component not found."
; ===== Version and About =====
JLIB_HTML_POWERED_BY="Powered by {{BRAND_NAME}}"
src/language/overrides/en-US.override.ini
+8
View File
@@ -43,5 +43,13 @@ MOD_LOGINSUPPORT_FORUM="{{COMPANY_NAME}} Support"
MOD_LOGINSUPPORT_DOCUMENTATION="{{BRAND_NAME}} Documentation"
MOD_LOGINSUPPORT_NEWS="{{COMPANY_NAME}} News"
; ===== Site offline =====
JOFFLINE_MESSAGE="This site is down for maintenance.<br>Please check back again soon."
; ===== Error pages =====
JERROR_PAGE_NOT_FOUND="Page Not Found"
JERROR_AN_ERROR_HAS_OCCURRED="An error has occurred."
JLIB_APPLICATION_ERROR_COMPONENT_NOT_FOUND="Component not found."
; ===== Version and About =====
JLIB_HTML_POWERED_BY="Powered by {{BRAND_NAME}}"