From 86db2d5b1a4004010056e19b59c8541921e89ed6 Mon Sep 17 00:00:00 2001 From: Jonathan Miller Date: Sat, 16 May 2026 18:58:15 +0000 Subject: [PATCH 1/5] =?UTF-8?q?chore(version):=20bump=2002.06.00=20?= =?UTF-8?q?=E2=86=92=2002.07.00=20(dev)=20[skip=20ci]?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 34a607a..4444813 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ A modern, lightweight Joomla site template built on Cassiopeia with Font Awesome | | | |---|---| | **Type** | Joomla Site Template | -| **Version** | 02.06.00 | +| **Version** | 02.07.00 | | **Joomla** | 5.x / 6.x | | **PHP** | 8.1+ | | **License** | GPL-3.0-or-later | From d4f243233216a4964293138e70cffc61a3cba7bb Mon Sep 17 00:00:00 2001 From: Jonathan Miller Date: Sat, 16 May 2026 18:58:15 +0000 Subject: [PATCH 2/5] =?UTF-8?q?chore(version):=20bump=2002.06.00=20?= =?UTF-8?q?=E2=86=92=2002.07.00=20(dev)=20[skip=20ci]?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/templateDetails.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/templateDetails.xml b/src/templateDetails.xml index fcddc0d..816c9de 100644 --- a/src/templateDetails.xml +++ b/src/templateDetails.xml @@ -36,7 +36,7 @@ MokoOnyx - 02.06.00 + 02.07.00 script.php 2026-05-16 Jonathan Miller || Moko Consulting From 7b52a06cc18decf6c3bb0f36d463bf04e97cc096 Mon Sep 17 00:00:00 2001 From: Jonathan Miller Date: Sat, 16 May 2026 14:33:55 -0500 Subject: [PATCH 3/5] fix(menu): remove hardcoded p-2 padding from menu icon spans The menu override templates were adding Bootstrap p-2 (padding) class to all menu icon spans, causing unwanted spacing around Font Awesome icons in navigation items. Icons should inherit their spacing from the surrounding link element, not add their own padding. Affected files: all mod_menu layout overrides (mainmenu_*, horizontal_*) Co-Authored-By: Claude Opus 4.6 (1M context) --- src/html/mod_menu/horizontal_component.php | 4 ++-- src/html/mod_menu/horizontal_heading.php | 4 ++-- src/html/mod_menu/horizontal_separator.php | 4 ++-- src/html/mod_menu/horizontal_url.php | 4 ++-- src/html/mod_menu/mainmenu_component.php | 4 ++-- src/html/mod_menu/mainmenu_heading.php | 4 ++-- src/html/mod_menu/mainmenu_separator.php | 4 ++-- src/html/mod_menu/mainmenu_url.php | 4 ++-- 8 files changed, 16 insertions(+), 16 deletions(-) diff --git a/src/html/mod_menu/horizontal_component.php b/src/html/mod_menu/horizontal_component.php index dfcfa7f..d2887cb 100644 --- a/src/html/mod_menu/horizontal_component.php +++ b/src/html/mod_menu/horizontal_component.php @@ -36,10 +36,10 @@ if ($item->menu_icon) { // The link is an icon if ($itemParams->get('menu_text', 1)) { // If the link text is to be displayed, the icon is added with aria-hidden - $linktype = '' . $item->title; + $linktype = '' . $item->title; } else { // If the icon itself is the link, it needs a visually hidden text - $linktype = ''; + $linktype = ''; } } diff --git a/src/html/mod_menu/horizontal_heading.php b/src/html/mod_menu/horizontal_heading.php index 990077e..af61674 100644 --- a/src/html/mod_menu/horizontal_heading.php +++ b/src/html/mod_menu/horizontal_heading.php @@ -22,10 +22,10 @@ if ($item->menu_icon) { // The link is an icon if ($itemParams->get('menu_text', 1)) { // If the link text is to be displayed, the icon is added with aria-hidden - $linktype = '' . $item->title; + $linktype = '' . $item->title; } else { // If the icon itself is the link, it needs a visually hidden text - $linktype = ''; + $linktype = ''; } } diff --git a/src/html/mod_menu/horizontal_separator.php b/src/html/mod_menu/horizontal_separator.php index 2c0c587..42579b9 100644 --- a/src/html/mod_menu/horizontal_separator.php +++ b/src/html/mod_menu/horizontal_separator.php @@ -22,10 +22,10 @@ if ($item->menu_icon) { // The link is an icon if ($itemParams->get('menu_text', 1)) { // If the link text is to be displayed, the icon is added with aria-hidden - $linktype = '' . $item->title; + $linktype = '' . $item->title; } else { // If the icon itself is the link, it needs a visually hidden text - $linktype = ''; + $linktype = ''; } } diff --git a/src/html/mod_menu/horizontal_url.php b/src/html/mod_menu/horizontal_url.php index 10b380b..1d81553 100644 --- a/src/html/mod_menu/horizontal_url.php +++ b/src/html/mod_menu/horizontal_url.php @@ -36,10 +36,10 @@ if ($item->menu_icon) { // The link is an icon if ($itemParams->get('menu_text', 1)) { // If the link text is to be displayed, the icon is added with aria-hidden - $linktype = '' . $item->title; + $linktype = '' . $item->title; } else { // If the icon itself is the link, it needs a visually hidden text - $linktype = ''; + $linktype = ''; } } diff --git a/src/html/mod_menu/mainmenu_component.php b/src/html/mod_menu/mainmenu_component.php index dfcfa7f..d2887cb 100644 --- a/src/html/mod_menu/mainmenu_component.php +++ b/src/html/mod_menu/mainmenu_component.php @@ -36,10 +36,10 @@ if ($item->menu_icon) { // The link is an icon if ($itemParams->get('menu_text', 1)) { // If the link text is to be displayed, the icon is added with aria-hidden - $linktype = '' . $item->title; + $linktype = '' . $item->title; } else { // If the icon itself is the link, it needs a visually hidden text - $linktype = ''; + $linktype = ''; } } diff --git a/src/html/mod_menu/mainmenu_heading.php b/src/html/mod_menu/mainmenu_heading.php index 990077e..af61674 100644 --- a/src/html/mod_menu/mainmenu_heading.php +++ b/src/html/mod_menu/mainmenu_heading.php @@ -22,10 +22,10 @@ if ($item->menu_icon) { // The link is an icon if ($itemParams->get('menu_text', 1)) { // If the link text is to be displayed, the icon is added with aria-hidden - $linktype = '' . $item->title; + $linktype = '' . $item->title; } else { // If the icon itself is the link, it needs a visually hidden text - $linktype = ''; + $linktype = ''; } } diff --git a/src/html/mod_menu/mainmenu_separator.php b/src/html/mod_menu/mainmenu_separator.php index 2c0c587..42579b9 100644 --- a/src/html/mod_menu/mainmenu_separator.php +++ b/src/html/mod_menu/mainmenu_separator.php @@ -22,10 +22,10 @@ if ($item->menu_icon) { // The link is an icon if ($itemParams->get('menu_text', 1)) { // If the link text is to be displayed, the icon is added with aria-hidden - $linktype = '' . $item->title; + $linktype = '' . $item->title; } else { // If the icon itself is the link, it needs a visually hidden text - $linktype = ''; + $linktype = ''; } } diff --git a/src/html/mod_menu/mainmenu_url.php b/src/html/mod_menu/mainmenu_url.php index 10b380b..1d81553 100644 --- a/src/html/mod_menu/mainmenu_url.php +++ b/src/html/mod_menu/mainmenu_url.php @@ -36,10 +36,10 @@ if ($item->menu_icon) { // The link is an icon if ($itemParams->get('menu_text', 1)) { // If the link text is to be displayed, the icon is added with aria-hidden - $linktype = '' . $item->title; + $linktype = '' . $item->title; } else { // If the icon itself is the link, it needs a visually hidden text - $linktype = ''; + $linktype = ''; } } From 36593a6b3c1589d33ee090b28ec431109b9830f1 Mon Sep 17 00:00:00 2001 From: Jonathan Miller Date: Sat, 16 May 2026 14:37:49 -0500 Subject: [PATCH 4/5] docs: fix mangled CHANGELOG, add p-2 fix entry Rebuilt CHANGELOG structure after auto-promote corruption. Added proper version sections for 02.06.00, 02.02.00, and unreleased p-2 menu icon padding fix. Co-Authored-By: Claude Opus 4.6 (1M context) --- CHANGELOG.md | 41 +++++++++++++++++++++++++++++------------ 1 file changed, 29 insertions(+), 12 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c6b9331..45ac853 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,12 +1,4 @@ - -# CSS Variables Reference - MokoOnyx - -This document provides a complete reference of all CSS variables available in the MokoOnyx template for customization. - -## Table of Contents - -- [Using Custom Color Palettes](#using-custom-color-palettes) -- [Primary Brand Colors](#primary-brand-colors) -- [Link Colors](#link-colors) -- [Navigation Colors](#navigation-colors) -- [Navbar Variables](#navbar-variables) -- [Offcanvas Variables](#offcanvas-variables) -- [Header Background](#header-background) -- [Container Backgrounds](#container-backgrounds) -- [Bootstrap Color Palette](#bootstrap-color-palette) -- [Body & Typography](#body--typography) -- [Additional Theme Colors](#additional-theme-colors) -- [Borders & Shadows](#borders--shadows) -- [Button Utilities](#button-utilities) -- [Card Variables](#card-variables) -- [Form Colors](#form-colors) -- [Responsive Tokens & Breakpoints](#responsive-tokens--breakpoints) -- [VirtueMart Variables](#virtuemart-variables) -- [Gable Variables](#gable-variables) -- [Hero Variant Variables](#hero-variant-variables) -- [Block Color Variables](#block-color-variables) - ---- - -## Using Custom Color Palettes - -To create custom color schemes: - -1. **Copy template files** from `./templates/` directory: - - `light.custom.css` → `media/templates/site/mokoonyx/css/theme/light.custom.css` - - `dark.custom.css` → `media/templates/site/mokoonyx/css/theme/dark.custom.css` - -2. **Edit the variables** in the copied files to match your brand - -3. **Enable in Joomla**: - - Navigate to: System → Site Templates → MokoOnyx - - Under "Theme" tab, set palette to "Custom" - - Save changes - -4. **Note**: Custom files are gitignored and won't be committed to the repository - -5. **On upgrade**: When the template is updated, `script.php` automatically runs `sync_custom_vars.php` to detect any new variables added to the starter templates and inject them into your existing custom palette files. Your existing values are never overwritten — only genuinely new variables are added. You can also run this manually: - ```bash - php templates/mokoonyx/sync_custom_vars.php --dry-run # preview what would be added - php templates/mokoonyx/sync_custom_vars.php # apply missing variables - ``` - ---- - -## Primary Brand Colors - -### `--color-primary` -- **Description**: Main brand color used throughout the template -- **Light Mode Default**: `#112855` -- **Dark Mode Default**: `#112855` -- **Usage**: Headers, primary buttons, brand elements - -### `--accent-color-primary` -- **Description**: Primary accent color for interactive elements -- **Light Mode Default**: `#3f8ff0` -- **Dark Mode Default**: `#3f8ff0` -- **Usage**: Hover states, focus indicators, call-to-action elements - -### `--accent-color-secondary` -- **Description**: Secondary accent color -- **Light Mode Default**: `#3f8ff0` -- **Dark Mode Default**: `#6fb3ff` -- **Usage**: Secondary highlights, alternative styling - ---- - -## Link Colors - -### `--color-link` -- **Description**: Default color for hyperlinks -- **Light Mode Default**: `#224FAA` -- **Dark Mode Default**: `white` -- **Usage**: All text links in content - -### `--color-hover` -- **Description**: Color when hovering over links and interactive elements -- **Light Mode Default**: `var(--accent-color-primary)` -- **Dark Mode Default**: `gray` -- **Usage**: Hover states for links and buttons - -### `--color-active` -- **Description**: Color for active/selected links -- **Light Mode Default**: (not set) -- **Dark Mode Default**: `var(--mainmenu-nav-link-color)` -- **Usage**: Active navigation items, selected states - -### `--link-color` -- **Description**: Bootstrap-compatible link color variable -- **Light Mode Default**: `#224faa` -- **Dark Mode Default**: `#8ab4f8` -- **Usage**: Alternative link color variable for Bootstrap compatibility - -### `--link-hover-color` -- **Description**: Bootstrap-compatible hover color -- **Light Mode Default**: `#424077` -- **Dark Mode Default**: `#c3d6ff` -- **Usage**: Link hover state for Bootstrap components - ---- - -## Navigation Colors - -### `--mainmenu-nav-link-color` -- **Description**: Text color for main navigation menu -- **Light Mode Default**: `white` -- **Dark Mode Default**: `#fff` -- **Usage**: Navigation menu text - -### `--nav-text-color` -- **Description**: General navigation text color -- **Light Mode Default**: `white` -- **Dark Mode Default**: `gray` -- **Usage**: Navigation elements - -### `--nav-bg-color` -- **Description**: Background color for navigation bars -- **Light Mode Default**: `var(--color-link)` -- **Dark Mode Default**: `var(--color-primary)` -- **Usage**: Navigation background - ---- - -## Navbar Variables - -### `--navbar-padding-x` -- **Description**: Horizontal padding for navbar -- **Default**: `1rem` -- **Usage**: Navbar horizontal spacing - -### `--navbar-padding-y` -- **Description**: Vertical padding for navbar -- **Default**: `0.5rem` -- **Usage**: Navbar vertical spacing - -### `--navbar-color` -- **Description**: Default text color for navbar items -- **Light Mode Default**: `rgba(0, 0, 0, 0.55)` -- **Dark Mode Default**: `rgba(255, 255, 255, 0.55)` -- **Usage**: Navbar text color - -### `--navbar-active-color` -- **Description**: Text color for active navbar items -- **Light Mode Default**: `rgba(0, 0, 0, 0.9)` -- **Dark Mode Default**: `rgba(255, 255, 255, 0.9)` -- **Usage**: Active navbar item color - -### `--navbar-disabled-color` -- **Description**: Text color for disabled navbar items -- **Light Mode Default**: `rgba(0, 0, 0, 0.3)` -- **Dark Mode Default**: `rgba(255, 255, 255, 0.3)` -- **Usage**: Disabled navbar item color - -### `--navbar-brand-padding-y` -- **Description**: Vertical padding for navbar brand -- **Default**: `0.3125rem` -- **Usage**: Navbar brand vertical spacing - -### `--navbar-brand-margin-end` -- **Description**: Right margin for navbar brand -- **Default**: `1rem` -- **Usage**: Space after navbar brand - -### `--navbar-brand-font-size` -- **Description**: Font size for navbar brand -- **Default**: `1.25rem` -- **Usage**: Navbar brand text size - -### `--navbar-brand-color` -- **Description**: Color for navbar brand -- **Default**: Inherits from `--navbar-color` -- **Usage**: Navbar brand text color - -### `--navbar-brand-active-color` -- **Description**: Color for navbar brand when active -- **Default**: Inherits from `--navbar-active-color` -- **Usage**: Active navbar brand color - -### `--navbar-toggler-padding-x` -- **Description**: Horizontal padding for navbar toggler button -- **Default**: `0.75rem` -- **Usage**: Toggler button horizontal spacing - -### `--navbar-toggler-padding-y` -- **Description**: Vertical padding for navbar toggler button -- **Default**: `0.25rem` -- **Usage**: Toggler button vertical spacing - -### `--navbar-toggler-font-size` -- **Description**: Font size for navbar toggler icon -- **Default**: `1.25rem` -- **Usage**: Toggler icon size - -### `--navbar-toggler-border-color` -- **Description**: Border color for navbar toggler -- **Light Mode Default**: `rgba(0, 0, 0, 0.1)` -- **Dark Mode Default**: `rgba(255, 255, 255, 0.1)` -- **Usage**: Toggler button border - -### `--navbar-toggler-border-radius` -- **Description**: Border radius for navbar toggler -- **Default**: `0.25rem` -- **Usage**: Toggler button corner rounding - -### `--navbar-toggler-focus-width` -- **Description**: Width of focus outline on toggler -- **Default**: `0.25rem` -- **Usage**: Focus indicator width - -### `--navbar-toggler-transition` -- **Description**: CSS transition for toggler state changes -- **Default**: `box-shadow 0.15s ease-in-out` -- **Usage**: Toggler animation - -### `--nav-link-padding-x` -- **Description**: Horizontal padding for nav links -- **Default**: `0.5rem` -- **Usage**: Nav link horizontal spacing - -### `--nav-link-padding-y` -- **Description**: Vertical padding for nav links -- **Default**: `0.5rem` -- **Usage**: Nav link vertical spacing - -### `--nav-link-font-weight` -- **Description**: Font weight for nav links -- **Default**: `400` -- **Usage**: Nav link text weight - -### `--nav-link-color` -- **Description**: Color for nav links -- **Default**: Inherits from `--navbar-color` -- **Usage**: Nav link text color - -### `--nav-link-active-color` -- **Description**: Color for active nav links -- **Default**: Inherits from `--navbar-active-color` -- **Usage**: Active nav link color - -### `--nav-link-disabled-color` -- **Description**: Color for disabled nav links -- **Default**: Inherits from `--navbar-disabled-color` -- **Usage**: Disabled nav link color - ---- - -## Offcanvas Variables - -### `--offcanvas-color` -- **Description**: Text color for offcanvas content -- **Light Mode Default**: `var(--body-color)` -- **Dark Mode Default**: `var(--body-color)` -- **Usage**: Offcanvas text color - -### `--offcanvas-padding-x` -- **Description**: Horizontal padding for offcanvas content -- **Default**: `1.5rem` -- **Usage**: Offcanvas horizontal spacing - -### `--offcanvas-padding-y` -- **Description**: Vertical padding for offcanvas content -- **Default**: `1.5rem` -- **Usage**: Offcanvas vertical spacing - ---- - -## Header Background - -### `--header-background-image` -- **Description**: Background image URL for header -- **Default**: `url('../../../../../../media/templates/site/mokoonyx/images/bg.svg')` -- **Usage**: Header section background - -### `--header-background-attachment` -- **Description**: CSS background-attachment property -- **Default**: `fixed` -- **Options**: `scroll`, `fixed`, `local` - -### `--header-background-repeat` -- **Description**: CSS background-repeat property -- **Default**: `repeat` -- **Options**: `repeat`, `repeat-x`, `repeat-y`, `no-repeat` - -### `--header-background-size` -- **Description**: CSS background-size property -- **Default**: `auto` -- **Options**: `auto`, `cover`, `contain`, specific sizes - ---- - -## Container Backgrounds - -Each container section has the following customizable properties: - -### Container Sections -- `below-topbar` - Below top navigation bar -- `top-a` - Top section A -- `top-b` - Top section B -- `toc` - Table of Contents sidebar -- `sidebar` - Sidebar area -- `bottom-a` - Bottom section A -- `bottom-b` - Bottom section B - -### Available Properties per Container -Replace `{section}` with the container name: - -- `--container-{section}-bg-image` - Background image URL -- `--container-{section}-bg-color` - Background color -- `--container-{section}-bg-position` - Background position -- `--container-{section}-bg-attachment` - Attachment (scroll/fixed) -- `--container-{section}-bg-repeat` - Repeat pattern -- `--container-{section}-bg-size` - Background size -- `--container-{section}-border` - Border styling -- `--container-{section}-border-radius` - Border radius - -### Special TOC Variables - -#### `--container-toc-bg` -- **Description**: Background color for TOC container -- **Light Mode Default**: `var(--mainmenu-nav-link-color)` -- **Dark Mode Default**: (empty, transparent) - -#### `--container-toc-color` -- **Description**: Text color for TOC -- **Light Mode Default**: `var(--color-primary)` -- **Dark Mode Default**: `#dbe3ff` - ---- - -## Bootstrap Color Palette - -### Contextual Colors - -#### `--primary` -- **Light Mode**: `#010156` -- **Dark Mode**: `#010156` -- **Usage**: Primary theme color - -#### `--secondary` -- **Light Mode**: `#6d757e` -- **Dark Mode**: `#48525d` -- **Usage**: Secondary elements - -#### `--success` -- **Light Mode**: `#448344` -- **Dark Mode**: `#4aa664` -- **Usage**: Success messages, positive actions - -#### `--info` -- **Light Mode**: `#30638d` -- **Dark Mode**: `#4f7aa0` -- **Usage**: Informational messages - -#### `--warning` -- **Light Mode**: `#ad6200` -- **Dark Mode**: `#c77a00` -- **Usage**: Warning messages - -#### `--danger` -- **Light Mode**: `#a51f18` -- **Dark Mode**: `#c23a31` -- **Usage**: Error messages, destructive actions - -#### `--light` -- **Light Mode**: `#f9fafb` -- **Dark Mode**: `#1b2027` -- **Usage**: Light backgrounds - -#### `--dark` -- **Light Mode**: `#353b41` -- **Dark Mode**: `#0f1318` -- **Usage**: Dark backgrounds - -### Standard Colors - -Available in both themes: -- `--blue`, `--indigo`, `--purple`, `--pink` -- `--red`, `--orange`, `--yellow`, `--green` -- `--teal`, `--cyan` -- `--black`, `--white` - -### Gray Scale - -Available in 9 shades: `--gray-100` through `--gray-900` - -Light mode ranges from very light (`#f9fafb`) to very dark (`#22262a`). -Dark mode ranges are inverted for better contrast on dark backgrounds. - -### Opacity Utilities - -**New in v03.08.04**: Opacity utility variables for creating translucent colors: - -- `--opacity-0`: `0` (fully transparent) -- `--opacity-5`: `0.05` -- `--opacity-10`: `0.1` -- `--opacity-15`: `0.15` -- `--opacity-20`: `0.2` -- `--opacity-25`: `0.25` -- `--opacity-30`: `0.3` -- `--opacity-50`: `0.5` -- `--opacity-75`: `0.75` -- `--opacity-100`: `1` (fully opaque) - -**Usage Example:** -```css -background-color: rgba(var(--black-rgb), var(--opacity-10)); -border-color: rgba(var(--white-rgb), var(--opacity-25)); -``` - -### Shadow Color Utilities - -**New in v03.08.04**: Pre-defined shadow color variables for consistent shadow styling: - -**Light Theme:** -- `--shadow-color-light`: `rgba(var(--black-rgb), var(--opacity-15))` - Light shadows -- `--shadow-color-medium`: `rgba(var(--black-rgb), var(--opacity-25))` - Medium shadows -- `--shadow-color-dark`: `rgba(var(--black-rgb), var(--opacity-30))` - Dark shadows -- `--border-color-translucent`: `rgba(var(--black-rgb), var(--opacity-10))` - Translucent borders -- `--highlight-translucent`: `rgba(var(--white-rgb), var(--opacity-15))` - Highlight overlays - -**Dark Theme:** -- `--shadow-color-light`: `rgba(var(--black-rgb), var(--opacity-30))` - Adjusted for dark backgrounds -- `--shadow-color-medium`: `rgba(var(--black-rgb), var(--opacity-50))` -- `--shadow-color-dark`: `rgba(var(--black-rgb), var(--opacity-75))` -- `--border-color-translucent`: `rgba(var(--white-rgb), var(--opacity-10))` -- `--highlight-translucent`: `rgba(var(--white-rgb), var(--opacity-5))` - -**Usage Example:** -```css -box-shadow: 0 0.5rem 1rem var(--shadow-color-light); -border: 1px solid var(--border-color-translucent); -``` - ---- - -## Body & Typography - -### `--body-font-family` -- **Description**: Default font stack for body text -- **Default**: `-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans", sans-serif` -- **Usage**: All body text - -### `--body-font-size` -- **Description**: Base font size -- **Default**: `1rem` (typically 16px) -- **Usage**: Base typography size - -### `--body-font-weight` -- **Description**: Default font weight -- **Default**: `400` -- **Usage**: Body text weight - -### `--body-line-height` -- **Description**: Line height for body text -- **Default**: `1.5` -- **Usage**: Text line spacing - -### `--body-color` -- **Description**: Main text color -- **Light Mode Default**: `#22262a` -- **Dark Mode Default**: `#e6ebf1` -- **Usage**: Body text color - -### `--body-bg` -- **Description**: Main background color -- **Light Mode Default**: `#fff` -- **Dark Mode Default**: `#0e1318` -- **Usage**: Page background - -### `--heading-color` -- **Description**: Color for headings (h1-h6) -- **Light Mode Default**: `inherit` -- **Dark Mode Default**: `#f1f5f9` -- **Usage**: Heading text - ---- - -## Additional Theme Colors - -### `--muted-color` -- **Default**: `#6d757e` -- **Usage**: Muted/secondary text - -### `--code-color` -- **Light Mode**: `#e93f8e` -- **Dark Mode**: `#ff7abd` -- **Usage**: Inline code elements - -### `--highlight-bg` -- **Light Mode**: `#fbeea8` -- **Dark Mode**: `#ffe28a1a` -- **Usage**: Text highlighting, mark elements - -### `--emphasis-color` -- **Light Mode**: `#000` -- **Dark Mode**: `#fff` -- **Usage**: Emphasized text - -### `--secondary-bg` -- **Light Mode**: `#eaedf0` -- **Dark Mode**: `#151b22` -- **Usage**: Secondary backgrounds, alternate rows - -### `--tertiary-bg` -- **Light Mode**: `#f9fafb` -- **Dark Mode**: `#10151b` -- **Usage**: Tertiary backgrounds, subtle contrast - ---- - -## Borders & Shadows - -### Border Variables - -#### `--border` -- **Default**: `5px` -- **Usage**: Border width shorthand - -#### `--border-width` -- **Default**: `1px` -- **Usage**: Standard border width - -#### `--border-style` -- **Default**: `solid` -- **Usage**: Border style - -#### `--border-color` -- **Light Mode**: `#dfe3e7` -- **Dark Mode**: `#2b323b` -- **Usage**: Standard border color - -#### `--border-color-translucent` -- **Light Mode**: `#0000002d` -- **Dark Mode**: `#ffffff26` -- **Usage**: Semi-transparent borders - -### Border Radius - -- `--border-radius`: `.25rem` (default) -- `--border-radius-sm`: `.2rem` (small) -- `--border-radius-lg`: `.3rem` (large) -- `--border-radius-xl`: `.3rem` (extra large) -- `--border-radius-xxl`: `2rem` (2x extra large) -- `--border-radius-pill`: `50rem` (pill-shaped) - -### Box Shadows - -#### `--box-shadow` -- **Default**: `0 .5rem 1rem rgba(0,0,0,.15)` -- **Usage**: Standard drop shadow - -#### `--box-shadow-sm` -- **Default**: `0 .125rem .25rem rgba(0,0,0,.075)` -- **Usage**: Small/subtle shadow - -#### `--box-shadow-lg` -- **Default**: `0 1rem 3rem rgba(0,0,0,.175)` -- **Usage**: Large/prominent shadow - -#### `--box-shadow-inset` -- **Default**: `inset 0 1px 2px rgba(0,0,0,.075)` -- **Usage**: Inset/inner shadow - ---- - -## Bootstrap Button Variants - -**New in v03.08.04**: Complete Bootstrap button color definitions for both light and dark themes. - -### Available Button Classes - -All button variants support hover, active, focus, and disabled states using CSS variables: - -**Solid Buttons:** -- `.btn-primary` - Primary brand button -- `.btn-secondary` - Secondary button -- `.btn-success` - Success/positive action button -- `.btn-info` - Informational button -- `.btn-warning` - Warning/caution button -- `.btn-danger` - Danger/destructive action button -- `.btn-light` - Light background button -- `.btn-dark` - Dark background button - -**Outline Buttons:** -- `.btn-outline-primary` through `.btn-outline-dark` - Outlined variants of above - -### Button CSS Variables - -Each button variant defines the following CSS variables: - -- `--btn-color`: Text color -- `--btn-bg`: Background color -- `--btn-border-color`: Border color -- `--btn-hover-color`: Hover state text color -- `--btn-hover-bg`: Hover state background -- `--btn-hover-border-color`: Hover state border -- `--btn-focus-shadow-rgb`: Focus ring RGB values -- `--btn-active-color`: Active state text color -- `--btn-active-bg`: Active state background -- `--btn-active-border-color`: Active state border -- `--btn-active-shadow`: Active state shadow -- `--btn-disabled-color`: Disabled state text color -- `--btn-disabled-bg`: Disabled state background -- `--btn-disabled-border-color`: Disabled state border - -### Customizing Button Colors - -To customize button colors in your custom color palette: - -```css -:root[data-bs-theme="light"] { - /* Override Bootstrap state colors */ - --success: #28a745; - --danger: #dc3545; -} - -.btn-primary { - --btn-bg: var(--color-primary); - --btn-border-color: var(--color-primary); - /* Other button states... */ -} -``` - -See `templates/light.custom.css` and `templates/dark.custom.css` for complete examples. - ---- - -## Button Utilities - -### `--btn-border-radius` -- **Description**: Border radius for buttons -- **Default**: `0.25rem` -- **Usage**: Button corner rounding - -### `--btn-box-shadow` -- **Description**: Box shadow for buttons -- **Default**: `inset 0 1px 0 rgba(255, 255, 255, 0.15), 0 1px 1px rgba(0, 0, 0, 0.075)` -- **Usage**: Button shadow styling - ---- - -## Card Variables - -### `--card-spacer-x` -- **Description**: Horizontal spacing for card padding -- **Default**: `1rem` -- **Usage**: Card horizontal padding - -### `--card-spacer-y` -- **Description**: Vertical spacing for card padding -- **Default**: `1rem` -- **Usage**: Card vertical padding - -### `--card-title-spacer-y` -- **Description**: Spacing below card title -- **Default**: `0.5rem` -- **Usage**: Card title bottom margin - -### `--card-border-width` -- **Description**: Width of card border -- **Default**: `1px` -- **Usage**: Card border thickness - -### `--card-border-color` -- **Description**: Color of card border -- **Light Mode Default**: `rgba(0, 0, 0, 0.125)` -- **Dark Mode Default**: `rgba(255, 255, 255, 0.125)` -- **Usage**: Card border color - -### `--card-border-radius` -- **Description**: Border radius for cards -- **Default**: `0.25rem` -- **Usage**: Card corner rounding - -### `--card-box-shadow` -- **Description**: Box shadow for cards -- **Default**: `none` -- **Usage**: Card shadow effect - -### `--card-inner-border-radius` -- **Description**: Inner border radius for nested card elements -- **Default**: `calc(0.25rem - 1px)` -- **Usage**: Inner card element corners - -### `--card-cap-padding-x` -- **Description**: Horizontal padding for card header/footer -- **Default**: `1rem` -- **Usage**: Card cap horizontal spacing - -### `--card-cap-padding-y` -- **Description**: Vertical padding for card header/footer -- **Default**: `0.5rem` -- **Usage**: Card cap vertical spacing - -### `--card-cap-bg` -- **Description**: Background color for card header/footer -- **Light Mode Default**: `rgba(0, 0, 0, 0.03)` -- **Dark Mode Default**: `rgba(255, 255, 255, 0.03)` -- **Usage**: Card cap background - -### `--card-cap-color` -- **Description**: Text color for card header/footer -- **Default**: Inherits from body color -- **Usage**: Card cap text color - -### `--card-height` -- **Description**: Height constraint for cards -- **Default**: `auto` -- **Usage**: Card height control - -### `--card-color` -- **Description**: Text color for card content -- **Default**: Inherits from body color -- **Usage**: Card text color - -### `--card-bg` -- **Description**: Background color for cards -- **Light Mode Default**: `#fff` -- **Dark Mode Default**: `#212529` -- **Usage**: Card background - -### `--card-img-overlay-padding` -- **Description**: Padding for card image overlays -- **Default**: `1rem` -- **Usage**: Card image overlay spacing - -### `--card-group-margin` -- **Description**: Margin between cards in card groups -- **Default**: `0.75rem` -- **Usage**: Card group spacing - ---- - -## Form Colors - -### Focus Ring - -#### `--focus-ring-width` -- **Default**: `.25rem` -- **Usage**: Width of focus indicators - -#### `--focus-ring-opacity` -- **Light Mode**: `.25` -- **Dark Mode**: `.6` -- **Usage**: Opacity of focus ring - -#### `--focus-ring-color` -- **Light Mode**: `rgba(1,1,86,.25)` -- **Dark Mode**: `rgba(84,114,255,.4)` -- **Usage**: Color of focus indicators - -### Validation Colors - -#### Valid State -- `--form-valid-color`: Success green - - Light: `#448344` - - Dark: `#78d694` -- `--form-valid-border-color`: Matching border color - -#### Invalid State -- `--form-invalid-color`: Error red - - Light: `#a51f18` - - Dark: `#ff8e86` -- `--form-invalid-border-color`: Matching border color - -### Form Control Enhancements - -**New in v03.08.04**: Additional form control color variables: - -#### `--input-file-button-active-bg` -- **Light Mode**: `#dee1e4` -- **Dark Mode**: `#2b3441` -- **Usage**: Background color for file input button in active state - -#### `--form-range-thumb-active-bg` -- **Light Mode**: `#b8bfcc` -- **Dark Mode**: `#4a5766` -- **Usage**: Background color for range slider thumb in active state - -### Alert Link Colors - -**New in v03.08.04**: Dedicated variables for alert link colors: - -- `--alert-primary-link-color`: Link color in primary alerts -- `--alert-secondary-link-color`: Link color in secondary alerts -- `--alert-success-link-color`: Link color in success alerts -- `--alert-info-link-color`: Link color in info alerts -- `--alert-warning-link-color`: Link color in warning alerts -- `--alert-danger-link-color`: Link color in danger alerts -- `--alert-light-link-color`: Link color in light alerts -- `--alert-dark-link-color`: Link color in dark alerts - -These ensure optimal readability for links within alert boxes. - ---- - -## Responsive Tokens & Breakpoints - -### Breakpoint Variables - -#### `--bp-xs` -- **Description**: Extra small breakpoint -- **Default**: `0px` -- **Usage**: Mobile devices - -#### `--bp-sm` -- **Description**: Small breakpoint -- **Default**: `576px` -- **Usage**: Small tablets, large phones - -#### `--bp-md` -- **Description**: Medium breakpoint -- **Default**: `768px` -- **Usage**: Tablets - -#### `--bp-lg` -- **Description**: Large breakpoint -- **Default**: `992px` -- **Usage**: Desktops - -#### `--bp-xl` -- **Description**: Extra large breakpoint -- **Default**: `1200px` -- **Usage**: Large desktops - -### Responsive Utilities - -#### `--nav-toggle-size` -- **Description**: Size of navigation toggle button -- **Default**: `40px` -- **Usage**: Mobile menu toggle button dimensions - -#### `--bg-opacity` -- **Description**: Background opacity for overlay elements -- **Default**: `0.5` -- **Usage**: Overlay transparency - -#### `--padding-x` -- **Description**: General horizontal padding utility -- **Default**: `1rem` -- **Usage**: Horizontal spacing utility - -#### `--padding-y` -- **Description**: General vertical padding utility -- **Default**: `1rem` -- **Usage**: Vertical spacing utility - ---- - -## VirtueMart Variables - -### VM Surfaces - -#### `--vm-surface` -- **Description**: Primary VirtueMart surface background -- **Light Mode Default**: `#ffffff` -- **Dark Mode Default**: `#1e1e1e` -- **Usage**: Main VM component backgrounds - -#### `--vm-surface-2` -- **Description**: Secondary VirtueMart surface background -- **Light Mode Default**: `#f8f9fa` -- **Dark Mode Default**: `#2d2d2d` -- **Usage**: Alternate VM backgrounds - -#### `--vm-text` -- **Description**: Default VirtueMart text color -- **Light Mode Default**: `#212529` -- **Dark Mode Default**: `#e9ecef` -- **Usage**: VM body text - -#### `--vm-text-strong` -- **Description**: Strong/emphasized VirtueMart text -- **Light Mode Default**: `#000000` -- **Dark Mode Default**: `#ffffff` -- **Usage**: VM headings, emphasized text - -#### `--vm-text-muted` -- **Description**: Muted VirtueMart text -- **Light Mode Default**: `#6c757d` -- **Dark Mode Default**: `#adb5bd` -- **Usage**: VM secondary text, captions - -#### `--vm-border` -- **Description**: Border color for VirtueMart components -- **Light Mode Default**: `#dee2e6` -- **Dark Mode Default**: `#495057` -- **Usage**: VM borders, dividers - -#### `--vm-price-color` -- **Description**: Color for product prices -- **Light Mode Default**: `#198754` -- **Dark Mode Default**: `#20c997` -- **Usage**: Product price display - -### VM Layout - -#### `--vm-container-max-width` -- **Description**: Maximum width for VM containers -- **Default**: `1200px` -- **Usage**: VM content width constraint - -#### `--vm-section-gap` -- **Description**: Gap between VM sections -- **Default**: `2rem` -- **Usage**: VM section spacing - -#### `--vm-block-radius` -- **Description**: Border radius for VM blocks -- **Default**: `0.375rem` -- **Usage**: VM component corner rounding - -#### `--vm-block-shadow` -- **Description**: Shadow for VM blocks -- **Default**: `0 2px 4px rgba(0, 0, 0, 0.1)` -- **Usage**: VM component shadows - -### VM Typography - -#### `--vm-title-1-size` -- **Description**: Size for h1 titles in VM -- **Default**: `2.5rem` -- **Usage**: VM main headings - -#### `--vm-title-1-weight` -- **Description**: Font weight for h1 titles -- **Default**: `700` -- **Usage**: VM main heading weight - -#### `--vm-title-2-size` -- **Description**: Size for h2 titles in VM -- **Default**: `2rem` -- **Usage**: VM section headings - -#### `--vm-title-2-weight` -- **Description**: Font weight for h2 titles -- **Default**: `600` -- **Usage**: VM section heading weight - -#### `--vm-title-3-size` -- **Description**: Size for h3 titles in VM -- **Default**: `1.75rem` -- **Usage**: VM subsection headings - -#### `--vm-title-3-weight` -- **Description**: Font weight for h3 titles -- **Default**: `600` -- **Usage**: VM subsection heading weight - -#### `--vm-title-4-size` -- **Description**: Size for h4 titles in VM -- **Default**: `1.5rem` -- **Usage**: VM component headings - -#### `--vm-title-4-weight` -- **Description**: Font weight for h4 titles -- **Default**: `500` -- **Usage**: VM component heading weight - -#### `--vm-title-5-size` -- **Description**: Size for h5 titles in VM -- **Default**: `1.25rem` -- **Usage**: VM small headings - -#### `--vm-title-5-weight` -- **Description**: Font weight for h5 titles -- **Default**: `500` -- **Usage**: VM small heading weight - -### VM Controls - -#### `--vm-input-border` -- **Description**: Border style for VM inputs -- **Light Mode Default**: `1px solid #ced4da` -- **Dark Mode Default**: `1px solid #495057` -- **Usage**: VM form input borders - -#### `--vm-input-bg` -- **Description**: Background color for VM inputs -- **Light Mode Default**: `#ffffff` -- **Dark Mode Default**: `#212529` -- **Usage**: VM form input backgrounds - -#### `--vm-input-text` -- **Description**: Text color for VM inputs -- **Light Mode Default**: `#212529` -- **Dark Mode Default**: `#e9ecef` -- **Usage**: VM form input text - -#### `--vm-qty-width` -- **Description**: Width for quantity input fields -- **Default**: `80px` -- **Usage**: Product quantity selectors - -#### `--vm-cart-dropdown-min-width` -- **Description**: Minimum width for cart dropdown -- **Default**: `300px` -- **Usage**: Shopping cart dropdown sizing - -### VM Alerts - -#### `--vm-alert-success-bg` -- **Description**: Background for success alerts -- **Light Mode Default**: `#d1e7dd` -- **Dark Mode Default**: `#0f5132` -- **Usage**: VM success messages - -#### `--vm-alert-error-bg` -- **Description**: Background for error alerts -- **Light Mode Default**: `#f8d7da` -- **Dark Mode Default**: `#842029` -- **Usage**: VM error messages - -#### `--vm-availability-in-stock` -- **Description**: Color for in-stock indicator -- **Light Mode Default**: `#198754` -- **Dark Mode Default**: `#20c997` -- **Usage**: Product availability display - -#### `--vm-availability-out-of-stock` -- **Description**: Color for out-of-stock indicator -- **Light Mode Default**: `#dc3545` -- **Dark Mode Default**: `#ea868f` -- **Usage**: Product unavailability display - -### VM Buttons - -#### `--vm-btn-padding-x` -- **Description**: Horizontal padding for VM buttons -- **Default**: `1rem` -- **Usage**: VM button horizontal spacing - -#### `--vm-btn-padding-y` -- **Description**: Vertical padding for VM buttons -- **Default**: `0.5rem` -- **Usage**: VM button vertical spacing - -#### `--vm-btn-radius` -- **Description**: Border radius for VM buttons -- **Default**: `0.25rem` -- **Usage**: VM button corner rounding - -#### `--vm-btn-shadow` -- **Description**: Shadow for VM buttons -- **Default**: `0 2px 4px rgba(0, 0, 0, 0.1)` -- **Usage**: VM button shadows - -#### `--vm-btn-primary-bg` -- **Description**: Background for primary VM buttons -- **Light Mode Default**: `#0d6efd` -- **Dark Mode Default**: `#0a58ca` -- **Usage**: Primary VM action buttons - -#### `--vm-btn-primary-text` -- **Description**: Text color for primary VM buttons -- **Default**: `#ffffff` -- **Usage**: Primary VM button text - -#### `--vm-btn-secondary-bg` -- **Description**: Background for secondary VM buttons -- **Light Mode Default**: `#6c757d` -- **Dark Mode Default**: `#565e64` -- **Usage**: Secondary VM action buttons - -#### `--vm-btn-secondary-text` -- **Description**: Text color for secondary VM buttons -- **Default**: `#ffffff` -- **Usage**: Secondary VM button text - -#### `--vm-btn-add-to-cart-bg` -- **Description**: Background for add-to-cart button -- **Light Mode Default**: `#198754` -- **Dark Mode Default**: `#146c43` -- **Usage**: Add to cart button styling - -### VM Image Overlays - -#### `--vm-overlay-gap` -- **Description**: Gap in image overlay elements -- **Default**: `0.5rem` -- **Usage**: Spacing in product image overlays - -#### `--vm-overlay-top` -- **Description**: Top position for overlay elements -- **Default**: `1rem` -- **Usage**: Overlay vertical positioning - -#### `--vm-overlay-right` -- **Description**: Right position for overlay elements -- **Default**: `1rem` -- **Usage**: Overlay horizontal positioning - -#### `--vm-overlay-btn-size` -- **Description**: Size for overlay buttons -- **Default**: `40px` -- **Usage**: Quick view, wishlist button dimensions - -#### `--vm-overlay-btn-bg` -- **Description**: Background for overlay buttons -- **Light Mode Default**: `rgba(255, 255, 255, 0.9)` -- **Dark Mode Default**: `rgba(0, 0, 0, 0.9)` -- **Usage**: Overlay button background - -#### `--vm-overlay-btn-text` -- **Description**: Text color for overlay buttons -- **Light Mode Default**: `#212529` -- **Dark Mode Default**: `#e9ecef` -- **Usage**: Overlay button text - -#### `--vm-overlay-btn-hover-bg` -- **Description**: Background for overlay buttons on hover -- **Light Mode Default**: `#ffffff` -- **Dark Mode Default**: `#000000` -- **Usage**: Overlay button hover state - -#### `--vm-overlay-btn-radius` -- **Description**: Border radius for overlay buttons -- **Default**: `50%` -- **Usage**: Circular overlay buttons - -#### `--vm-overlay-btn-shadow` -- **Description**: Shadow for overlay buttons -- **Default**: `0 2px 8px rgba(0, 0, 0, 0.15)` -- **Usage**: Overlay button shadows - -### VM Vendor Menu - -#### `--vm-vendor-menu-bg` -- **Description**: Background for vendor menu -- **Light Mode Default**: `#ffffff` -- **Dark Mode Default**: `#212529` -- **Usage**: Vendor menu background - -#### `--vm-vendor-menu-text` -- **Description**: Text color for vendor menu -- **Light Mode Default**: `#212529` -- **Dark Mode Default**: `#e9ecef` -- **Usage**: Vendor menu text - -#### `--vm-vendor-menu-border` -- **Description**: Border for vendor menu -- **Light Mode Default**: `1px solid #dee2e6` -- **Dark Mode Default**: `1px solid #495057` -- **Usage**: Vendor menu borders - -#### `--vm-vendor-menu-hover-bg` -- **Description**: Background on hover for vendor menu items -- **Light Mode Default**: `#f8f9fa` -- **Dark Mode Default**: `#2d2d2d` -- **Usage**: Vendor menu hover state - -#### `--vm-vendor-menu-active-bg` -- **Description**: Background for active vendor menu items -- **Light Mode Default**: `#e9ecef` -- **Dark Mode Default**: `#343a40` -- **Usage**: Active vendor menu item - -#### `--vm-vendor-menu-active-text` -- **Description**: Text color for active vendor menu items -- **Light Mode Default**: `#0d6efd` -- **Dark Mode Default**: `#6ea8fe` -- **Usage**: Active vendor menu text - -#### `--vm-vendor-menu-padding-x` -- **Description**: Horizontal padding for vendor menu items -- **Default**: `1rem` -- **Usage**: Vendor menu item horizontal spacing - -#### `--vm-vendor-menu-padding-y` -- **Description**: Vertical padding for vendor menu items -- **Default**: `0.75rem` -- **Usage**: Vendor menu item vertical spacing - -#### `--vm-vendor-menu-font-size` -- **Description**: Font size for vendor menu -- **Default**: `0.875rem` -- **Usage**: Vendor menu text size - -#### `--vm-vendor-menu-font-weight` -- **Description**: Font weight for vendor menu -- **Default**: `400` -- **Usage**: Vendor menu text weight - -#### `--vm-vendor-menu-radius` -- **Description**: Border radius for vendor menu -- **Default**: `0.25rem` -- **Usage**: Vendor menu corner rounding - -#### `--vm-vendor-menu-shadow` -- **Description**: Shadow for vendor menu -- **Default**: `0 2px 4px rgba(0, 0, 0, 0.1)` -- **Usage**: Vendor menu drop shadow - -#### `--vm-vendor-menu-width` -- **Description**: Width for vendor menu -- **Default**: `250px` -- **Usage**: Vendor menu sizing - -#### `--vm-vendor-menu-item-gap` -- **Description**: Gap between vendor menu items -- **Default**: `0.25rem` -- **Usage**: Vendor menu item spacing - -#### `--vm-vendor-menu-icon-size` -- **Description**: Size for vendor menu icons -- **Default**: `1.25rem` -- **Usage**: Vendor menu icon dimensions - ---- - -## Gable Variables - -### `--gab-blue` -- **Description**: Gable primary blue color -- **Default**: `#1e88e5` -- **Usage**: Gable brand blue accent - -### `--gab-green` -- **Description**: Gable green color -- **Default**: `#43a047` -- **Usage**: Gable success/positive indicators - -### `--gab-red` -- **Description**: Gable red color -- **Default**: `#e53935` -- **Usage**: Gable error/alert indicators - -### `--gab-orange` -- **Description**: Gable orange color -- **Default**: `#fb8c00` -- **Usage**: Gable warning indicators - -### `--gab-gray1` -- **Description**: Gable light gray -- **Light Mode Default**: `#f5f5f5` -- **Dark Mode Default**: `#424242` -- **Usage**: Gable light backgrounds - -### `--gab-gray2` -- **Description**: Gable medium gray -- **Light Mode Default**: `#e0e0e0` -- **Dark Mode Default**: `#616161` -- **Usage**: Gable medium backgrounds, borders - -### `--gab-gray3` -- **Description**: Gable dark gray -- **Light Mode Default**: `#9e9e9e` -- **Dark Mode Default**: `#9e9e9e` -- **Usage**: Gable text, icons - ---- - -## Usage Examples - -### Example 1: Custom Brand Colors - -```css -:root[data-bs-theme="light"] { - --color-primary: #1e40af; - --accent-color-primary: #3b82f6; - --color-link: #2563eb; - --color-hover: #1d4ed8; -} -``` - -### Example 2: Custom Container Background - -```css -:root[data-bs-theme="light"] { - --container-top-a-bg-color: #f3f4f6; - --container-top-a-bg-image: url('/images/pattern.svg'); - --container-top-a-bg-repeat: repeat; - --container-top-a-border-radius: 8px; -} -``` - -### Example 3: Custom Typography - -```css -:root[data-bs-theme="light"] { - --body-font-family: 'Inter', sans-serif; - --body-font-size: 1.125rem; - --heading-color: #1f2937; -} -``` - -### Example 4: Custom Card Styling - -```css -:root[data-bs-theme="light"] { - --card-border-radius: 0.5rem; - --card-box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1); - --card-spacer-x: 1.5rem; - --card-spacer-y: 1.5rem; -} -``` - -### Example 5: VirtueMart Custom Colors - -```css -:root[data-bs-theme="light"] { - --vm-btn-primary-bg: #0d6efd; - --vm-btn-add-to-cart-bg: #198754; - --vm-price-color: #dc3545; - --vm-surface: #ffffff; -} -``` - -### Example 6: Responsive Navbar - -```css -:root[data-bs-theme="light"] { - --navbar-padding-x: 1.5rem; - --navbar-padding-y: 0.75rem; - --nav-toggle-size: 48px; - --navbar-toggler-border-radius: 0.5rem; -} -``` - ---- - -## Tips for Customization - -1. **Start with templates**: Use the provided template files as a starting point -2. **Test both themes**: Ensure your colors work well in both light and dark modes -3. **Use CSS variables**: Reference other variables with `var()` for consistency -4. **Check contrast**: Ensure text remains readable against backgrounds -5. **Use fallbacks**: Provide fallback values in `var()` functions -6. **Test responsively**: Verify colors work on all screen sizes -7. **Document changes**: Keep notes on custom color choices - ---- - -## See Also - -- [README](../README.md) - Main documentation -- [Quick Start Guide](./QUICK_START.md) - Getting started -- [Development Guide](./JOOMLA_DEVELOPMENT.md) - Developer resources -- Template files in `/templates/` directory - ---- - -## Hero Variant Variables - -### `--hero-primary-bg-color` -- **Description**: Fallback background color for the primary hero variant -- **Light Mode Default**: `var(--color-primary)` -- **Dark Mode Default**: `#0d1e3a` -- **Usage**: `.hero#primary` background when no image loads - -### `--hero-primary-overlay` -- **Description**: Gradient overlay tint for primary hero -- **Light Mode Default**: `linear-gradient(rgba(163, 205, 226, .45), rgba(163, 205, 226, .45))` -- **Dark Mode Default**: `linear-gradient(rgba(13, 30, 58, .65), rgba(13, 30, 58, .65))` -- **Usage**: Semi-transparent color wash over hero background image - -### `--hero-primary-color` -- **Description**: Text color for primary hero content -- **Light Mode Default**: `var(--color-primary)` -- **Dark Mode Default**: `#f1f5f9` -- **Usage**: Headings and body text inside `.hero#primary` - -### `--hero-secondary-bg-color` -- **Description**: Fallback background color for the secondary hero variant -- **Light Mode Default**: `var(--color-primary)` -- **Dark Mode Default**: `#080f1e` -- **Usage**: `.hero#secondary` background when no image loads - -### `--hero-secondary-overlay` -- **Description**: Gradient overlay tint for secondary hero -- **Light Mode Default**: `linear-gradient(rgba(17, 40, 85, .75), rgba(17, 40, 85, .75))` -- **Dark Mode Default**: `linear-gradient(rgba(8, 15, 30, .80), rgba(8, 15, 30, .80))` -- **Usage**: Stronger overlay for inner-page heroes - -### `--hero-secondary-color` -- **Description**: Text color for secondary hero content -- **Light Mode Default**: `#f1f5f9` -- **Dark Mode Default**: `#f1f5f9` -- **Usage**: Headings and body text inside `.hero#secondary` - ---- - -## Block Color Variables - -### Slot Palette (automatic by position order) - -| Variable | Purpose | Light Default | Dark Default | -|---|---|---|---| -| `--block-color-1` | Background for 1st module | `var(--color-primary)` | `var(--secondary-bg)` | -| `--block-text-1` | Text for 1st module | `var(--body-color)` | `var(--body-color)` | -| `--block-color-2` | Background for 2nd module | `var(--accent-color-primary)` | `var(--accent-color-primary)` | -| `--block-text-2` | Text for 2nd module | `#fff` | `#fff` | -| `--block-color-3` | Background for 3rd module | `var(--warning, #eec234)` | `rgba(238, 194, 52, .15)` | -| `--block-text-3` | Text for 3rd module | `var(--body-color)` | `var(--body-color)` | -| `--block-color-4` | Background for 4th module | `var(--success-bg-subtle, #eef7f0)` | `rgba(74, 166, 100, .15)` | -| `--block-text-4` | Text for 4th module | `var(--body-color)` | `var(--body-color)` | - -### Named Per-Module Overrides - -| Variable | Purpose | -|---|---| -| `--block-highlight-bg` | Background for `#block-highlight` module | -| `--block-highlight-text` | Text color for `#block-highlight` module | -| `--block-cta-bg` | Background for `#block-cta` module | -| `--block-cta-text` | Text color for `#block-cta` module | -| `--block-alert-bg` | Background for `#block-alert` module | -| `--block-alert-text` | Text color for `#block-alert` module | - -### Override Priority - -| Priority | Method | How applied | -|---|---|---| -| 1 (highest) | Named module ID (`#block-highlight`) | ID in module HTML, named variable in palette | -| 2 | Slot color (`--block-color-1` etc.) | Automatic by `:nth-child()` order | - ---- - -## Metadata - -* Document: docs/CSS_VARIABLES.md -* Repository: [https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx](https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx) -* Path: /docs/CSS_VARIABLES.md -* Owner: Moko Consulting -* Version: 03.09.02 -* Status: Active -* Effective Date: 2026-03-26 -* Classification: Public Open Source Documentation - -## Revision History - -| Date | Change Summary | Author | -| ---------- | ----------------------------------------------------- | --------------- | -| 2026-03-26 | Added hero variant and block color variable docs | Claude | -| 2026-02-07 | Added missing CSS variable documentation | GitHub Copilot | -| 2026-01-30 | Initial CSS variables reference documentation created | GitHub Copilot | diff --git a/docs/JOOMLA_DEVELOPMENT.md b/docs/JOOMLA_DEVELOPMENT.md deleted file mode 100644 index d83b2f4..0000000 --- a/docs/JOOMLA_DEVELOPMENT.md +++ /dev/null @@ -1,376 +0,0 @@ -# Joomla Development Workflows and Scripts - -This document describes the Joomla-aware development workflows and scripts available in this repository. - -## Table of Contents - -- [Overview](#overview) -- [Requirements](#requirements) -- [Scripts](#scripts) -- [GitHub Actions Workflows](#github-actions-workflows) -- [Testing](#testing) -- [Code Quality](#code-quality) -- [Deployment](#deployment) - -## Overview - -This repository includes comprehensive Joomla development workflows and scripts for: - -1. **Extension Packaging** - Create distributable ZIP packages -2. **Joomla Testing** - Automated testing with multiple Joomla versions -3. **Code Quality** - PHPStan, PHP_CodeSniffer, and compatibility checks -4. **Deployment** - Staging and production deployment workflows - -## Requirements - -### Local Development - -- PHP 8.0 or higher -- Composer (for PHPStan and PHP_CodeSniffer) -- Node.js 18+ (for some workflows) -- MySQL/MariaDB (for Joomla testing) - -### CI/CD (GitHub Actions) - -All requirements are automatically installed in CI/CD pipelines. - -## Scripts - -### Extension Packaging - -Package the Joomla template as a distributable ZIP file: - -```bash -make package -``` - -This creates a ZIP file in the `dist` directory with all necessary template files, excluding development files. - -## GitHub Actions Workflows - -### 1. PHP Code Quality (`php_quality.yml`) - -Runs on every push and pull request to main branches. - -**Jobs:** -- **PHP_CodeSniffer** - Checks code style and standards -- **PHPStan** - Static analysis at level 5 -- **PHP Compatibility** - Ensures PHP 8.0+ compatibility - -**Matrix Testing:** -- PHP versions: 8.0, 8.1, 8.2, 8.3 - -**Trigger:** -```bash -# Automatically runs on push/PR -git push origin dev/3.5.0 -``` - -### 2. Joomla Testing (`joomla_testing.yml`) - -Tests template with multiple Joomla and PHP versions. - -**Jobs:** -- **Joomla Setup** - Installs Joomla CMS -- **Template Installation** - Installs template into Joomla -- **Validation** - Validates template functionality -- **Codeception** - Runs test framework - -**Matrix Testing:** -- PHP versions: 8.0, 8.1, 8.2, 8.3 -- Joomla versions: 4.4 (LTS), 5.0, 5.1 -- MySQL version: 8.0 - -**Example:** -```bash -# Automatically runs on push to main branches -git push origin main -``` - -### 3. Deploy to Staging (`deploy_staging.yml`) - -Manual deployment to staging/development environments. - -**Parameters:** -- `environment`: Target environment (staging, development, preview) -- `version`: Version to deploy (optional, defaults to latest) - -**Usage:** -1. Go to Actions → Deploy to Staging -2. Click "Run workflow" -3. Select environment and version -4. Click "Run workflow" - -**Required Secrets:** -For staging deployment, configure these repository secrets: -- `STAGING_HOST` - SFTP server hostname -- `STAGING_USER` - SFTP username -- `STAGING_KEY` - SSH private key (recommended) or use `STAGING_PASSWORD` -- `STAGING_PATH` - Remote path for deployment -- `STAGING_PORT` - SSH port (optional, default: 22) - -## Testing - -### Codeception Framework - -The repository is configured with Codeception for acceptance and unit testing. - -#### Running Tests Locally - -1. Install Codeception: -```bash -composer global require "codeception/codeception" --with-all-dependencies -``` - -2. Run tests: -```bash -# Run all tests -codecept run - -# Run acceptance tests only -codecept run acceptance - -# Run unit tests only -codecept run unit - -# Run with verbose output -codecept run --debug -``` - -#### Test Structure - -``` -tests/ -├── _data/ # Test data and fixtures -├── _output/ # Test reports and screenshots -├── _support/ # Helper classes -├── acceptance/ # Acceptance tests -│ └── TemplateInstallationCest.php -├── unit/ # Unit tests -│ └── TemplateConfigurationTest.php -├── acceptance.suite.yml -└── unit.suite.yml -``` - -#### Writing Tests - -**Unit Test Example:** -```php -assertTrue(true); - } -} -``` - -**Acceptance Test Example:** -```php -amOnPage('/'); - $I->see('Welcome'); - } -} -``` - -## Code Quality - -### PHPStan - -Static analysis configuration in `phpstan.neon`: - -```bash -# Run PHPStan locally -phpstan analyse --configuration=phpstan.neon -``` - -**Configuration:** -- Analysis level: 5 -- Target paths: `src/` -- PHP version: 8.0+ - -### PHP_CodeSniffer - -Coding standards configuration in `phpcs.xml`: - -```bash -# Check code style -phpcs --standard=phpcs.xml - -# Fix auto-fixable issues -phpcbf --standard=phpcs.xml -``` - -**Standards:** -- PSR-12 as base -- PHP 8.0+ compatibility checks -- Joomla coding conventions (when available) - -### Running Quality Checks Locally - -1. Install tools: -```bash -composer global require "squizlabs/php_codesniffer:^3.0" --with-all-dependencies -composer global require "phpstan/phpstan:^1.0" --with-all-dependencies -composer global require "phpcompatibility/php-compatibility:^9.0" --with-all-dependencies -``` - -2. Configure PHPCompatibility: -```bash -phpcs --config-set installed_paths ~/.composer/vendor/phpcompatibility/php-compatibility -``` - -3. Run checks: -```bash -# PHP syntax check -make validate-required - -# CodeSniffer -phpcs --standard=phpcs.xml src/ - -# PHPStan -phpstan analyse --configuration=phpstan.neon - -# PHP Compatibility -phpcs --standard=PHPCompatibility --runtime-set testVersion 8.0- src/ -``` - -## Deployment - -### Manual Deployment - -Use the package script to create a distribution: - -```bash -# Create package -make package - -# Upload to server -scp dist/moko-cassiopeia-3.5.0-template.zip user@server:/path/to/joomla/ -``` - -### Automated Deployment - -Use the GitHub Actions workflow: - -1. **Staging Deployment:** - - Go to Actions → Deploy to Staging - - Select "staging" environment - - Click "Run workflow" - -2. **Development Testing:** - - Select "development" environment - - Useful for quick testing without affecting staging - -3. **Preview Deployment:** - - Select "preview" environment - - For showcasing features before staging - -### Post-Deployment Steps - -After deployment to Joomla: - -1. Log in to Joomla administrator -2. Go to System → Extensions → Discover -3. Click "Discover" to find the template -4. Click "Install" to complete installation -5. Go to System → Site Templates -6. Configure template settings -7. Set as default template if desired - -## CI/CD Pipeline Details - -### Build Process - -1. **Validation** - All scripts validate before packaging -2. **Packaging** - Create ZIP with proper structure -3. **Testing** - Run on multiple PHP/Joomla versions -4. **Quality** - PHPStan and PHPCS analysis -5. **Deployment** - SFTP upload to target environment - -### Matrix Testing Strategy - -- **PHP Versions:** 8.0, 8.1, 8.2, 8.3 -- **Joomla Versions:** 4.4 LTS, 5.0, 5.1 -- **Exclusions:** PHP 8.3 not tested with Joomla 4.4 (incompatible) - -## Troubleshooting - -### Common Issues - -**Issue: PHP_CodeSniffer not found** -```bash -composer global require "squizlabs/php_codesniffer:^3.0" -export PATH="$PATH:$HOME/.composer/vendor/bin" -``` - -**Issue: PHPStan errors** -```bash -# Increase analysis memory -php -d memory_limit=1G $(which phpstan) analyse -``` - -**Issue: Joomla installation fails in CI** -- Check MySQL service is running -- Verify database credentials -- Ensure PHP extensions are installed - -**Issue: SFTP deployment fails** -- Verify SSH key is correctly formatted -- Check firewall allows port 22 -- Ensure STAGING_PATH exists on server - -## Contributing - -When adding new workflows or scripts: - -1. Follow existing script structure -2. Add proper error handling -3. Include usage documentation -4. Test with multiple PHP versions -5. Update this documentation - -## Support - -For issues or questions: -- Open an issue on GitHub -- Check existing workflow runs for examples -- Review test output in Actions tab - -## License - -All scripts and workflows are licensed under GPL-3.0-or-later, same as the main project. - ---- - -## Metadata - -* Document: docs/JOOMLA_DEVELOPMENT.md -* Repository: [https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx](https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx) -* Path: /docs/JOOMLA_DEVELOPMENT.md -* Owner: Moko Consulting -* Version: 03.06.03 -* Status: Active -* Effective Date: 2026-01-30 -* Classification: Public Open Source Documentation - -## Revision History - -| Date | Change Summary | Author | -| ---------- | ----------------------------------------------------- | --------------- | -| 2026-01-30 | Updated metadata to MokoStandards format | GitHub Copilot | -| 2025-01-04 | Initial Joomla development guide created | GitHub Copilot | diff --git a/docs/MANUAL_DEPLOYMENT.md b/docs/MANUAL_DEPLOYMENT.md deleted file mode 100644 index aa11a64..0000000 --- a/docs/MANUAL_DEPLOYMENT.md +++ /dev/null @@ -1,310 +0,0 @@ -# Manual Deployment Guide - MokoOnyx - -This guide explains how to manually deploy the MokoOnyx template from the `src` directory to a Joomla installation without using the build/packaging process. - -## Table of Contents - -- [Overview](#overview) -- [Understanding the Structure](#understanding-the-structure) -- [Manual Deployment Methods](#manual-deployment-methods) -- [Troubleshooting](#troubleshooting) -- [When to Use Manual Deployment](#when-to-use-manual-deployment) - -## Overview - -**Important**: The `src` directory in this repository is the development source, not a ready-to-install package. For production use, we recommend using the packaged ZIP file from [Releases](https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx/releases). - -However, for development or testing purposes, you can manually deploy files from the `src` directory to your Joomla installation. - -## Understanding the Structure - -### Repository Structure - -The `src/` directory contains: - -``` -src/ -├── component.php # Template file -├── error.php # Template file -├── index.php # Main template file -├── offline.php # Template file -├── templateDetails.xml # Template manifest -├── joomla.asset.json # Asset registration -├── html/ # Module & component overrides -├── language/ # Frontend language files -├── administrator/ # Backend language files -│ └── language/ -└── media/ # Assets (CSS, JS, images, fonts) - ├── css/ - ├── js/ - ├── images/ - └── fonts/ -``` - -### Joomla Installation Structure - -Joomla expects template files in these locations: - -``` -YOUR_JOOMLA_ROOT/ -├── templates/ -│ └── mokoonyx/ # Template files go here -│ ├── component.php -│ ├── error.php -│ ├── index.php -│ ├── offline.php -│ ├── templateDetails.xml -│ ├── joomla.asset.json -│ ├── html/ -│ ├── language/ -│ └── administrator/ -└── media/ - └── templates/ - └── site/ - └── mokoonyx/ # Media files go here - ├── css/ - ├── js/ - ├── images/ - └── fonts/ -``` - -**Key Point**: Template files and media files go to **different locations** in Joomla! - -## Manual Deployment Methods - -### Method 1: Recommended - Upload as ZIP (Still Manual) - -This method mimics what Joomla's installer does automatically. - -1. **Prepare the template directory**: - ```bash - # From the repository root - cd src - - # Copy all files EXCEPT media to a temp directory - mkdir -p /tmp/mokoonyx - cp component.php /tmp/mokoonyx/ - cp error.php /tmp/mokoonyx/ - cp index.php /tmp/mokoonyx/ - cp offline.php /tmp/mokoonyx/ - cp templateDetails.xml /tmp/mokoonyx/ - cp joomla.asset.json /tmp/mokoonyx/ - cp -r html /tmp/mokoonyx/ - cp -r language /tmp/mokoonyx/ - cp -r administrator /tmp/mokoonyx/ - - # Copy media to a separate temp directory - mkdir -p /tmp/mokoonyx_media - cp -r media/* /tmp/mokoonyx_media/ - ``` - -2. **Upload to Joomla via FTP/SFTP**: - ```bash - # Upload template files - # Replace with your actual Joomla path - scp -r /tmp/mokoonyx/* user@yourserver:/path/to/joomla/templates/mokoonyx/ - - # Upload media files - scp -r /tmp/mokoonyx_media/* user@yourserver:/path/to/joomla/media/templates/site/mokoonyx/ - ``` - -3. **Set proper permissions**: - ```bash - # On your server - cd /path/to/joomla - chmod 755 templates/mokoonyx - chmod 644 templates/mokoonyx/* - chmod 755 templates/mokoonyx/html - chmod 755 media/templates/site/mokoonyx - ``` - -### Method 2: Direct Copy to Existing Installation - -If you have direct filesystem access (e.g., local development): - -1. **Copy template files** (excluding media): - ```bash - # From repository root - cd src - - # Copy to Joomla templates directory - cp component.php /path/to/joomla/templates/mokoonyx/ - cp error.php /path/to/joomla/templates/mokoonyx/ - cp index.php /path/to/joomla/templates/mokoonyx/ - cp offline.php /path/to/joomla/templates/mokoonyx/ - cp templateDetails.xml /path/to/joomla/templates/mokoonyx/ - cp joomla.asset.json /path/to/joomla/templates/mokoonyx/ - - # Copy directories - cp -r html /path/to/joomla/templates/mokoonyx/ - cp -r language /path/to/joomla/templates/mokoonyx/ - cp -r administrator /path/to/joomla/templates/mokoonyx/ - ``` - -2. **Copy media files separately**: - ```bash - # Copy media to the media directory - cp -r media/* /path/to/joomla/media/templates/site/mokoonyx/ - ``` - -3. **Clear Joomla cache**: - - In Joomla admin: **System → Clear Cache** - - Or delete: `/path/to/joomla/cache/*` and `/path/to/joomla/administrator/cache/*` - -### Method 3: Symlink for Development (Linux/Mac only) - -For active development where you want changes to immediately reflect: - -1. **Create symlinks**: - ```bash - # Remove existing directory if present - rm -rf /path/to/joomla/templates/mokoonyx - rm -rf /path/to/joomla/media/templates/site/mokoonyx - - # Create parent directories if needed - mkdir -p /path/to/joomla/templates - mkdir -p /path/to/joomla/media/templates/site - - # Symlink template files - ln -s /path/to/MokoOnyx/src /path/to/joomla/templates/mokoonyx - - # Symlink media files - ln -s /path/to/MokoOnyx/src/media /path/to/joomla/media/templates/site/mokoonyx - ``` - -2. **Note**: This won't work as-is because the src directory includes the media folder. You'll need to: - ```bash - # Better approach for symlinks: - # Link everything except media at template root - cd /path/to/joomla/templates - mkdir -p mokoonyx - cd mokoonyx - - ln -s /path/to/MokoOnyx/src/component.php - ln -s /path/to/MokoOnyx/src/error.php - ln -s /path/to/MokoOnyx/src/index.php - ln -s /path/to/MokoOnyx/src/offline.php - ln -s /path/to/MokoOnyx/src/templateDetails.xml - ln -s /path/to/MokoOnyx/src/joomla.asset.json - ln -s /path/to/MokoOnyx/src/html - ln -s /path/to/MokoOnyx/src/language - ln -s /path/to/MokoOnyx/src/administrator - - # Link media separately - ln -s /path/to/MokoOnyx/src/media /path/to/joomla/media/templates/site/mokoonyx - ``` - -## Troubleshooting - -### Language Files Not Loading - -**Problem**: Language strings appear as language keys (e.g., `TPL_MOKOONYX_LABEL`) - -**Solution**: Ensure the `language` and `administrator` folders are present in your template directory: - -```bash -# Check if folders exist -ls -la /path/to/joomla/templates/mokoonyx/language -ls -la /path/to/joomla/templates/mokoonyx/administrator -``` - -The `templateDetails.xml` should contain (lines 54-55): -```xml - - - language - administrator - -``` - -### CSS/JS Not Loading - -**Problem**: Styles or scripts don't apply - -**Solution**: Verify media files are in the correct location: - -```bash -# Check media directory structure -ls -la /path/to/joomla/media/templates/site/mokoonyx/ -# Should show: css/, js/, images/, fonts/ -``` - -Clear Joomla cache: -- Admin: **System → Clear Cache** -- Check browser developer console for 404 errors - -### Template Not Appearing in Template Manager - -**Problem**: MokoOnyx doesn't show in **System → Site Templates** - -**Solution**: -1. Verify `templateDetails.xml` is present in `/path/to/joomla/templates/mokoonyx/` -2. Check file permissions (should be readable by web server) -3. Verify XML is well-formed: - ```bash - xmllint --noout /path/to/joomla/templates/mokoonyx/templateDetails.xml - ``` -4. Check Joomla's error logs for XML parsing errors - -### File Permission Issues - -**Problem**: "Permission denied" or template files not readable - -**Solution**: -```bash -# Set proper ownership (replace www-data with your web server user) -chown -R www-data:www-data /path/to/joomla/templates/mokoonyx -chown -R www-data:www-data /path/to/joomla/media/templates/site/mokoonyx - -# Set proper permissions -find /path/to/joomla/templates/mokoonyx -type d -exec chmod 755 {} \; -find /path/to/joomla/templates/mokoonyx -type f -exec chmod 644 {} \; -find /path/to/joomla/media/templates/site/mokoonyx -type d -exec chmod 755 {} \; -find /path/to/joomla/media/templates/site/mokoonyx -type f -exec chmod 644 {} \; -``` - -## When to Use Manual Deployment - -### ✅ Use Manual Deployment For: - -- **Active Development**: Testing changes immediately without rebuilding packages -- **Local Development**: Working on a local Joomla instance -- **Quick Fixes**: Making emergency hotfixes directly on a development server -- **Learning**: Understanding the template structure and Joomla's file organization - -### ❌ Don't Use Manual Deployment For: - -- **Production Sites**: Always use packaged ZIP files from releases -- **Client Sites**: Use proper Joomla extension installation -- **Version Control**: Can lead to inconsistent deployments -- **Staging Environments**: Use CI/CD or release packages - -## Best Practices - -1. **Always Test Locally First**: Don't deploy untested changes to production -2. **Keep Backups**: Back up both template and media directories before updating -3. **Use Version Control**: Track your customizations separately from manual deployments -4. **Document Changes**: Note any manual file modifications -5. **Clear Cache**: Always clear Joomla cache after manual file updates -6. **Verify Permissions**: Ensure web server can read all files - -## Related Documentation - -- **[Quick Start Guide](QUICK_START.md)** - Development environment setup -- **[Joomla Development Guide](JOOMLA_DEVELOPMENT.md)** - Complete development workflows -- **[Release Process](RELEASE_PROCESS.md)** - How to create proper release packages - -## Support - -If you encounter issues with manual deployment: - -1. Check this troubleshooting guide first -2. Review [Joomla's template documentation](https://docs.joomla.org/J4.x:Creating_a_Simple_Template) -3. Open an issue on [GitHub](https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx/issues) -4. Contact: hello@mokoconsulting.tech - ---- - -**Document Version**: 1.0.0 -**Last Updated**: 2026-03-01 -**Status**: Active diff --git a/docs/MODULE_COLOR_SCHEME.md b/docs/MODULE_COLOR_SCHEME.md deleted file mode 100644 index e94d9a5..0000000 --- a/docs/MODULE_COLOR_SCHEME.md +++ /dev/null @@ -1,82 +0,0 @@ - - -# Per-Module Color Scheme - -Force any module into dark or light mode regardless of the site's current theme. - -## Usage - -1. Open the module in **Content > Site Modules** -2. Go to the **Advanced** tab -3. In **Module Class Suffix**, enter `theme-dark` or `theme-light` -4. Save - -The module will render in the specified color scheme — even if the rest of the page uses the opposite theme. - -## Examples - -### Dark module on a light page - -Set Module Class Suffix to `theme-dark`: - -``` -Module Class Suffix: theme-dark -``` - -The module gets a dark background with light text, using the same dark palette variables defined in your theme. - -### Light module on a dark page - -``` -Module Class Suffix: theme-light -``` - -### Combining with other suffixes - -You can combine `theme-dark` or `theme-light` with other CSS classes: - -``` -Module Class Suffix: theme-dark shadow-lg rounded-3 -``` - -## How It Works - -1. **CSS variables are scoped to `[data-bs-theme]`** (not just `:root`), so they apply to any element with the attribute — including module wrappers -2. **JavaScript** scans for `.theme-dark` and `.theme-light` classes on page load and adds `data-bs-theme="dark"` or `data-bs-theme="light"` to those elements -3. **Bootstrap 5.3+** natively supports `data-bs-theme` on any element, so all Bootstrap components inside the module (buttons, cards, alerts, etc.) also switch automatically - -## Supported Module Types - -All module types work — the feature operates at the HTML class level, not the module override level. This includes: - -- Custom HTML modules -- Menu modules -- Article modules -- Login modules -- Third-party modules (VirtueMart, DPCalendar, Community Builder, etc.) -- Any module using the card layout chrome - -## Custom Palettes - -If you use custom color palettes (`light.custom.css` / `dark.custom.css`), the module will inherit those custom variables when themed. No additional configuration needed — the same palette files apply to both page-level and module-level theming. - -## Technical Notes - -- The `data-bs-theme` attribute is set via JavaScript after DOM load -- CSS selectors use `[data-bs-theme="dark"]` without `:root` prefix, enabling nested scoping -- Themed modules get `background-color: var(--body-bg)` and `color: var(--body-color)` automatically -- The theme toggle (light/dark switch) only changes `:root` — it does not override module-level `data-bs-theme` attributes. Modules with an explicit suffix always stay in their specified scheme. diff --git a/docs/MODULE_OVERRIDES.md b/docs/MODULE_OVERRIDES.md deleted file mode 100644 index fddf8d7..0000000 --- a/docs/MODULE_OVERRIDES.md +++ /dev/null @@ -1,725 +0,0 @@ - - -# Module & Component Overrides — MokoOnyx - -This document provides a comprehensive guide to all mobile-responsive module and component overrides included in MokoOnyx. - -## Overview - -MokoOnyx includes **16 mobile-responsive module overrides** and **12 component view overrides** designed to enhance the mobile user experience for third-party extensions and the Main Menu navigation. - -**Important**: Following Cassiopeia template best practices, MokoOnyx avoids overriding standard Joomla core modules (such as mod_search, mod_login, mod_breadcrumbs) to ensure proper language loading and compatibility. **Exception**: mod_menu "Main Menu" override provides essential Bootstrap 5 collapsible dropdown functionality. - -### Alternative Layouts, Not Replacements - -**All MokoOnyx overrides use alternative layout names (`mobile.php`) instead of replacing default layouts (`default.php`).** This means: - -- ✅ Default Joomla layouts continue to work unchanged -- ✅ You must explicitly select the "mobile" layout in module/menu item settings -- ✅ Joomla core updates don't break your site -- ✅ Full control over which modules use enhanced layouts - -**📖 See [OVERRIDE_PHILOSOPHY.md](OVERRIDE_PHILOSOPHY.md) for complete details on how to activate and use these alternative layouts.** - -### Key Features - -All module overrides share these characteristics: - -- **Mobile-First Design**: Optimized for mobile devices with responsive breakpoints -- **Touch Targets**: 48px on mobile, 44px on desktop (WCAG 2.1 compliant) -- **Input Font Size**: 16px minimum on mobile (prevents iOS zoom) -- **Accessibility**: Full ARIA labels, keyboard navigation, semantic HTML -- **BEM Naming**: Consistent CSS class naming convention -- **CSS Variables**: Integration with template color schemes -- **Security**: Proper escaping, _JEXEC checks, index.html protection -- **Documentation**: Each override includes comprehensive README - -## Module Categories - -### 1. VirtueMart E-Commerce Modules - -Five comprehensive overrides for VirtueMart shopping functionality. - -**Master Documentation**: [VIRTUEMART_MODULES_README.md](../src/html/VIRTUEMART_MODULES_README.md) - -#### mod_virtuemart_cart -**Location**: `src/html/mod_virtuemart_cart/` - -Shopping cart display with product list and checkout button. - -**Features**: -- Responsive product cards -- Remove item buttons with confirmations -- Price display with currency formatting -- Checkout button with prominent styling - -#### mod_virtuemart_product -**Location**: `src/html/mod_virtuemart_product/` - -Product showcase with grid layouts. - -**Features**: -- Responsive grid: 1-4 columns based on screen size -- Product images with hover effects -- Price display and "Add to Cart" buttons -- Rating display support - -#### mod_virtuemart_currencies -**Location**: `src/html/mod_virtuemart_currencies/` - -Currency selector dropdown for multi-currency stores. - -**Features**: -- Accessible dropdown with proper labels -- Currency symbol and name display -- Responsive button styling - -#### mod_virtuemart_category -**Location**: `src/html/mod_virtuemart_category/` - -Category navigation with hierarchical display. - -**Features**: -- Expandable subcategories -- Product count display -- Hierarchical indentation -- Active category highlighting - -#### mod_virtuemart_manufacturer -**Location**: `src/html/mod_virtuemart_manufacturer/` - -Manufacturer/brand display with grid layout. - -**Features**: -- Responsive grid: 2-4 columns -- Logo display support -- Product count per manufacturer - ---- - -### 2. Main Menu & Community Builder Modules - -Three essential Community Builder and navigation module overrides. - -#### mod_menu (Main Menu) -**Location**: `src/html/mod_menu/` - -Bootstrap 5 responsive navigation menu with collapsible dropdown functionality. - -**Files**: -- `mainmenu.php` - Main layout with Bootstrap navbar -- `mainmenu_component.php` - Component menu items -- `mainmenu_heading.php` - Heading menu items -- `mainmenu_separator.php` - Separator menu items -- `mainmenu_url.php` - URL menu items - -**Features**: -- Bootstrap 5 navbar structure with collapsible hamburger menu -- Multi-level dropdown support (hover on desktop, tap on mobile) -- WCAG 2.1 compliant touch targets (48px mobile, 44px desktop) -- BEM naming convention: `.mod-menu-main__*` -- Active state indicators for current menu items -- ARIA labels and keyboard navigation support -- Alternative layout named `mainmenu.php` (not `default.php`) - -**Activation**: Select "Mainmenu" layout in Joomla Administrator → Modules → Menu Module → Advanced Tab → Alternative Layout - -**Note**: Unlike the broken mod_menu override removed in v03.08.01, this v03.08.03 version is properly structured based on Joomla core layouts and Bootstrap 5, ensuring language strings load correctly and menu functionality works as expected. - -#### mod_cblogin -**Location**: `src/html/mod_cblogin/` - -Community Builder login with avatar display. - -**Features**: -- User avatar when logged in -- CB-specific login form -- Profile link -- Logout button - -#### mod_comprofilerOnline -**Location**: `src/html/mod_comprofilerOnline/` - -Community Builder online users display. - -**Features**: -- User count display -- Avatar grid layout -- Username display -- Online status indicators - ---- - -### 3. Industry Extension Modules - -Eight popular third-party extension module overrides plus component views. - -#### K2 Content Extension - -##### mod_k2_content -**Location**: `src/html/mod_k2_content/` - -K2 content display with advanced layouts. - -**Features**: -- Responsive grid: 1-3 columns -- Featured images with lazy loading -- Category, author, date metadata -- Excerpt support -- Tag display - -#### AcyMailing Newsletter - -##### mod_acymailing -**Location**: `src/html/mod_acymailing/` - -Newsletter subscription form. - -**Features**: -- Email validation -- Privacy checkbox -- Success/error messaging -- GDPR compliance fields - -#### HikaShop E-Commerce - -##### mod_hikashop_cart -**Location**: `src/html/mod_hikashop_cart/` - -HikaShop shopping cart module. - -**Features**: -- Product list with images -- Quantity adjustment -- Price totals -- Checkout button - -#### Kunena Forum - -Four comprehensive forum modules plus component view. - -##### mod_kunenalatest -**Location**: `src/html/mod_kunenalatest/` - -Latest forum posts display. - -**Features**: -- Post excerpts -- Author avatars -- Reply count -- Post date - -##### mod_kunenalogin -**Location**: `src/html/mod_kunenalogin/` - -Forum-specific login module. - -**Features**: -- User avatar display -- Forum statistics -- Quick login form -- Profile link - -##### mod_kunenasearch -**Location**: `src/html/mod_kunenasearch/` - -Forum search with button positions. - -**Features**: -- Multiple button positions (left, right, top) -- Search placeholder text -- Icon support -- 48px touch targets - -##### mod_kunenastats -**Location**: `src/html/mod_kunenastats/` - -Forum statistics display. - -**Features**: -- Visual stat cards -- Member count -- Topic/post totals -- Latest member -- Responsive grid layout - -##### com_kunena (Component) -**Location**: `src/html/com_kunena/` - -Forum category list view. - -**Views**: -- `category/default.php` - Category listing with icons - -#### OS Membership Pro - -Module and component overrides for membership management. - -##### mod_osmembership -**Location**: `src/html/mod_osmembership/` - -Membership plans module. - -**Features**: -- Plan cards with pricing -- Feature lists -- Signup buttons -- Badge displays (popular, featured) - -##### com_osmembership (Component) -**Location**: `src/html/com_osmembership/` - -Membership pricing tables. - -**Views**: -- `plans/default.php` - Responsive pricing table with comparison features - ---- - -### 4. Community Builder Components - -Four comprehensive component view overrides for Community Builder user management. - -#### com_comprofiler -**Location**: `src/html/com_comprofiler/` - -Mobile-responsive views for Community Builder user profiles, registration, and login. - -##### userprofile -User profile display with tabbed interface. - -**Features**: -- Large avatar display (150px) -- Tabbed interface for profile sections -- Custom field display with labels -- Online status indicator -- Responsive layout: vertical mobile → horizontal desktop - -##### userslist -User directory with search and grid layout. - -**Features**: -- Search functionality with accessible form -- Responsive grid: 1 column mobile → 2-3 columns desktop -- User cards with avatars (80px) -- Custom field display -- Profile view buttons -- Pagination support - -##### registers -Multi-step registration form with validation. - -**Features**: -- Fieldset organization with legends -- Required field indicators (*) -- Input validation and error display -- Captcha support section -- Terms & conditions checkbox -- GDPR-compliant design -- 16px input font on mobile - -##### login -Login page with remember me and helper links. - -**Features**: -- Centered login container (max-width: 450px) -- Username/password fields with autocomplete -- Remember me checkbox -- Registration and password recovery links -- CSRF token support -- Responsive padding adjustments - -### 5. JEM (Joomla Event Manager) Components - -Five comprehensive component view overrides for JEM event management. - -#### com_jem -**Location**: `src/html/com_jem/` - -Mobile-responsive views for JEM event listings, details, calendar, venues, and categories. - -##### eventslist -Event listing with card-based layout. - -**Features**: -- Event cards with date, time, and venue -- Category badges with color coding -- Responsive event grid layout -- Event description excerpts -- Read more buttons with clear calls-to-action -- Pagination support -- Empty state messaging - -##### event -Single event details view with comprehensive information. - -**Features**: -- Large event image display (responsive) -- Date and time with structured data -- Venue information with maps link -- Event description with full content -- Category display with badges -- Registration information (if enabled) -- Contact information display -- Back to events navigation -- Meta information with icons - -##### calendar -Monthly calendar view with event indicators. - -**Features**: -- Month navigation (previous/next) -- Calendar grid with weekday headers -- Event indicators on dates with events -- Responsive calendar layout -- Today highlighting -- Event list for selected month -- Event count per day display -- Touch-friendly navigation buttons - -##### venue -Venue details with location and upcoming events. - -**Features**: -- Venue image display -- Complete address information -- Website link (external) -- Google Maps integration -- Venue description -- Upcoming events at venue -- Location coordinates display -- Back navigation - -##### categories -Event category listing with descriptions. - -**Features**: -- Category cards with images -- Category descriptions -- Event count per category -- View category buttons -- Responsive grid layout -- Empty state messaging -- Pagination support - ---- - -## CSS Architecture - -All module styles are located in `src/media/css/template.css` with dedicated sections: - -### CSS Sections - -1. **MOD_SEARCH MOBILE RESPONSIVE STYLES** (Lines ~18400+) - - Search box layouts - - Button position variants - - Input styling - -2. **VIRTUEMART MODULE MOBILE RESPONSIVE STYLES** (Lines ~18500+) - - Cart product cards - - Product grids - - Currency selector - - Category navigation - - Manufacturer displays - -3. **STANDARD JOOMLA & COMMUNITY BUILDER MODULE STYLES** (Lines ~19300+) - - Menu navigation - - Breadcrumbs - - Login forms - - Article displays - - CB module components - -4. **INDUSTRY EXTENSION MODULE STYLES** (Lines ~19800+) - - K2 content grids - - AcyMailing forms - - HikaShop cart - - Kunena forum modules - - OS Membership pricing - -5. **COMMUNITY BUILDER COMPONENT STYLES** (Lines ~21000+) - - User profile layouts - - Users list grids - - Registration forms - - Login pages - - Tab interfaces - -6. **JEM COMPONENT STYLES** (Lines ~22000+) - - Event list cards - - Event details layout - - Calendar grid - - Venue information - - Category displays - -### CSS Variables Integration - -All modules integrate with template CSS variables: - -```css -/* Common Variables Used */ ---body-color /* Text color */ ---link-color /* Link color */ ---link-hover-color /* Link hover color */ ---border-color /* Border color */ ---secondary-bg /* Background color */ ---border-radius /* Border radius */ ---input-bg /* Input background */ ---input-border-color /* Input border */ ---btn-primary-bg /* Primary button */ ---btn-primary-hover-bg /* Button hover */ -``` - -See [CSS_VARIABLES.md](CSS_VARIABLES.md) for complete reference. - ---- - -## Responsive Breakpoints - -All modules use Bootstrap-aligned breakpoints: - -| Breakpoint | Size | Typical Changes | -|------------|-----------|-----------------------------------| -| `xs` | < 576px | Single column, stacked layouts | -| `sm` | ≥ 576px | 2 columns for grids | -| `md` | ≥ 768px | 3 columns, horizontal layouts | -| `lg` | ≥ 992px | 4 columns, expanded spacing | -| `xl` | ≥ 1200px | Maximum width, optimal spacing | -| `xxl` | ≥ 1400px | Extra spacing | - ---- - -## Accessibility Features - -All overrides implement comprehensive accessibility: - -### ARIA Labels -- Descriptive labels for all interactive elements -- `aria-label` for icon-only buttons -- `aria-describedby` for form fields -- `aria-live` for dynamic content - -### Keyboard Navigation -- Proper tab order -- Focus states on all interactive elements -- Keyboard-accessible dropdowns -- Skip links where appropriate - -### Screen Readers -- Semantic HTML5 elements -- Hidden text for icon-only elements -- Proper heading hierarchy -- Alternative text for images - -### WCAG 2.1 Compliance -- Touch targets: 48px minimum on mobile -- Color contrast ratios meet AA standards -- Text resizable to 200% without loss -- No content relies on color alone - ---- - -## Customization Guide - -### Override Customization - -Each module can be customized in two ways: - -#### 1. CSS Customization - -Edit `src/media/css/user.css` to add custom styles: - -```css -/* Example: Change product grid columns */ -@media (min-width: 768px) { - .mod-vm-product__grid { - grid-template-columns: repeat(3, 1fr); - } -} - -/* Example: Customize cart button */ -.mod-vm-cart__checkout-button { - background-color: #28a745; -} -``` - -#### 2. Template Override Customization - -Copy the entire module directory and modify: - -```bash -# Keep original override as reference -cp -r src/html/mod_virtuemart_cart src/html/mod_virtuemart_cart_original - -# Modify your version -# Edit src/html/mod_virtuemart_cart/default.php -``` - -### CSS Variables Override - -Override CSS variables in your custom color scheme: - -```css -/* src/media/css/theme/light.custom.css */ -:root { - --vm-price-color: #28a745; - --vm-cart-bg: #f8f9fa; - --vm-button-primary: #007bff; -} -``` - ---- - -## Best Practices - -### When Using Overrides - -1. **Test Across Devices**: Always test on actual mobile devices -2. **Maintain Accessibility**: Don't remove ARIA labels or keyboard navigation -3. **Keep BEM Naming**: Use established class naming patterns -4. **Security First**: Always escape output and validate input -5. **Document Changes**: Comment your customizations - -### When Updating - -1. **Backup First**: Always backup your site before updating -2. **Review Changes**: Check CHANGELOG.md for breaking changes -3. **Test Thoroughly**: Test all modules after updates -4. **Custom Overrides**: May need adjustments after template updates - ---- - -## Troubleshooting - -### Common Issues - -#### Module Not Displaying Correctly -1. Clear Joomla cache (System → Clear Cache) -2. Check module is published and assigned to correct position -3. Verify template is assigned to menu items -4. Check browser console for JavaScript errors - -#### Styles Not Applying -1. Clear browser cache (Ctrl+F5 / Cmd+Shift+R) -2. Verify `template.css` is loading -3. Check CSS specificity conflicts -4. Review custom CSS in `user.css` - -#### Mobile View Issues -1. Test with browser dev tools responsive mode -2. Check viewport meta tag in template -3. Verify breakpoint media queries -4. Test on actual devices when possible - -#### Accessibility Issues -1. Run WAVE or axe DevTools accessibility check -2. Test with keyboard navigation only -3. Verify screen reader compatibility -4. Check color contrast ratios - -### Getting Help - -- **Documentation**: Check module-specific README files -- **GitHub Issues**: [Report issues](https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx/issues) -- **Support**: hello@mokoconsulting.tech - ---- - -## How to Activate Alternative Layouts - -All MokoOnyx overrides are **alternative layouts** that must be explicitly activated. They do not automatically replace default layouts. - -### Quick Start: Enable Mobile Layout - -1. **Go to Joomla Administrator** → Extensions → Modules -2. **Open the module** you want to enhance (e.g., VirtueMart Cart) -3. **Navigate to Advanced tab** -4. **Find "Alternative Layout" field** -5. **Select "MokoOnyx - mobile"** from dropdown -6. **Save & Close** - -### For Menu Items (Component Views) - -1. **Go to Menus** → Select your menu -2. **Open the menu item** (e.g., Events List) -3. **Navigate to Advanced Options or Page Display tab** -4. **Find "Alternative Layout" field** -5. **Select "MokoOnyx - mobile"** from dropdown -6. **Save & Close** - -### Apply to All Modules in a Position - -In your template's `index.php`, specify layout for entire module position: - -```php - -``` - -**📖 For complete documentation, see [OVERRIDE_PHILOSOPHY.md](OVERRIDE_PHILOSOPHY.md)** - ---- - -## Version History - -| Version | Date | Changes | -|----------|------------|--------------------------------------------------| -| 03.08.04 | 2026-02-27 | Added alternative layout activation instructions, JEM overrides | -| 03.08.03 | 2026-02-25 | Removed mod_search override per Cassiopeia philosophy | -| 03.08.00 | 2026-02-22 | Added Community Builder component overrides | -| 03.07.00 | 2026-02-22 | Initial release of all mobile-responsive overrides | - ---- - -## Additional Resources - -- **Override Philosophy**: [OVERRIDE_PHILOSOPHY.md](OVERRIDE_PHILOSOPHY.md) ⭐ **Start here** -- **Main README**: [README.md](../README.md) -- **Changelog**: [CHANGELOG.md](../CHANGELOG.md) -- **CSS Variables**: [CSS_VARIABLES.md](CSS_VARIABLES.md) -- **Repository**: [GitHub](https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx) - ---- - -## Metadata - -* Document: docs/MODULE_OVERRIDES.md -* Repository: [https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx](https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx) -* Path: /docs/MODULE_OVERRIDES.md -* Owner: Moko Consulting -* Version: 03.07.00 -* Status: Active -* Effective Date: 2026-02-22 -* Classification: Public Open Source Documentation - -## Revision History - -| Date | Change Summary | Author | -| ---------- | ----------------------------------------------------- | --------------- | -| 2026-02-22 | Initial creation with comprehensive module override documentation | GitHub Copilot | diff --git a/docs/OVERRIDE_PHILOSOPHY.md b/docs/OVERRIDE_PHILOSOPHY.md deleted file mode 100644 index 0761a8d..0000000 --- a/docs/OVERRIDE_PHILOSOPHY.md +++ /dev/null @@ -1,332 +0,0 @@ - - -# Override Philosophy — MokoOnyx - -## Core Principle: Add-On, Not Replacement - -**MokoOnyx overrides are designed as alternative layouts, not replacements of default Joomla layouts.** - -This means: -- ✅ Default Joomla layouts continue to work unchanged -- ✅ Site administrators can choose when to use our enhanced layouts -- ✅ Updates to Joomla core layouts don't break the site -- ✅ Compatibility with other extensions is maintained -- ✅ Users have control over which layouts to use - ---- - -## Technical Implementation - -### Layout Naming Convention - -All MokoOnyx overrides use **`mobile.php`** naming instead of **`default.php`**: - -``` -❌ BAD (Replaces default): -src/html/mod_virtuemart_cart/default.php - -✅ GOOD (Alternative layout): -src/html/mod_virtuemart_cart/mobile.php -``` - -### How Joomla Handles Layouts - -When a module or component looks for a layout, Joomla searches in this order: - -1. **Template override with specified layout name**: `templates/mokoonyx/html/{extension}/{view}/{layout}.php` -2. **Extension's specified layout**: `{extension}/tmpl/{view}/{layout}.php` -3. **Template override for default layout**: `templates/mokoonyx/html/{extension}/{view}/default.php` -4. **Extension's default layout**: `{extension}/tmpl/{view}/default.php` - -By naming our overrides `mobile.php` instead of `default.php`, they become **step 1** alternatives that must be explicitly selected, rather than **step 3** replacements that are automatically used. - ---- - -## How to Use Alternative Layouts - -### Method 1: Module/Menu Item Settings - -When editing a module or menu item in Joomla administrator: - -1. Open the module/menu item for editing -2. Navigate to the **Advanced** tab -3. Find the **Alternative Layout** field -4. Select **MokoOnyx - mobile** from the dropdown -5. Save - -### Method 2: Override in Module Position - -If you want all modules in a specific position to use the mobile layout: - -```php - -countModules('sidebar-left')) : ?> - - -``` - -### Method 3: Module Chrome (Advanced) - -Create a custom module chrome in `templates/mokoonyx/html/layouts/chromes/` that automatically applies the mobile layout. - ---- - -## Exception: Main Menu - -**The only exception** to this philosophy is `mod_menu` with the "Main Menu" module type. - -The template includes files like: -- `src/html/mod_menu/mainmenu.php` -- `src/html/mod_menu/mainmenu_component.php` -- `src/html/mod_menu/mainmenu_heading.php` -- `src/html/mod_menu/mainmenu_url.php` -- `src/html/mod_menu/mainmenu_separator.php` - -These use a **custom layout name** (`mainmenu`) instead of replacing `default.php`, which allows the site to: -- Use the enhanced Bootstrap 5 collapsible menu for main navigation -- Keep standard Joomla menus working in other positions -- Provide better mobile navigation without breaking existing menus - -To use this layout, set the module's **Alternative Layout** to **MokoOnyx - mainmenu**. - ---- - -## Override Inventory - -### Module Overrides (16 total) - -All use `mobile.php` naming (alternative layout): - -**VirtueMart (5)**: -- `mod_virtuemart_cart/mobile.php` -- `mod_virtuemart_product/mobile.php` -- `mod_virtuemart_currencies/mobile.php` -- `mod_virtuemart_category/mobile.php` -- `mod_virtuemart_manufacturer/mobile.php` - -**Community Builder (2)**: -- `mod_cblogin/mobile.php` -- `mod_comprofilerOnline/mobile.php` - -**Main Menu (1)**: -- `mod_menu/mainmenu.php` (custom layout name) - -**Industry Extensions (8)**: -- `mod_k2_content/mobile.php` -- `mod_acymailing/mobile.php` -- `mod_hikashop_cart/mobile.php` -- `mod_kunenalatest/mobile.php` -- `mod_kunenalogin/mobile.php` -- `mod_kunenasearch/mobile.php` -- `mod_kunenastats/mobile.php` -- `mod_osmembership/mobile.php` - -### Component View Overrides (12 total) - -All use `mobile.php` naming (alternative layout): - -**Community Builder (4)**: -- `com_comprofiler/userprofile/mobile.php` -- `com_comprofiler/userslist/mobile.php` -- `com_comprofiler/registers/mobile.php` -- `com_comprofiler/login/mobile.php` - -**JEM - Joomla Event Manager (5)**: -- `com_jem/eventslist/mobile.php` -- `com_jem/event/mobile.php` -- `com_jem/calendar/mobile.php` -- `com_jem/venue/mobile.php` -- `com_jem/categories/mobile.php` - -**Kunena Forum (1)**: -- `com_kunena/category/mobile.php` - -**OSMembership (2)**: -- `com_osmembership/plan/mobile.php` -- `com_osmembership/plans/mobile.php` - -**Joomla Core (2)**: -- `com_content/article/toc-left.php` (custom layout name) -- `com_content/article/toc-right.php` (custom layout name) - ---- - -## Benefits of This Approach - -### 1. **Zero Breaking Changes** - -Existing sites continue to work exactly as before. No layouts are forcibly changed. - -### 2. **Gradual Adoption** - -Site administrators can: -- Test mobile layouts on specific modules first -- Roll out changes module-by-module -- Keep some modules using default layouts if needed -- Easily revert by changing the Alternative Layout setting - -### 3. **Extension Compatibility** - -Third-party extensions' default layouts remain untouched, preventing conflicts with: -- Extension updates -- Other templates -- Custom development - -### 4. **Joomla Core Updates** - -When Joomla core updates: -- Default layouts get new features/bug fixes automatically -- Mobile layouts remain stable and tested -- No emergency fixes needed after Joomla updates - -### 5. **Multi-Language Support** - -Joomla's language system loads extension language files properly because: -- Extensions aren't hijacked by template overrides -- Language strings come from the correct source -- Translations work as expected - ---- - -## Standards Not Overridden - -Following Cassiopeia template best practices, MokoOnyx **does not override** standard Joomla core modules: - -- ❌ `mod_breadcrumbs` - Use Joomla core layout -- ❌ `mod_login` - Use Joomla core layout -- ❌ `mod_articles_latest` - Use Joomla core layout -- ❌ `mod_articles_category` - Use Joomla core layout -- ❌ `mod_articles_news` - Use Joomla core layout -- ❌ `mod_search` - Use Joomla core layout (removed in v03.08.03) - -**Reason**: These modules have robust core layouts with proper language loading, accessibility, and ongoing Joomla maintenance. - ---- - -## Developer Guidelines - -When adding new overrides to MokoOnyx: - -### ✅ DO: - -1. Name files `mobile.php` or use descriptive custom names (`mainmenu.php`, `toc-left.php`) -2. Document the alternative layout in MODULE_OVERRIDES.md -3. Add CSS with BEM naming: `.{extension}-{view}__element` -4. Test that default layouts still work -5. Provide clear instructions for selecting the layout - -### ❌ DON'T: - -1. Create `default.php` files that replace core layouts -2. Override standard Joomla core modules without strong justification -3. Break backward compatibility -4. Assume users will automatically get your layout -5. Forget to document how to enable the alternative layout - ---- - -## Migration from Replacing Overrides - -If you're migrating from a template that used `default.php` overrides: - -### Step 1: Identify Replaced Layouts - -```bash -find templates/oldtemplate/html -name "default.php" -``` - -### Step 2: Rename to Alternative Layouts - -```bash -# For each default.php found: -mv default.php mobile.php -``` - -### Step 3: Update Module Settings - -For each module using the old override: -1. Edit module in administrator -2. Advanced tab → Alternative Layout -3. Select "mobile" from dropdown -4. Save - -### Step 4: Test - -- Verify module displays correctly -- Check that other modules still use default layouts -- Confirm language strings load properly - ---- - -## Troubleshooting - -### My Alternative Layout Doesn't Appear in Dropdown - -**Check:** -1. File is in correct location: `templates/mokoonyx/html/{extension}/{view}/` -2. File has `.php` extension -3. File is not named `default.php` -4. Cache is cleared (System → Clear Cache) - -### Module Still Uses Default Layout - -**Check:** -1. Module's Alternative Layout setting in administrator -2. Module position's `layout` parameter in `` tag -3. File permissions (must be readable) -4. Template is assigned to correct pages - -### Layout Works But Looks Wrong - -**Check:** -1. CSS is loaded: inspect element and check for `.{extension}-{view}__` classes -2. `template.css` is up to date -3. Browser cache is cleared -4. CSS variables are defined in template - ---- - -## References - -- [Joomla Docs: Layout Overrides](https://docs.joomla.org/Layout_Overrides_in_Joomla) -- [Joomla Docs: Alternative Layouts](https://docs.joomla.org/J3.x:How_to_use_the_alternative_layout_feature) -- [MODULE_OVERRIDES.md](MODULE_OVERRIDES.md) - Complete override inventory -- [CSS_VARIABLES.md](CSS_VARIABLES.md) - Template styling system - ---- - -## Version History - -- **03.08.04**: Created OVERRIDE_PHILOSOPHY.md document -- **03.08.03**: Removed mod_search override to align with philosophy -- **03.08.02**: Removed standard Joomla module overrides for proper language loading -- **Earlier**: Renamed all overrides from default.php to mobile.php (21 files) diff --git a/docs/QUICK_START.md b/docs/QUICK_START.md deleted file mode 100644 index 7cc82e0..0000000 --- a/docs/QUICK_START.md +++ /dev/null @@ -1,333 +0,0 @@ -# Quick Start Guide - MokoOnyx Development - -Get up and running with MokoOnyx development in minutes. - -## Prerequisites - -Before you begin, ensure you have: - -- **Git** - For version control -- **PHP 8.0+** - Required runtime -- **Composer** - PHP dependency manager -- **Make** (optional) - For convenient commands -- **Code Editor** - VS Code recommended (tasks pre-configured) - -## 5-Minute Setup - -### 1. Clone the Repository - -```bash -git clone https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx.git -cd MokoOnyx -``` - -### 2. Install Development Dependencies - -```bash -# Using Make (recommended) -make dev-setup - -# Or manually -composer global require "squizlabs/php_codesniffer:^3.0" -composer global require phpstan/phpstan -composer global require "phpcompatibility/php-compatibility:^9.0" -composer global require codeception/codeception -``` - -### 3. Validate Everything Works - -```bash -# Quick validation -make validate-required - -# Or comprehensive validation -make validate -``` - -## Common Tasks - -### Development Workflow - -```bash -# 1. Make your changes -vim src/index.php - -# 2. Validate locally -make validate-required - -# 3. Check code quality -make quality - -# 4. Commit -git add -A -git commit -m "feat: add new feature" -# (pre-commit hook runs automatically) - -# 5. Push -git push origin your-branch -``` - -### Testing - -```bash -# Run all tests -make test - -# Run unit tests only -make test-unit - -# Run acceptance tests only -make test-acceptance -``` - -### Code Quality - -```bash -# Check everything -make quality - -# PHP CodeSniffer only -make phpcs - -# Auto-fix PHPCS issues -make phpcs-fix - -# PHPStan only -make phpstan - -# PHP compatibility check -make phpcompat -``` - -### Creating a Release Package - -```bash -# Package with auto-detected version -make package - -# Check package contents -ls -lh dist/ -unzip -l dist/mokoonyx-*.zip -``` - -## VS Code Integration - -If using VS Code, press `Ctrl+Shift+P` (or `Cmd+Shift+P` on Mac) and type "Run Task" to see available tasks: - -- **Validate All** - Run all validation scripts (default test task) -- **Validate Required** - Run only required validations -- **PHP CodeSniffer** - Check code style -- **PHP CodeSniffer - Auto Fix** - Fix code style issues -- **PHPStan** - Static analysis -- **Run Tests** - Execute all tests -- **Create Package** - Build distribution ZIP -- **Install Git Hooks** - Set up pre-commit hooks - -## Available Make Commands - -Run `make help` to see all available commands: - -```bash -make help # Show all commands -make dev-setup # Complete environment setup -make validate # Run all validations -make test # Run all tests -make quality # Check code quality -make package # Create distribution package -make clean # Remove generated files -make check # Quick check (validate + quality) -make all # Complete build pipeline -``` - -## Project Structure - -``` -moko-cassiopeia/ -├── src/ # Joomla template source (template root) -│ ├── component.php # Component template file -│ ├── index.php # Main template file -│ ├── offline.php # Offline page template -│ ├── error.php # Error page template -│ ├── templateDetails.xml # Template manifest -│ ├── html/ # Module & component overrides -│ ├── media/ # Assets (CSS, JS, images, fonts) -│ ├── language/ # Frontend language files (en-GB, en-US) -│ └── administrator/ # Backend files -│ └── language/ # Backend language files -├── tests/ # Test suites -├── docs/ # Documentation -├── scripts/ # Build scripts -├── .github/workflows/ # CI/CD workflows -├── Makefile # Make commands -└── README.md # Project overview -``` - -## Next Steps - -### Learning the Workflow - -1. **Read the Workflow Guide**: [docs/WORKFLOW_GUIDE.md](./WORKFLOW_GUIDE.md) -2. **Review Joomla Development**: [docs/JOOMLA_DEVELOPMENT.md](./JOOMLA_DEVELOPMENT.md) - -### Creating Your First Feature - -1. **Create a version branch** via GitHub Actions: - - Go to Actions → Create version branch - - Enter version (e.g., 03.06.00) - - Select branch prefix: `dev/` - - Run workflow - -2. **Checkout the branch**: - ```bash - git fetch origin - git checkout dev/03.06.00 - ``` - -3. **Make changes and test**: - ```bash - # Edit files - vim src/index.php - - # Validate - make validate-required - - # Check quality - make quality - ``` - -4. **Commit and push**: - ```bash - git add -A - git commit -m "feat: your feature description" - git push origin dev/03.06.00 - ``` - -5. **Watch CI**: Check GitHub Actions for automated testing - -### Understanding the Release Process - -``` -Development → RC → Stable → Production - (dev/) (rc/) (version/) (main) -``` - -1. **dev/X.Y.Z** - Active development -2. **rc/X.Y.Z** - Release candidate testing -3. **version/X.Y.Z** - Stable release -4. **main** - Production (auto-merged from version/) - -Use the Release Pipeline workflow to promote between stages. - -## Troubleshooting - -### Scripts Not Executable - -```bash -make fix-permissions -### PHPStan/PHPCS Not Found - -```bash -make install -# Or manually: -composer global require "squizlabs/php_codesniffer:^3.0" phpstan/phpstan -``` - -### CI Workflow Fails - -1. Check the workflow logs in GitHub Actions -2. Run validation locally: - ```bash - make validate-required - make quality - ``` - -### Need Help? - -- **Documentation**: Check [docs/](../docs/) directory -- **Issues**: Open an issue on GitHub -- **Contributing**: See [CONTRIBUTING.md](../CONTRIBUTING.md) - -## Best Practices - -### Before Committing - -```bash -# Always validate first -make validate-required - -# Check quality for PHP changes -make quality - -# Run tests if you changed functionality -make test -``` - -### Code Style - -- Follow PSR-12 standards -- Use `make phpcs-fix` to auto-fix issues -- Add SPDX license headers to new files -- Keep functions small and focused - -### Documentation - -- Update docs when changing workflows -- Add comments for complex logic -- Update CHANGELOG.md with changes -- Keep README.md current - -### Version Management - -- Use semantic versioning: Major.Minor.Patch (03.06.00) -- Update CHANGELOG.md with all changes -- Follow the version hierarchy: dev → rc → version → main -- Never skip stages in the release process - -## Useful Resources - -- [Joomla Documentation](https://docs.joomla.org/) -- [PSR-12 Coding Standard](https://www.php-fig.org/psr/psr-12/) -- [Semantic Versioning](https://semver.org/) -- [Conventional Commits](https://www.conventionalcommits.org/) - -## Quick Reference Card - -```bash -# Setup -make dev-setup # Initial setup - -# Development -make validate-required # Quick validation -make quality # Code quality -make test # Run tests - -# Building -make package # Create ZIP - -# Maintenance -make clean # Clean generated files -make fix-permissions # Fix script permissions - -# Help -make help # Show all commands -``` - ---- - -## Metadata - -* Document: docs/QUICK_START.md -* Repository: [https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx](https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx) -* Path: /docs/QUICK_START.md -* Owner: Moko Consulting -* Version: 03.06.03 -* Status: Active -* Effective Date: 2026-01-30 -* Classification: Public Open Source Documentation - -## Revision History - -| Date | Change Summary | Author | -| ---------- | ----------------------------------------------------- | --------------- | -| 2026-01-30 | Updated metadata to MokoStandards format | GitHub Copilot | -| 2025-01-04 | Initial quick start guide created | GitHub Copilot | diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index 676335c..0000000 --- a/docs/README.md +++ /dev/null @@ -1,188 +0,0 @@ - - -# MokoOnyx Documentation - -This directory contains comprehensive documentation for the MokoOnyx Joomla template. - -## Documentation Overview - -### Developer Documentation - -* **[Quick Start Guide](QUICK_START.md)** - Get up and running in 5 minutes - * Development environment setup - * Essential commands and workflows - * First-time contributor guide - -* **[Workflow Guide](WORKFLOW_GUIDE.md)** - Complete workflow reference - * Git branching strategy - * Development workflow - * Pull request guidelines - -* **[Release Process](RELEASE_PROCESS.md)** ⭐ - Complete release documentation - * Automated release workflow with GitHub Actions - * Manual release procedures - * Update server configuration - * Testing and rollback procedures - * Build scripts and tools - -* **[Joomla Development Guide](JOOMLA_DEVELOPMENT.md)** - Joomla-specific development - * Testing with Codeception - * PHP quality checks (PHPStan, PHPCS) - * Joomla extension packaging - * Multi-version testing - -* **[Manual Deployment Guide](MANUAL_DEPLOYMENT.md)** - Deploy src directory without building - * Understanding src vs. installed structure - * Manual deployment methods (copy, symlink) - * Troubleshooting language files and media - * Best practices for development deployments - -* **[CSS Variables Reference](CSS_VARIABLES.md)** - Complete CSS customization guide - * All available CSS variables - * Custom color palette creation - * Usage examples and tips - * Light and dark mode theming - -* **[Module & Component Overrides](MODULE_OVERRIDES.md)** - Mobile-responsive overrides guide - * 16 module overrides + 12 component overrides - * VirtueMart, Community Builder, JEM, Kunena, industry extensions - * Mobile-first responsive design patterns - * Accessibility features and customization - -* **[Override Philosophy](OVERRIDE_PHILOSOPHY.md)** ⭐ - Alternative layouts, not replacements - * Why overrides use `mobile.php` naming instead of `default.php` - * How to activate alternative layouts in Joomla - * Benefits of non-replacing overrides - * Developer guidelines and best practices - -* **[Roadmap](ROADMAP.md)** - Version-specific roadmap - * Current features (v03.07.00) - * Feature evolution timeline - * Planned enhancements - * Development priorities - -### User Documentation - -For end-user documentation, installation instructions, and feature guides, see the main [README.md](../README.md) in the repository root. - -## Project Structure - -``` -moko-cassiopeia/ -├── docs/ # Documentation (you are here) -│ ├── README.md # This file - documentation index -│ ├── QUICK_START.md # Quick start guide for developers -│ ├── WORKFLOW_GUIDE.md # Development workflow guide -│ ├── JOOMLA_DEVELOPMENT.md # Joomla-specific development guide -│ ├── CSS_VARIABLES.md # CSS variables reference -│ ├── MODULE_OVERRIDES.md # Module & component overrides guide -│ └── ROADMAP.md # Version-specific roadmap -├── src/ # Template source code (Joomla template root) -│ ├── component.php # Component template -│ ├── index.php # Main template file -│ ├── offline.php # Offline template -│ ├── error.php # Error page template -│ ├── templateDetails.xml # Template manifest -│ ├── html/ # Module & component overrides (16 modules, 12 components) -│ ├── media/ # Assets (CSS, JS, images, fonts) -│ │ ├── css/ # Stylesheets -│ │ │ └── colors/ # Color schemes -│ │ │ ├── light/ # Light mode color files (colors_standard.css) -│ │ │ └── dark/ # Dark mode color files (colors_standard.css) -│ │ ├── js/ # JavaScript files -│ │ ├── images/ # Image assets -│ │ └── fonts/ # Font files -│ ├── language/ # Frontend language files -│ │ ├── en-GB/ # English (UK) translations -│ │ └── en-US/ # English (US) translations -│ └── administrator/ # Backend files -│ └── language/ # Backend language files -│ ├── en-GB/ # English (UK) system translations -│ └── en-US/ # English (US) system translations -├── templates/ # Reserved for future template files -│ └── README.md # Templates directory guide -├── scripts/ # Build and utility scripts -├── tests/ # Automated tests -└── .github/ # GitHub configuration and workflows -``` - -## Contributing - -Before contributing, please read: - -1. **[CONTRIBUTING.md](../CONTRIBUTING.md)** - Contribution guidelines and standards -2. **[CODE_OF_CONDUCT.md](../CODE_OF_CONDUCT.md)** - Community standards and expectations -3. **[SECURITY.md](../SECURITY.md)** - Security policy and reporting procedures - -## Standards Compliance - -This project adheres to [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/MokoStandards) for: - -* Coding standards and formatting -* Documentation requirements -* Git workflow and branching -* CI/CD pipeline configuration -* Security scanning and dependency management - -## Additional Resources - -* **Repository**: [https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx](https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx) -* **Issue Tracker**: [GitHub Issues](https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx/issues) -* **Changelog**: [CHANGELOG.md](../CHANGELOG.md) -* **License**: [GPL-3.0-or-later](../LICENSE) - -## Support - -* **Email**: hello@mokoconsulting.tech -* **Website**: https://mokoconsulting.tech/support/joomla-cms/moko-cassiopeia-roadmap - ---- - -## Metadata - -* Document: docs/README.md -* Repository: [https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx](https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx) -* Path: /docs/README.md -* Owner: Moko Consulting -* Version: 03.07.00 -* Status: Active -* Effective Date: 2026-01-30 -* Classification: Public Open Source Documentation - -## Revision History - -| Date | Change Summary | Author | -| ---------- | ----------------------------------------------------- | --------------- | -| 2026-02-22 | Added MODULE_OVERRIDES.md reference, updated version to 03.07.00 | GitHub Copilot | -| 2026-01-30 | Added CSS Variables reference, updated version to 03.06.03 | GitHub Copilot | -| 2026-01-09 | Initial documentation index created for MokoStandards compliance. | GitHub Copilot | -| 2026-01-27 | Updated with roadmap link and version to 03.05.01. | GitHub Copilot | diff --git a/docs/RELEASE_PROCESS.md b/docs/RELEASE_PROCESS.md deleted file mode 100644 index d0daa66..0000000 --- a/docs/RELEASE_PROCESS.md +++ /dev/null @@ -1,638 +0,0 @@ - - -# Release Process — MokoOnyx - -This document describes the complete release process for MokoOnyx Joomla template, including automated workflows and manual procedures. - -## Table of Contents - -1. [Overview](#overview) -2. [Release Types](#release-types) -3. [Automated Release Process](#automated-release-process) -4. [Manual Release Process](#manual-release-process) -5. [Update Server Configuration](#update-server-configuration) -6. [Testing Releases](#testing-releases) -7. [Rollback Procedures](#rollback-procedures) -8. [Troubleshooting](#troubleshooting) - ---- - -## Overview - -MokoOnyx uses an automated release system powered by GitHub Actions. The system: - -- **Builds** installation packages automatically -- **Generates** checksums for security verification -- **Creates** GitHub Releases with downloadable artifacts -- **Updates** the Joomla update server (`updates.xml`) automatically -- **Validates** package integrity with SHA-256 hashes - -### Key Components - -1. **Release Workflow** (`.github/workflows/release.yml`): Builds and publishes releases -2. **Auto-Update SHA** (`.github/workflows/auto-update-sha.yml`): Updates `updates.xml` after release -3. **Build Script** (`scripts/build-release.sh`): Local development builds -4. **Update Server** (`updates.xml`): Joomla update server manifest - ---- - -## Release Types - -### Patch Release (Third Digit) - -**Format**: `XX.XX.XX` → `XX.XX.XX+1` (e.g., `03.08.03` → `03.08.04`) - -**When to use**: -- Bug fixes -- Security patches -- Documentation updates -- Minor CSS/styling tweaks -- No breaking changes - -**Example**: `03.08.03` → `03.08.04` - -### Minor Release (Second Digit) - -**Format**: `XX.XX.00` → `XX.XX+1.00` (e.g., `03.08.03` → `03.09.00`) - -**When to use**: -- New features -- New module/component overrides -- Significant styling changes -- Backward-compatible changes - -**Example**: `03.08.03` → `03.09.00` - -### Major Release (First Digit) - -**Format**: `XX.00.00` → `XX+1.00.00` (e.g., `03.08.03` → `04.00.00`) - -**When to use**: -- Breaking changes -- Major architecture changes -- Joomla version upgrades -- Complete redesigns - -**Example**: `03.08.03` → `04.00.00` - ---- - -## Automated Release Process - -**Recommended for most releases** - -### Prerequisites - -- [ ] All changes merged to `main` branch -- [ ] Tests passing -- [ ] Documentation updated -- [ ] CHANGELOG.md updated -- [ ] Local testing completed - -### Step 1: Prepare Release Branch - -```bash -# Create release branch -git checkout main -git pull -git checkout -b release/03.08.04 - -# Update version in templateDetails.xml -# Edit: src/templateDetails.xml -# Change: 03.08.03 -# To: 03.08.04 - -# Update CHANGELOG.md -# Add new section: -## [03.08.04] - 2026-02-27 - -### Added -- Feature descriptions - -### Fixed -- Bug fix descriptions - -### Changed -- Change descriptions - -# Commit changes -git add src/templateDetails.xml CHANGELOG.md -git commit -m "chore: Prepare release 03.08.04" -git push origin release/03.08.04 -``` - -### Step 2: Create Pull Request - -1. Go to GitHub repository -2. Click "Pull requests" → "New pull request" -3. Base: `main`, Compare: `release/03.08.04` -4. Title: `Release 03.08.04` -5. Description: Copy relevant CHANGELOG entries -6. Create pull request -7. Review and merge - -### Step 3: Create and Push Tag - -```bash -# Switch to main and pull changes -git checkout main -git pull - -# Create tag -git tag 03.08.04 - -# Push tag (triggers release workflow) -git push origin 03.08.04 -``` - -### Step 4: Monitor Automated Process - -1. **Go to GitHub Actions tab** -2. **Watch "Create Release" workflow**: - - Builds package - - Generates checksums - - Creates GitHub Release - - Uploads artifacts - -3. **Watch "Auto-Update SHA Hash" workflow**: - - Downloads release package - - Calculates SHA-256 hash - - Updates `updates.xml` - - Commits to main branch - -### Step 5: Verify Release - -1. **Check GitHub Release**: - - Go to Releases tab - - Verify release `03.08.04` exists - - Download ZIP package - - Verify checksums match - -2. **Check updates.xml**: - ```bash - git pull - cat updates.xml - ``` - - Verify version is `03.08.04` - - Verify download URL is correct - - Verify SHA-256 hash is present - -3. **Test Joomla Update**: - - Install previous version in Joomla - - Go to Extensions → Update - - Verify update is detected - - Perform update - - Verify template works correctly - ---- - -## Manual Release Process - -**Use when automation fails or for local testing** - -### Step 1: Prepare Repository - -```bash -# Update version numbers -# Edit: src/templateDetails.xml -# Edit: CHANGELOG.md - -# Commit changes -git add src/templateDetails.xml CHANGELOG.md -git commit -m "chore: Prepare release 03.08.04" -git push -``` - -### Step 2: Build Package Locally - -```bash -# Run build script -./scripts/build-release.sh 03.08.04 - -# Output will be in build/ directory: -# - mokoonyx-src-03.08.04.zip -# - mokoonyx-src-03.08.04.zip.sha256 -# - mokoonyx-src-03.08.04.zip.md5 -``` - -### Step 3: Test Package - -```bash -# Install in Joomla test environment -# Extensions → Manage → Install → Upload Package File -# Select: build/mokoonyx-src-03.08.04.zip - -# Test all features: -# - Template displays correctly -# - Module overrides work -# - Alternative layouts selectable -# - Dark mode works -# - No JavaScript errors -``` - -### Step 4: Create GitHub Release - -1. **Go to GitHub Releases** -2. **Click "Create a new release"** -3. **Tag**: `03.08.04` (create new tag) -4. **Release title**: `Release 03.08.04` -5. **Description**: Copy from CHANGELOG.md -6. **Upload files**: - - `mokoonyx-src-03.08.04.zip` - - `mokoonyx-src-03.08.04.zip.sha256` - - `mokoonyx-src-03.08.04.zip.md5` -7. **Publish release** - -### Step 5: Update updates.xml Manually - -```bash -# Extract SHA-256 hash -cat build/mokoonyx-src-03.08.04.zip.sha256 -# Example output: a1b2c3d4e5f6... - -# Edit updates.xml -# Update 03.08.04 -# Update 2026-02-27 -# Update https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx/releases/download/03.08.04/mokoonyx-src-03.08.04.zip -# Update sha256:a1b2c3d4e5f6... - -# Commit and push -git add updates.xml -git commit -m "chore: Update updates.xml for release 03.08.04" -git push -``` - ---- - -## Update Server Configuration - -### updates.xml Structure - -```xml - - - MokoOnyx - Moko Consulting's site template based on Cassiopeia. - mokoonyx - template - site - - 03.08.04 - 2026-02-27 - Jonathan Miller || Moko Consulting - hello@mokoconsulting.tech - (C)GNU General Public License Version 3 - 2026 Moko Consulting - - https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx - - - https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx/releases/download/03.08.04/mokoonyx-src-03.08.04.zip - sha256:a1b2c3d4e5f6... - - - - stable - - - Moko Consulting - https://www.mokoconsulting.tech - - - - -``` - -### Hosting Update Server - -The `updates.xml` file is hosted directly on GitHub: - -**URL**: `https://raw.githubusercontent.com/mokoconsulting-tech/MokoOnyx/main/updates.xml` - -This URL is configured in `src/templateDetails.xml`: - -```xml - - - https://raw.githubusercontent.com/mokoconsulting-tech/MokoOnyx/main/updates.xml - - -``` - ---- - -## Testing Releases - -### Pre-Release Testing - -```bash -# 1. Build package locally -./scripts/build-release.sh - -# 2. Set up Joomla test environment -# - Clean Joomla 5.x installation -# - Previous MokoOnyx version installed - -# 3. Test current version features -# - All module overrides -# - Alternative layouts -# - Dark mode toggle -# - Responsive behavior - -# 4. Install new package -# Extensions → Manage → Install → Upload Package - -# 5. Verify upgrade process -# - No errors during installation -# - Settings preserved -# - Custom modifications retained - -# 6. Test new features -# - New functionality works -# - Bug fixes applied -# - No regressions -``` - -### Update Server Testing - -```bash -# 1. Install previous version in Joomla -# 2. Go to: Extensions → Update -# 3. Click "Find Updates" -# 4. Verify update shows: "MokoOnyx 03.08.04" -# 5. Click "Update" -# 6. Verify successful update -# 7. Test template functionality -``` - -### Checklist - -- [ ] Package installs without errors -- [ ] Template activates correctly -- [ ] All module overrides work -- [ ] Alternative layouts selectable -- [ ] Dark mode functions -- [ ] Responsive on mobile/tablet/desktop -- [ ] No JavaScript console errors -- [ ] No PHP errors in Joomla logs -- [ ] Update server detects new version -- [ ] Update process completes successfully - ---- - -## Rollback Procedures - -### Rollback Release - -If a release has critical issues: - -1. **Delete GitHub Release**: - - Go to Releases - - Click release to delete - - Click "Delete" - - Confirm deletion - -2. **Delete Git Tag**: - ```bash - # Delete local tag - git tag -d 03.08.04 - - # Delete remote tag - git push --delete origin 03.08.04 - ``` - -3. **Revert updates.xml**: - ```bash - # Revert to previous version - git revert - git push - ``` - -4. **Notify Users**: - - Create GitHub issue explaining the problem - - Pin the issue - - Provide rollback instructions for users - -### User Rollback Instructions - -For users who installed the problematic version: - -1. **Download previous version** from GitHub Releases -2. **Uninstall current version**: - - Extensions → Manage → Manage - - Find MokoOnyx - - Click "Uninstall" -3. **Install previous version**: - - Extensions → Manage → Install - - Upload previous version ZIP -4. **Verify functionality** - ---- - -## Troubleshooting - -### Release Workflow Fails - -**Problem**: Build fails with "rsync: command not found" - -**Solution**: The GitHub Actions runner always has rsync installed. If this occurs, check the workflow file syntax. - -**Problem**: ZIP creation fails - -**Solution**: Check that `src/` and `src/media/` directories exist and contain files. - -**Problem**: Version update fails - -**Solution**: Verify `sed` commands in workflow match actual XML structure. - -### Auto-Update SHA Fails - -**Problem**: Cannot download release package - -**Solution**: -- Verify release was published (not draft) -- Check package naming: `mokoonyx-src-{version}.zip` -- Verify release tag format - -**Problem**: SHA-256 hash mismatch - -**Solution**: -- Package may have been modified after calculation -- Re-run the workflow manually -- Verify package integrity - -**Problem**: Commit fails - -**Solution**: -- Check workflow has write permissions -- Verify no branch protection rules blocking bot commits - -### Manual Build Issues - -**Problem**: `./scripts/build-release.sh: Permission denied` - -**Solution**: -```bash -chmod +x scripts/build-release.sh -./scripts/build-release.sh -``` - -**Problem**: Build directory exists - -**Solution**: -```bash -rm -rf build/ -./scripts/build-release.sh -``` - -### Update Server Issues - -**Problem**: Joomla doesn't detect update - -**Solution**: -1. Check `updates.xml` is accessible: - ```bash - curl https://raw.githubusercontent.com/mokoconsulting-tech/MokoOnyx/main/updates.xml - ``` -2. Verify version number is higher than installed version -3. Clear Joomla cache: System → Clear Cache -4. Check update URL in templateDetails.xml - -**Problem**: Update fails with "Invalid package" - -**Solution**: -- Verify SHA-256 hash matches -- Re-download package and check integrity -- Verify package structure is correct - ---- - -## Best Practices - -### Version Numbering - -- **Always increment** version numbers sequentially -- **Never reuse** version numbers -- **Use consistent** format: `XX.XX.XX` - -### Changelog - -- **Update before** release -- **Include all changes** since last version -- **Categorize** changes: Added, Changed, Fixed, Removed -- **Write clear descriptions** for users - -### Testing - -- **Test locally** before pushing tag -- **Test update process** from previous version -- **Test on clean** Joomla installation -- **Test different** configurations - -### Communication - -- **Announce releases** on GitHub Discussions -- **Document breaking changes** clearly -- **Provide migration guides** for major changes -- **Respond promptly** to issue reports - ---- - -## Quick Reference - -### Automated Release Commands - -```bash -# 1. Create release branch -git checkout -b release/03.08.04 - -# 2. Update version and CHANGELOG -# (edit files) - -# 3. Commit and push -git add . -git commit -m "chore: Prepare release 03.08.04" -git push origin release/03.08.04 - -# 4. Create and merge PR (via GitHub UI) - -# 5. Create and push tag -git checkout main -git pull -git tag 03.08.04 -git push origin 03.08.04 - -# 6. Wait for automation to complete -``` - -### Manual Release Commands - -```bash -# Build locally -./scripts/build-release.sh 03.08.04 - -# Test installation -# (manual Joomla testing) - -# Create release on GitHub -# (via GitHub UI) - -# Update updates.xml -# (edit file with SHA-256) -git add updates.xml -git commit -m "chore: Update updates.xml for 03.08.04" -git push -``` - ---- - -## Related Documentation - -- **Build Scripts**: [scripts/README.md](../scripts/README.md) -- **Workflow Guide**: [WORKFLOW_GUIDE.md](WORKFLOW_GUIDE.md) -- **Contributing**: [CONTRIBUTING.md](../CONTRIBUTING.md) -- **Changelog**: [CHANGELOG.md](../CHANGELOG.md) - ---- - -## Support - -- **Issues**: [GitHub Issues](https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx/issues) -- **Discussions**: [GitHub Discussions](https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx/discussions) -- **Email**: hello@mokoconsulting.tech - ---- - -## License - -Copyright (C) 2026 Moko Consulting - -This documentation is licensed under GPL-3.0-or-later. diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md deleted file mode 100644 index 9faa2f5..0000000 --- a/docs/ROADMAP.md +++ /dev/null @@ -1,946 +0,0 @@ - - -# MokoOnyx Roadmap (VERSION: 03.09.03) - -This document provides a comprehensive, version-specific roadmap for the MokoOnyx Joomla template, tracking feature evolution, current capabilities, and planned enhancements. - -## Table of Contents - -- [Version Timeline](#version-timeline) - - [Past Releases](#past-releases) - - [Future Roadmap (5-Year Plan)](#future-roadmap-5-year-plan) -- [Current Release (v03.06.03)](#current-release-v030603) -- [Implemented Features](#implemented-features) -- [Planned Features](#planned-features) -- [Development Priorities](#development-priorities) -- [Long-term Vision](#long-term-vision) -- [External Resources](#external-resources) - ---- - -## Version Timeline - -### Past Releases - -### v03.05.01 (2026-01-09) - Standards & Security -**Status**: Released (CHANGELOG entry exists, code files pending version update) - -**Added**: -- Dependency review workflow for vulnerability scanning -- Standards compliance workflow for MokoStandards validation -- Dependabot configuration for automated security updates -- Documentation index (`docs/README.md`) - -**Changed**: -- Removed custom CodeQL workflow (using GitHub's default setup) -- Enforced repository compliance with MokoStandards -- Improved security posture with automated scanning - -### v03.06.00 (2026-01-28) - Version Update -**Status**: Current Release (in code) - -**Changed**: -- Updated version to 03.06.00 across all files - -### v03.05.00 (2026-01-04) - Workflow & Governance -**Status**: Mentioned in CHANGELOG (v03.05.00) - -**Added**: -- `.github/workflows` directory structure -- CODE_OF_CONDUCT.md from MokoStandards -- CONTRIBUTING.md from MokoStandards - -**Changed**: -- TODO items to be split to separate file (tracked) - -### v03.01.00 (2025-12-16) - CI/CD Foundation -**Added**: -- Initial GitHub Actions workflows - -### v03.00.00 (2025-12-09) - Font Awesome 7 Upgrade -**Updated**: -- Copyright headers to MokoCodingDefaults standards -- Fixed color style injection in `index.php` -- Upgraded Font Awesome 6 to Font Awesome 7 Free -- Added Font Awesome 7 Free style fallback - -**Removed**: -- Deprecated CODE_OF_CONDUCT.md -- Deprecated CONTRIBUTING.md - -### v02.01.05 (2025-09-04) - CSS Refinement -**Fixed**: -- Removed vmbasic.css -- Repaired template.css and colors_standard.css - -### v02.00.00 (2025-08-30) - Dark Mode & TOC -**Major Features**: -- **Dark Mode Toggle System** - - Frontend toggle switch with localStorage persistence - - Admin-configurable default mode - - CSS rules for light/dark themes - - JavaScript-powered mode switching - -- **Enhanced Template Parameters** - - Logo parameter support - - GTM container ID configuration - - Dark mode defaults in settings - - Updated metadata and copyright headers - -- **Expanded Table of Contents** - - Automatic TOC injection - - User-selectable placement (`toc-left` or `toc-right`) - - Article options integration - -**Improvements**: -- Cleaned up `index.php` (removed duplicate skip-to-content calls) -- Consolidated JavaScript asset loading -- Streamlined CSS for toggle switch -- Accessibility refinements (typography, color contrast) -- Fixed missing logo parameter in header -- Corrected stylesheet inconsistencies -- Patched redundant script includes - -### v01.00.00 - Initial Public Release -**Core Features**: -- Font Awesome 6 integration -- Bootstrap 5 helpers and utilities -- Automatic Table of Contents (TOC) utility -- Moko Expansions: Google Tag Manager / GA4 hooks -- Built on Joomla's Cassiopeia template - ---- - -### Future Roadmap (5-Year Plan) - -The following versions represent our planned annual major releases, each building upon the previous version's foundation. - -#### v02.00.00 (Q3 2026) - Clean Slate -**Status**: Planned -**Target Release**: Q3 2026 - -**Breaking Changes**: -- **Remove MokoCassiopeia migration script** — the `helper/migrate.php` bootstrap in `index.php` and the `.migrated` marker file will be removed. All MokoCassiopeia users must migrate before upgrading to v02. -- **Remove MokoCassiopeia references** — all `str_replace(mokocassiopeia, mokoonyx)` logic, old name constants, and legacy compatibility code will be cleaned out. -- **Remove `script.php` bridge logic** — the `postflight()` migration code for MokoCassiopeia will be removed. - -**New Features**: -- Clean codebase with no migration overhead -- Performance improvements from removing first-load migration check -- Fresh start for MokoOnyx-native development - -**Migration Notice**: -Users still running MokoCassiopeia must install MokoOnyx v01.x first to migrate their settings before upgrading to v02. The v01.x line will remain available for download. - ---- - -#### v04.00.00 (Q4 2027) - Enhanced Accessibility & Performance -**Status**: Planned -**Target Release**: December 2027 - -**Major Template Features**: -- **WCAG 2.1 AA Compliance** - - Full accessibility audit and remediation - - High-contrast theme options - - Screen reader optimizations - - Keyboard navigation enhancements - - ARIA landmark improvements - - Skip navigation enhancements - -- **Template Performance Optimizations** - - Critical CSS inlining for faster first paint - - Lazy loading for images and below-fold content - - WebP image support with automatic fallbacks - - Advanced asset bundling and minification - - Template asset caching (CSS/JS bundles) - -- **Enhanced Layout System** - - Additional responsive grid layouts - - Flexible module position system - - Column layout presets (2-col, 3-col, 4-col variations) - - Grid/masonry article layouts - - Sticky sidebar options - -- **Typography Enhancements** - - Advanced typography controls in template settings - - Additional font pairing presets - - Custom font upload support - - Line height and letter spacing controls - - Responsive typography scaling - -- **Developer Experience** - - Development mode enablement (unminified assets, debug output) - - Live reload during development - - Enhanced error logging and diagnostics - - Template debugging tools - - Style guide generator - -- **Content Display Features** - - Soft offline mode (category-based access during maintenance) - - Enhanced article layouts (grid, masonry, timeline) - - Image caption styling options - - Quote block styling variations - - Enhanced breadcrumb customization - -**Template Infrastructure**: -- Expanded template parameter validation -- Enhanced template override detection -- Automated template compatibility testing -- Template performance profiling tools - ---- - -#### v05.00.00 (Q4 2028) - Advanced Layouts & Template Customization -**Status**: Planned -**Target Release**: December 2028 - -**Major Template Features**: -- **Enhanced Layout Builder** - - Template-based page layout variations - - Configurable layout options via template parameters - - Layout presets library (blog, portfolio, business, magazine) - - Module position layout manager - - Visual layout preview in admin - -- **Advanced Styling System** - - Extended color palette management (unlimited custom palettes) - - CSS variable editor in template settings - - Style presets for different site types - - Border radius and spacing controls - - Box shadow and effect controls - -- **Template Component Enhancements** - - Enhanced menu styling options (mega menu support) - - Advanced header variations (transparent, sticky, minimal) - - Footer layout options (column variations, widgets) - - Sidebar styling and behavior options - - Hero section templates and variations - -- **Content Display Options** - - Article intro/full text display controls - - Category layout variations (grid, list, masonry, cards) - - Featured content sections - - Related articles display options - - Author bio box styling - -- **Responsive Design Improvements** - - Mobile-first navigation patterns - - Tablet-specific layout controls - - Responsive image sizing options - - Mobile header variations - - Touch-friendly interface elements - -- **Template Integration Features** - - Enhanced VirtueMart template overrides - - Contact form styling variations - - Search result layout options - - Error page customization - - Archive page templates - -**Template Infrastructure**: -- Joomla 6.x template compatibility (if released) -- PHP 8.2+ support -- Template child theme support -- Template preset import/export functionality - ---- - -#### v06.00.00 (Q4 2029) - Template Extensions & Advanced Features -**Status**: Planned -**Target Release**: December 2029 - -**Major Template Features**: -- **Template Marketplace & Extensions** - - Template addon system for modular features - - Community-contributed template extensions - - Template preset marketplace - - Style pack distribution system - - Template component library - -- **Advanced Module System** - - Custom module chrome options - - Module animation effects - - Module visibility controls (scroll, time-based) - - Module group management - - Module style inheritance - -- **Enhanced Media Handling** - - Background image options per page/section - - Image overlay controls - - Parallax scrolling effects - - Video background support - - Gallery template variations - -- **Template Branding Options** - - Multiple logo upload (standard, retina, mobile) - - Favicon and app icon management - - Custom loading screen/animations - - Watermark options - - Brand color scheme generator - -- **Advanced Header/Footer** - - Multiple header layout presets - - Sticky header variations and behaviors - - Header transparency controls - - Footer widget areas expansion - - Floating action buttons - -- **Content Enhancement Features** - - Reading progress indicator - - Social sharing buttons (template-integrated) - - Print-friendly styles - - Reading time estimation display - - Content table enhancements - -- **Template SEO Features** - - Schema markup templates for common types - - Open Graph tag management - - Twitter Card support - - Breadcrumb schema integration - - Meta tag template controls - -**Template Infrastructure**: -- Template versioning system -- Template backup/restore functionality -- Template A/B testing support -- Multi-language template variations -- Template documentation generator - ---- - -#### v07.00.00 (Q4 2030) - Modern Template Standards & Enhancements -**Status**: Planned -**Target Release**: December 2030 - -**Major Template Features**: -- **Modern CSS Features** - - CSS Grid layout system integration - - CSS Container Queries support - - CSS Cascade Layers implementation (layered style priority system) - - Custom properties (CSS variables) UI - - Modern filter and backdrop effects - -- **Progressive Template Features** - - Offline-capable template assets - - Service worker template integration - - App manifest generation - - Install to home screen support - - Template asset preloading strategies - -- **Animation & Interaction** - - Scroll-triggered animations - - Hover effect library - - Page transition effects - - Micro-interactions for UI elements - - Loading animation options - -- **Advanced Responsive Features** - - Container-based responsive design - - Element visibility by viewport - - Responsive navigation patterns library - - Mobile-optimized interactions - - Adaptive image loading - -- **Template Accessibility Features** - - Focus indicators customization - - Reduced motion preferences support - - High contrast mode automation - - Keyboard navigation patterns - - ARIA live regions for dynamic content - -- **Content Presentation** - - Advanced blockquote styles - - Code snippet highlighting themes - - Table styling variations - - List styling options - - Custom content block templates - -- **Template Performance** - - Resource hints (preconnect, prefetch) - - Optimal asset delivery strategies - - Image format optimization (AVIF support) - - Font loading optimization - - Template metrics dashboard - -**Template Infrastructure**: -- Template pattern library -- Design token system -- Template component documentation -- Automated template testing suite -- Template performance monitoring - ---- - -#### v08.00.00 (Q4 2031) - Next-Generation Template Features -**Status**: Conceptual -**Target Release**: December 2031 - -**Major Template Features**: -- **Advanced Layout Systems** - - Subgrid support for complex layouts - - Multi-column layout variations - - Asymmetric grid systems - - Dynamic layout switching - - Layout constraint system - -- **Enhanced Visual Customization** - - Real-time style editor - - Template style variations manager - - Custom CSS injection with validation - - Style inheritance and override system - - Visual design tokens editor - -- **Template Component Library** - - Comprehensive UI component set - - Reusable template blocks - - Component variation system - - Template snippet library - - Pattern library integration - -- **Advanced Typography System** - - Variable font support - - Advanced typographic scales - - Font pairing recommendations - - Fluid typography system - - Custom font fallback chains - -- **Template Integration Features** - - Enhanced component overrides - - Template hooks system - - Event-based template modifications - - Custom field rendering templates - - Module position API enhancements - -- **Responsive & Adaptive Design** - - Advanced breakpoint management - - Element-specific responsive controls - - Adaptive images with art direction - - Responsive typography system - - Context-aware component rendering - -- **Template Ecosystem** - - Child template framework - - Template derivative system - - Community template marketplace - - Template rating and review system - - Professional template support network - -- **Template Quality & Maintenance** - - Automated accessibility testing - - Template performance auditing - - Code quality monitoring - - Update notification system - - Template health dashboard - -**Template Infrastructure**: -- Template API for extensibility -- Template package manager -- Template development CLI tools -- Template migration utilities -- Comprehensive template documentation system - ---- - -## Current Release (v03.06.03) - -### System Requirements -- **Joomla**: 4.4.x or 5.x -- **PHP**: 8.0+ -- **Database**: MySQL/MariaDB compatible - -### Architecture -- **Base Template**: Joomla Cassiopeia -- **Enhancement Layer**: Non-invasive overrides -- **Asset Management**: Joomla Web Asset Manager (WAM) -- **Frontend Framework**: Bootstrap 5 -- **Icon Library**: Font Awesome 7 Free - ---- - -## Implemented Features - -### 🎨 Theming & Visual Design - -#### Color Palette System -- **3 Built-in Palettes**: Standard, Alternative, Custom -- **Dual Mode Support**: Separate light and dark configurations -- **Custom Palettes**: User-definable via `colors_custom.css` -- **Location**: `src/media/css/colors/{light|dark}/` - -#### Dark Mode System -- **Toggle Controls**: Switch (Light↔Dark) or Radios (Light/Dark/System) -- **Default Mode**: Admin-configurable (system, light, or dark) -- **Persistence**: localStorage for user preferences -- **Auto-Detection**: Optional system preference detection -- **Meta Tags**: `color-scheme` and `theme-color` support -- **ARIA Bridge**: Bootstrap ARIA compatibility - -#### Typography -- **Font Schemes**: - - Local: Roboto - - Web (Google Fonts): Fira Sans, Roboto + Noto Sans -- **Admin-Configurable**: Template settings dropdown - -#### Branding -- **Logo Support**: Custom logo upload -- **Site Title**: Text-based branding option -- **Site Description**: Tagline/subtitle field -- **Font Awesome Kit**: Optional custom kit integration - -### 📐 Layout & Structure - -#### Module Positions (23 Total) -**Header Area**: -- topbar, below-topbar, below-logo, menu, search, banner - -**Content Area**: -- top-a, top-b, main-top, main-bottom, breadcrumbs -- sidebar-left, sidebar-right - -**Footer Area**: -- bottom-a, bottom-b, footer-menu, footer - -**Special**: -- debug, offline-header, offline, offline-footer -- drawer-left, drawer-right - -#### Layout Options -- **Container Type**: Fluid or Static -- **Sticky Header**: Optional fixed navigation -- **Back-to-Top Button**: Scrollable page support - -### 📝 Content Features - -#### Table of Contents (TOC) -- **Automatic Generation**: From article headings -- **Placement Options**: `toc-left` or `toc-right` layouts -- **Article Integration**: Via Options → Layout dropdown -- **Responsive**: Mobile-friendly sidebar placement - -#### Article Layouts -- **Default**: Standard Cassiopeia layout -- **TOC Variants**: Left-sidebar or right-sidebar TOC -- **Custom Overrides**: Located in `html/com_content/article/` - -### 📊 Analytics & Tracking - -#### Google Tag Manager (GTM) -- **Enable/Disable**: Admin toggle -- **Container ID**: Template parameter field -- **Implementation**: Head and body script injection -- **GDPR-Ready**: Configurable consent defaults - -#### Google Analytics 4 (GA4) -- **Enable/Disable**: Admin toggle -- **Property ID**: Template parameter field -- **Universal Analytics Fallback**: Legacy UA support -- **Privacy-First**: Conditional loading based on settings - -#### Smart Visitor Detection -- **Enable/Disable**: Admin toggle (default: enabled) -- **Visitor Type**: Pushes `logged_in` or `guest` to dataLayer -- **Visitor Group**: Pushes highest-privilege Joomla user group name (e.g., "Registered", "Author") -- **Page Type**: Pushes component + view (e.g., `com_content.article`) -- **GA4 User Properties**: Sets `visitor_type` and `visitor_group` as persistent user-scoped dimensions -- **Privacy-Safe**: No PII (usernames, emails, or user IDs) is ever sent -- **Dual Integration**: Works with both GTM (`moko.visitor_detect` event) and standalone GA4 (`user_properties`) - -### 🎛️ Customization & Developer Tools - -#### Custom Code Injection -- **Head Start**: Custom HTML/JS before `` -- **Head End**: Custom HTML/JS at end of `` -- **Raw HTML**: Unfiltered code injection for advanced users - -#### Drawer System -- **Left/Right Drawers**: Offcanvas menu areas -- **Icon Customization**: Font Awesome icon selection -- **Default Icons**: - - Left: `fa-solid fa-chevron-right` - - Right: `fa-solid fa-chevron-left` - -#### Asset Management -- **Joomla WAM**: Complete asset registry in `joomla.asset.json` -- **Development/Production Modes**: Minified and unminified assets -- **Dependency Management**: Automatic script/style loading - -### 🏗️ Template Overrides - -#### Component Overrides -**Content (com_content)**: -- Article layouts (default, toc-left, toc-right) -- Category layouts (blog, list) -- Featured articles - -**Contact (com_contact)**: -- Contact form layouts - -**Engage (com_engage)**: -- Comment system integration - -#### Module Overrides -**Menu (mod_menu)**: -- Metis dropdown menu -- Offcanvas navigation - -**VirtueMart**: -- Product display (`mod_virtuemart_product`) -- Shopping cart (`mod_virtuemart_cart`) -- Manufacturer display (`mod_virtuemart_manufacturer`) -- Category display (`mod_virtuemart_category`) -- Currency selector (`mod_virtuemart_currencies`) - -**Other Modules**: -- Custom HTML (`mod_custom`) -- GABble social integration (`mod_gabble`) - -**Membership System (OS Membership)**: -- Plan layouts (default, pricing tables) -- Member management interfaces - -### 🔧 Configuration Parameters - -#### Theme Tab -**General**: -- `theme_enabled` - Enable/disable theme system -- `theme_control_type` - Toggle UI type (switch/radios/none) -- `theme_default_choice` - Default mode (system/light/dark) -- `theme_auto_dark` - Auto-detect system preference -- `theme_meta_color_scheme` - Inject `color-scheme` meta tag -- `theme_meta_theme_color` - Inject `theme-color` meta tag -- `theme_bridge_bs_aria` - Bootstrap ARIA compatibility - -**Variables & Palettes**: -- `colorLightName` - Light mode color scheme -- `colorDarkName` - Dark mode color scheme - -**Typography**: -- `useFontScheme` - Font selection (local/web) - -**Branding & Icons**: -- `brand` - Show/hide branding -- `logoFile` - Logo upload path -- `siteTitle` - Site title text -- `siteDescription` - Site tagline -- `fA6KitCode` - Font Awesome kit code - -**Header & Navigation**: -- `stickyHeader` - Fixed navigation -- `backTop` - Back-to-top button - -**Toggle UI**: -- `theme_fab_enabled` - Floating action button for theme toggle -- `theme_fab_pos` - FAB position (br/bl/tr/tl) - -#### Google Tab -- `googletagmanager` - Enable GTM -- `googletagmanagerid` - GTM container ID -- `googleanalytics` - Enable GA4 -- `googleanalyticsid` - GA4 property ID -- `googlevisitordetection` - Smart Visitor Detection (default: enabled) - -#### Custom Code Tab -- `custom_head_start` - Custom code at head start -- `custom_head_end` - Custom code at head end - -#### Drawers Tab -- `drawerLeftIcon` - Left drawer icon (Font Awesome class) -- `drawerRightIcon` - Right drawer icon (Font Awesome class) - -#### Advanced Tab -- `fluidContainer` - Container layout (static/fluid) - -### 🛠️ Development Tools - -#### Quality Assurance -- **Codeception**: Automated testing framework -- **PHPStan**: Static analysis (level 8+) -- **PHPCS**: Code style validation (PSR-12) -- **PHPCompatibility**: PHP 8.0+ compatibility checks - -#### CI/CD Workflows -- **Dependency Review**: Vulnerability scanning -- **Standards Compliance**: MokoStandards validation -- **CodeQL**: Security analysis (GitHub default) -- **Dependabot**: Automated dependency updates - -#### Documentation -- **Quick Start**: 5-minute developer setup -- **Workflow Guide**: Git strategy, branching, releases -- **Joomla Development**: Testing, packaging, multi-version support - ---- - -## Planned Features - -### 🚧 In Development - -#### Soft Offline Mode (v03.07.00 - Planned) -**Status**: Planned for v03.07.00 -**Priority**: High -**Description**: Keep selected categories accessible during site maintenance mode with persistent links to essential pages - -**Use Cases**: -- Legal documents remain viewable during downtime -- Policy pages accessible for compliance requirements -- Terms of service always available to users -- Privacy policy accessible at all times -- Essential public information during maintenance - -**Technical Specifications**: -- **Configuration Method**: Template parameters in `templateDetails.xml` -- **Category Access**: Category IDs stored as comma-separated values -- **Persistent Links**: Direct article/menu item links always visible -- **Access Control**: Check in `offline.php` template file -- **Content Rendering**: Use Joomla's content component to fetch articles -- **Security**: Maintain proper access levels and permissions - -**Implementation Plan**: -1. Add category selection field to template parameters -2. Add persistent link configuration (Terms of Service, Privacy Policy, etc.) -3. Modify `offline.php` to check for allowed categories -4. Add persistent link display in offline mode header/footer -5. Implement category content fetching during offline mode -6. Add styling for offline mode category display and persistent links -7. Test with various category and link configurations -8. Document admin configuration steps - -**Configuration Interface**: -- **Category Field Type**: Category multiselect in template settings - - **Label**: "Categories Accessible During Offline Mode" - - **Default**: None (all content hidden by default) -- **Persistent Links**: Text fields for essential always-available links - - **Terms of Service URL**: Direct link to TOS article/page - - **Privacy Policy URL**: Direct link to privacy policy - - **Contact URL**: Optional contact page link - - **Custom Link 1-3**: Additional persistent links if needed -- **Admin Path**: System → Site Templates → MokoOnyx → Advanced → Offline Mode Settings - -**Persistent Links Feature**: -- **Display Location**: Footer of offline page -- **Styling**: Clearly visible, accessible links -- **Format**: "Terms of Service | Privacy Policy | Contact" -- **Behavior**: Links bypass offline mode restrictions -- **Validation**: Check if URLs are valid Joomla routes - -**Benefits**: -- ✅ Compliance: Keep legal pages accessible -- ✅ Transparency: Users can access essential information -- ✅ Flexibility: Admin control over which categories remain visible -- ✅ Security: Respects Joomla access levels -- ✅ Legal Protection: Terms of Service always accessible -- ✅ User Trust: Privacy policy always available - -**Milestone**: Target release v03.07.00 (Q2 2026) - -#### TODO Tracking System -**Status**: Mentioned in CHANGELOG (v03.05.00) -**Description**: Separate TODO tracking file -**Purpose**: Centralized issue and feature tracking outside changelog - -### 🔮 Future Enhancements - -#### Development Mode (Commented Out) -**Status**: Code exists but disabled -**Location**: `templateDetails.xml` line 91 -**Description**: Comprehensive development mode toggle -**Potential Features**: -- Unminified asset loading -- Debug output -- Performance profiling -- Template cache bypass - -#### Potential Features (Community Requested) -*Note: These are conceptual and not yet officially planned* - -**Enhanced Accessibility**: -- WCAG 2.1 AAA compliance mode -- High-contrast themes -- Screen reader optimizations -- Keyboard navigation improvements - -**Template Layout Features**: -- Advanced responsive grid layouts -- Multiple column variations -- Custom module position system -- Layout preset library - -**Template Styling Features**: -- Extended color palette management -- Custom font upload support -- Typography scale controls -- Visual style editor - ---- - -## Development Priorities - -### Immediate Focus (v03.x - 2026) -1. **Bootstrap TOC Integration**: Complete and document v1.0.1 implementation ✅ -2. **Soft Offline Mode**: Implement category-based offline access (Target: v03.07.00) -3. **TODO Tracking System**: Implement separate file for issue tracking -4. **Security Updates**: Maintain Dependabot and CodeQL scans -5. **Documentation**: Keep docs synchronized with features -6. **Bug Fixes**: Address reported issues and edge cases - -### v04.00.00 Priorities (2027) - Template Foundation -1. **WCAG 2.1 AA Compliance**: Full template accessibility audit and implementation -2. **Template Performance**: Critical CSS, lazy loading, WebP support -3. **Layout System**: Enhanced responsive grid and module positions -4. **Development Mode**: Enable comprehensive template developer tools - -### v05.00.00 Priorities (2028) - Template Customization -1. **Layout Builder**: Template-based page layout system -2. **Styling System**: Extended color palettes and CSS variable management -3. **Template Components**: Enhanced header, footer, and menu variations -4. **Responsive Design**: Mobile-first navigation and layout improvements - -### v06.00.00 Priorities (2029) - Template Extensions -1. **Template Marketplace**: Addon system and community extensions -2. **Module System**: Advanced module chrome and animation options -3. **Media Handling**: Background images, parallax, video backgrounds -4. **Template SEO**: Schema markup templates and meta tag controls - -### v07.00.00+ Priorities (2030+) - Modern Standards -1. **Modern CSS**: Grid, Container Queries, Cascade Layers -2. **Progressive Template**: Offline-capable assets and PWA features -3. **Animation System**: Scroll-triggered effects and micro-interactions -4. **Template Performance**: Advanced optimization and monitoring - ---- - -## Long-term Vision - -### Mission Statement -MokoOnyx aims to be the **most developer-friendly, user-customizable, and standards-compliant Joomla template** while maintaining minimal core overrides for maximum upgrade compatibility. - -### Core Principles -1. **Non-Invasive**: Minimal Cassiopeia overrides -2. **Standards-First**: MokoStandards compliance -3. **Accessibility**: WCAG 2.1 compliance -4. **Performance**: Fast, optimized delivery -5. **Developer Experience**: Clear docs, easy setup, powerful tools -6. **Template-Focused**: Pure template features without complex external dependencies - -### 5-Year Strategic Roadmap (Template Features) - -#### 2027 (v04.00.00) - Accessibility & Performance -- Achieve WCAG 2.1 AA compliance for all template elements -- Implement critical template performance optimizations -- Enhance template layout system with flexible grids -- Enable comprehensive development mode for template developers - -#### 2028 (v05.00.00) - Layouts & Customization -- Launch template-based layout builder system -- Deploy extended styling and customization options -- Enhance template component variations (headers, footers, menus) -- Improve responsive design patterns for all devices - -#### 2029 (v06.00.00) - Extensions & Enhancements -- Introduce template addon and extension system -- Launch template preset marketplace -- Deploy advanced module styling and animation features -- Implement comprehensive template SEO controls - -#### 2030 (v07.00.00) - Modern Standards -- Adopt modern CSS standards (Grid, Container Queries, Cascade Layers) -- Implement progressive template features (PWA support) -- Deploy advanced animation and interaction system -- Enhance template performance monitoring and optimization - -#### 2031 (v08.00.00) - Next-Generation Template -- Advanced layout systems with subgrid support -- Comprehensive template component library -- Enhanced visual customization tools -- Template ecosystem with child themes and derivatives - ---- - -## External Resources - -### Official Links -- **Full Roadmap**: [https://mokoconsulting.tech/support/joomla-cms/mokoonyx-roadmap](https://mokoconsulting.tech/support/joomla-cms/mokoonyx-roadmap) -- **Repository**: [https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx](https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx) -- **Issue Tracker**: [GitHub Issues](https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx/issues) -- **Changelog**: [CHANGELOG.md](../CHANGELOG.md) - -### Community -- **Email Support**: hello@mokoconsulting.tech -- **Contributing**: [CONTRIBUTING.md](../CONTRIBUTING.md) -- **Code of Conduct**: [CODE_OF_CONDUCT.md](../CODE_OF_CONDUCT.md) - -### Documentation -- **Quick Start**: [docs/QUICK_START.md](./QUICK_START.md) -- **Workflow Guide**: [docs/WORKFLOW_GUIDE.md](./WORKFLOW_GUIDE.md) -- **Joomla Development**: [docs/JOOMLA_DEVELOPMENT.md](./JOOMLA_DEVELOPMENT.md) -- **Main README**: [README.md](../README.md) - ---- - -## Contributing to the Roadmap - -Have ideas for future features? We welcome community input! - -**How to Suggest Features**: -1. Check the [GitHub Issues](https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx/issues) for existing requests -2. Open a new issue with the `enhancement` label -3. Provide clear use cases and benefits -4. Engage in community discussion - -**Feature Evaluation Criteria**: -- Alignment with core principles -- User demand and use cases -- Technical feasibility -- Maintenance burden -- Performance impact -- Security implications - ---- - -## Metadata - -* Document: docs/ROADMAP.md -* Repository: [https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx](https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx) -* Path: /docs/ROADMAP.md -* Owner: Moko Consulting -* Version: 03.06.03 -* Status: Active -* Effective Date: 2026-01-30 -* Classification: Public Open Source Documentation - -## Revision History - -| Date | Change Summary | Author | -| ---------- | ----------------------------------------------------- | --------------- | -| 2026-01-27 | Initial version-specific roadmap generated from codebase scan. | GitHub Copilot | -| 2026-01-27 | Added 5-year future roadmap with annual major version releases (v04-v08). | GitHub Copilot | -| 2026-01-27 | Refocused roadmap to concentrate on template-oriented features only. | GitHub Copilot | diff --git a/docs/WORKFLOW_GUIDE.md b/docs/WORKFLOW_GUIDE.md deleted file mode 100644 index 38c787c..0000000 --- a/docs/WORKFLOW_GUIDE.md +++ /dev/null @@ -1,459 +0,0 @@ -# Workflow Guide - Moko Cassiopeia - -Quick reference guide for GitHub Actions workflows and common development tasks. - -## Table of Contents - -- [Overview](#overview) -- [Workflow Quick Reference](#workflow-quick-reference) -- [Common Development Tasks](#common-development-tasks) -- [Troubleshooting](#troubleshooting) -- [Best Practices](#best-practices) - -## Overview - -This repository uses GitHub Actions for continuous integration, testing, quality checks, and deployment. All workflows are located in `.github/workflows/`. - -### Workflow Execution Model - -``` -┌─────────────────┐ -│ Code Changes │ -└────────┬────────┘ - │ - ▼ -┌─────────────────┐ -│ CI Pipeline │ ← Validation, Testing, Quality -└────────┬────────┘ - │ - ▼ -┌─────────────────┐ -│ Version Branch │ ← Create dev/X.Y.Z branch -└────────┬────────┘ - │ - ▼ -┌─────────────────┐ -│ Release Pipeline│ ← dev → rc → version → main -└────────┬────────┘ - │ - ▼ -┌─────────────────┐ -│ Distribution │ ← ZIP package + GitHub Release -└─────────────────┘ -``` - -## Workflow Quick Reference - -### Continuous Integration (ci.yml) - -**Trigger:** Automatic on push/PR to main, dev/*, rc/*, version/* branches - -**Purpose:** Validates code quality and repository structure - -**What it does:** -- ✅ Validates Joomla manifest XML -- ✅ Checks XML well-formedness -- ✅ Validates GitHub Actions workflows -- ✅ Runs PHP syntax checks -- ✅ Checks for secrets in code -- ✅ Validates license headers -- ✅ Verifies version alignment - -**When to check:** After every commit - -**How to view results:** -```bash -# Via GitHub CLI -gh run list --workflow=ci.yml --limit 5 -gh run view --log -``` - -### PHP Quality Checks (php_quality.yml) - -**Trigger:** Automatic on push/PR to main, dev/*, rc/*, version/* branches - -**Purpose:** Ensures PHP code quality and compatibility - -**What it does:** -- 🔍 PHPStan static analysis (level 5) -- 📏 PHP_CodeSniffer with PSR-12 standards -- ✔️ PHP 8.0+ compatibility checks - -**Matrix:** PHP 8.0, 8.1, 8.2, 8.3 - -**When to check:** Before committing PHP changes - -**How to run locally:** -```bash -# Install tools -composer global require "squizlabs/php_codesniffer:^3.0" --with-all-dependencies -composer global require "phpstan/phpstan:^1.0" --with-all-dependencies - -# Run checks -phpcs --standard=phpcs.xml src/ -phpstan analyse --configuration=phpstan.neon -``` - -### Joomla Testing (joomla_testing.yml) - -**Trigger:** Automatic on push/PR to main, dev/*, rc/* branches - -**Purpose:** Tests template compatibility with Joomla versions - -**What it does:** -- 📦 Downloads and installs Joomla (4.4, 5.0, 5.1) -- 🔧 Installs template into Joomla -- ✅ Validates template installation -- 🧪 Runs Codeception tests - -**Matrix:** Joomla 4.4/5.0/5.1 × PHP 8.0/8.1/8.2/8.3 - -**When to check:** Before releasing new versions - -**How to test locally:** -```bash -# See docs/JOOMLA_DEVELOPMENT.md for local testing setup -codecept run -``` - -### Version Branch Creation (version_branch.yml) - -**Trigger:** Manual workflow dispatch - -**Purpose:** Creates a new version branch and bumps version numbers - -**What it does:** -- 🏷️ Creates dev/*, rc/*, or version/* branch -- 📝 Updates version in all files -- 📅 Updates manifest dates -- 📋 Moves CHANGELOG unreleased to version -- ✅ Validates version hierarchy - -**When to use:** Starting work on a new version - -**How to run:** -1. Go to Actions → Create version branch -2. Click "Run workflow" -3. Enter version (e.g., 03.06.00) -4. Select branch prefix (dev/, rc/, or version/) -5. Click "Run workflow" - -**Example:** -```yaml -new_version: 03.06.00 -branch_prefix: dev/ -version_text: beta -``` - -### Release Pipeline (release_pipeline.yml) - -**Trigger:** Manual workflow dispatch or release event - -**Purpose:** Promotes branches through release stages and creates distributions - -**What it does:** -- 🔄 Promotes branches: dev → rc → version → main -- 📅 Normalizes dates in manifest and CHANGELOG -- 📦 Builds distributable ZIP package -- 🚀 Uploads to SFTP server -- 🏷️ Creates Git tag -- 📋 Creates GitHub Release -- 🔒 Attests build provenance - -**When to use:** Promoting a version through release stages - -**How to run:** -1. Go to Actions → Release Pipeline -2. Click "Run workflow" -3. Select classification (auto/rc/stable) -4. Click "Run workflow" - -**Release flow:** -``` -dev/X.Y.Z → rc/X.Y.Z → version/X.Y.Z → main - (dev) (RC) (stable) (production) -``` - -### Deploy to Staging (deploy_staging.yml) - -**Trigger:** Manual workflow dispatch - -**Purpose:** Deploys template to staging/development environments - -**What it does:** -- ✅ Validates deployment prerequisites -- 📦 Builds deployment package -- 🚀 Uploads via SFTP to environment -- 📝 Creates deployment summary - -**When to use:** Testing in staging before production release - -**How to run:** -1. Go to Actions → Deploy to Staging -2. Click "Run workflow" -3. Select environment (staging/development/preview) -4. Optionally specify version -5. Click "Run workflow" - -**Required secrets:** -- `STAGING_HOST` - SFTP hostname -- `STAGING_USER` - SFTP username -- `STAGING_KEY` - SSH private key (or `STAGING_PASSWORD`) -- `STAGING_PATH` - Remote deployment path - -### Repository Health (repo_health.yml) - -**Trigger:** Manual workflow dispatch (admin only) - -**Purpose:** Comprehensive repository health and configuration checks - -**What it does:** -- 🔐 Validates release configuration -- 🌐 Tests SFTP connectivity -- 📂 Checks scripts governance -- 📄 Validates required artifacts -- 🔍 Extended checks (SPDX, ShellCheck, etc.) - -**When to use:** Before major releases or when debugging deployment issues - -**How to run:** -1. Go to Actions → Repo Health -2. Click "Run workflow" -3. Select profile (all/release/repo) -4. Click "Run workflow" - -**Profiles:** -- `all` - Run all checks -- `release` - Release configuration and SFTP only -- `scripts` - Scripts governance only -- `repo` - Repository health only - -## Common Development Tasks - -### Starting a New Feature - -```bash -# 1. Create a new version branch via GitHub Actions -# Actions → Create version branch → dev/X.Y.Z - -# 2. Clone and checkout the new branch -git fetch origin -git checkout dev/X.Y.Z - -# 3. Make your changes -vim src/index.php - -# 4. Validate locally -make validate-required - -# 5. Commit and push -git add -A -git commit -m "feat: add new feature" -git push origin dev/X.Y.Z -``` - -### Running All Validations Locally - -```bash -# Run comprehensive validation suite -make validate-required - -# Run quality checks -make quality -``` - -### Creating a Release Package - -```bash -# Package with auto-detected version -```bash -# Package with auto-detected version -make package - -# Verify package contents -unzip -l dist/moko-cassiopeia-*.zip -``` - -### Updating Version Numbers - -```bash -# Via GitHub Actions (recommended) -# Actions → Release Management workflow -``` - -### Updating CHANGELOG - -Update CHANGELOG.md manually or via pull request following the existing format. - -## Troubleshooting - -### CI Failures - -#### PHP Syntax Errors - -```bash -# Check specific file -php -l src/index.php - -# Run validation -make validate-required -``` - -#### Manifest Validation Failed - -```bash -# Validate manifest and XML files -make validate-required -``` - -#### Version Alignment Issues - -```bash -# Check version consistency -make validate-required -``` - -### Workflow Failures - -#### "Branch already exists" - -```bash -# Check existing branches -git branch -r | grep dev/ - -# Delete remote branch if needed (carefully!) -git push origin --delete dev/03.06.00 -``` - -#### "Missing required secrets" - -Go to repository Settings → Secrets and variables → Actions, and add: -- `FTP_SERVER` -- `FTP_USER` -- `FTP_KEY` or `FTP_PASSWORD` -- `FTP_PATH` - -#### SFTP Connection Failed - -1. Verify credentials in repo_health workflow: - - Actions → Repo Health → profile: release - -2. Check SSH key format (OpenSSH, not PuTTY PPK) - -3. Verify server allows connections from GitHub IPs - -### Quality Check Failures - -#### PHPStan Errors - -```bash -# Run locally to see full output -phpstan analyse --configuration=phpstan.neon - -# Generate baseline to ignore existing issues -phpstan analyse --configuration=phpstan.neon --generate-baseline -``` - -#### PHPCS Violations - -```bash -# Check violations -phpcs --standard=phpcs.xml src/ - -# Auto-fix where possible -phpcbf --standard=phpcs.xml src/ - -# Show specific error codes -phpcs --standard=phpcs.xml --report=source src/ -``` - -#### Joomla Testing Failed - -1. Check PHP/Joomla version matrix compatibility -2. Review MySQL connection errors -3. Verify template manifest structure -4. Check template file paths - -## Best Practices - -### Version Management - -1. **Always use version branches:** dev/X.Y.Z, rc/X.Y.Z, version/X.Y.Z -2. **Follow hierarchy:** dev → rc → version → main -3. **Update CHANGELOG:** Document all changes in Unreleased section -4. **Semantic versioning:** Major.Minor.Patch (03.06.00) - -### Code Quality - -1. **Run validations locally** before pushing -2. **Fix PHPStan warnings** at level 5 -3. **Follow PSR-12** coding standards -4. **Add SPDX license headers** to new files -5. **Keep functions small** and well-documented - -### Workflow Usage - -1. **Use CI for every commit** - automated validation -2. **Run repo_health before releases** - comprehensive checks -3. **Test on staging first** - never deploy directly to production -4. **Monitor workflow runs** - fix failures promptly -5. **Review workflow logs** - understand what changed - -### Release Process - -1. **Create dev branch** → Work on features -2. **Promote to rc** → Release candidate testing -3. **Promote to version** → Stable release -4. **Merge to main** → Production (auto-merged via PR) -5. **Create GitHub Release** → Public distribution - -### Security - -1. **Never commit secrets** - use GitHub Secrets -2. **Use SSH keys** for SFTP (not passwords) -3. **Scan for secrets** - runs automatically in CI -4. **Keep dependencies updated** - security patches -5. **Review security advisories** - GitHub Dependabot - -### Documentation - -1. **Update docs with code** - keep in sync -2. **Document workflow changes** - update this guide -3. **Add examples** - show, don't just tell -4. **Link to relevant docs** - cross-reference -5. **Keep README current** - first impression matters - -## Quick Links - -- [Main README](../README.md) - Project overview -- [Joomla Development Guide](./JOOMLA_DEVELOPMENT.md) - Testing and quality -- [CHANGELOG](../CHANGELOG.md) - Version history -- [CONTRIBUTING](../CONTRIBUTING.md) - Contribution guidelines - -## Getting Help - -1. **Check workflow logs** - Most issues have clear error messages -2. **Review this guide** - Common solutions documented -3. **Run validation scripts** - Identify specific issues -4. **Open an issue** - For bugs or questions -5. **Contact maintainers** - For access or configuration issues - ---- - -## Metadata - -* Document: docs/WORKFLOW_GUIDE.md -* Repository: [https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx](https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx) -* Path: /docs/WORKFLOW_GUIDE.md -* Owner: Moko Consulting -* Version: 03.06.03 -* Status: Active -* Effective Date: 2026-01-30 -* Classification: Public Open Source Documentation - -## Revision History - -| Date | Change Summary | Author | -| ---------- | ----------------------------------------------------- | --------------- | -| 2026-01-30 | Updated metadata to MokoStandards format | GitHub Copilot | -| 2025-01-04 | Initial workflow guide created | GitHub Copilot |