diff --git a/README.md b/README.md index 78eedca..e706865 100644 --- a/README.md +++ b/README.md @@ -7,108 +7,83 @@ # FILE INFORMATION REPO: https://git.mokoconsulting.tech/MokoConsulting/MokoJoomHero FILE: ./README.md - VERSION: 01.19.00 - BRIEF: MokoJoomHero - Joomla Module + BRIEF: MokoJoomHero - Joomla Hero Module --> # MokoJoomHero -A Joomla 5 site template developed following MokoStandards. +A Joomla site module for random hero image slideshows, video backgrounds, solid colours, gradients, and content overlays. [![License](https://img.shields.io/badge/license-GPL--3.0--or--later-blue.svg)](LICENSE) ## Overview -MokoJoomHero is a modern, accessible Joomla 5 template by Moko Consulting. It features a prominent hero section, flexible module positions, sticky header, customisable brand colour, and responsive layout — all built on Joomla's Web Asset Manager. +MokoJoomHero is a free, open-source Joomla module that creates dynamic hero sections with multiple background modes, configurable content overlays, and advanced features like parallax scrolling, A/B testing, and scheduling. Designed for the MokoOnyx template but works with any Joomla 5/6 template. ## Features -- **Hero Section**: Dedicated `hero` module position with gradient styling -- **Flexible Layout**: 11 module positions including sidebars, topbar, banner, and footer -- **Sticky Header**: Optional sticky navigation with smooth scroll -- **Brand Customisation**: Configurable brand colour, logo, and tagline via Template Manager -- **Responsive**: Mobile-first layout with CSS custom properties -- **Accessibility**: Semantic HTML5, ARIA landmarks, skip-to-content support -- **Web Asset Manager**: Modern asset loading via `joomla.asset.json` -- **Error & Offline Pages**: Custom styled error and offline templates +### Background Modes +- **Image Slideshow** — random images from a folder with 4 transition types (crossfade, slide, fade-to-black, zoom/Ken Burns) +- **Video** — YouTube, Vimeo, or local video with autoplay, mute toggle, and poster image +- **Solid Colour** — single colour picker +- **Gradient** — two-colour gradient with configurable angle + +### Content & Overlay +- **WYSIWYG Editor** or **Joomla Article** as content source +- **Per-slide content** — unique heading, body, and CTA per image slide via subform +- **Card mode** — white card with shadow and fade-in delay +- **Overlay** — solid or directional gradient (dark at bottom/top/left/right) +- **Text alignment** — horizontal (left/center/right) and vertical (top/center/bottom) +- **Content animations** — fade-in, slide-up, slide-left, slide-right with configurable delay + +### Advanced +- **Parallax scroll** — background moves at configurable speed (0.1–0.9) +- **A/B testing** — weighted random content variations, session-sticky per visitor +- **Scheduling** — start/end datetime with site timezone support +- **Scroll indicator** — animated chevron with smooth-scroll click handler +- **Mobile height** — separate height setting for mobile viewports +- **Reduced motion** — WCAG 2.1 AA compliant, respects `prefers-reduced-motion` ## Prerequisites - **PHP**: 8.1 or higher -- **Joomla**: 5.x (also compatible with 6.x) -- **Make**: GNU Make for build automation +- **Joomla**: 5.x or 6.x ## Installation -1. Build the template package: - ```bash - make build - ``` +1. Download the latest release from the [releases page](https://git.mokoconsulting.tech/MokoConsulting/MokoJoomHero/releases) +2. Upload `mod_mokojoomhero-*.zip` via **System > Install > Upload Package File** +3. Assign the module to a template position and configure -2. Upload the generated `tpl_mokojoomhero-1.0.0.zip` via Joomla's Extension Manager - -3. Set as default template in **System → Site Template Styles** - -## Usage +Or build from source: ```bash -# Display available commands -make help - -# Validate code -make validate - -# Build template package make build ``` -## Module Positions +## Usage -| Position | Purpose | -|----------|---------| -| `topbar` | Slim bar above the header (contact info, social links) | -| `banner` | Full-width banner below the header | -| `menu` | Main navigation inside the header | -| `hero` | Hero section with gradient background | -| `breadcrumbs` | Breadcrumb trail | -| `sidebar-left` | Left sidebar | -| `sidebar-right` | Right sidebar | -| `main-top` | Above the main content area | -| `main-bottom` | Below the main content area | -| `footer` | Footer area | -| `debug` | Debug output (hidden from users) | - -## Template Parameters - -Configure via **System → Site Template Styles → MokoJoomHero**: - -- **Logo** — Upload a site logo image -- **Site Description** — Tagline displayed next to the logo -- **Brand Colour** — Primary accent colour (default: `#1a73e8`) -- **Fluid Container** — Toggle full-width vs fixed-width layout -- **Sticky Header** — Keep the header visible on scroll -- **Back to Top** — Floating scroll-to-top button +1. Go to **Content > Site Modules > MokoJoomHero** +2. Select a **Hero Mode** (Images, Video, Solid Colour, or Gradient) +3. Add content via the **Hero Content** tab +4. Configure overlay, text alignment, and animations in **Overlay & Text** +5. Assign to a module position and publish ## Project Structure ``` -. -├── docs/ # Documentation files -├── scripts/ # Build and deployment scripts -├── src/ # Template source code -│ ├── css/template.css # Main stylesheet -│ ├── js/template.js # Main JavaScript -│ ├── images/ # Template images -│ ├── html/ # Template overrides -│ ├── language/en-GB/ # Language files -│ ├── templateDetails.xml # Joomla manifest -│ ├── joomla.asset.json # Web Asset Manager config -│ ├── index.php # Main template -│ ├── error.php # Error page -│ ├── offline.php # Offline page -│ └── component.php # Component-only output -├── Makefile # Build automation -└── README.md # This file +src/ +├── mod_mokojoomhero.php # Module entry point +├── mod_mokojoomhero.xml # Joomla manifest +├── script.php # Install script +├── tmpl/default.php # Template +├── media/ +│ ├── css/mod_mokojoomhero.css +│ ├── js/mod_mokojoomhero.js +│ └── joomla.asset.json +└── language/ + ├── en-GB/ + └── en-US/ ``` ## Contributing @@ -117,9 +92,7 @@ We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guid ## Versioning -This project uses [Semantic Versioning](https://semver.org/). - -See [CHANGELOG.md](CHANGELOG.md) for version history. +This project uses [Semantic Versioning](https://semver.org/). See [CHANGELOG.md](CHANGELOG.md) for version history. ## License @@ -131,6 +104,7 @@ SPDX-License-Identifier: GPL-3.0-or-later ## Support -- **Documentation**: See the [docs/](docs/) directory +- **Wiki**: [MokoJoomHero Wiki](https://git.mokoconsulting.tech/MokoConsulting/MokoJoomHero/wiki) +- **Issues**: [Issue Tracker](https://git.mokoconsulting.tech/MokoConsulting/MokoJoomHero/issues) - **Contact**: hello@mokoconsulting.tech - **Website**: [mokoconsulting.tech](https://mokoconsulting.tech) diff --git a/src/mod_mokojoomhero.xml b/src/mod_mokojoomhero.xml index 6d6d355..035e518 100644 --- a/src/mod_mokojoomhero.xml +++ b/src/mod_mokojoomhero.xml @@ -23,7 +23,7 @@ Copyright (C) 2026 Moko Consulting. All rights reserved. GPL-3.0-or-later 01.19.00 - Displays a random hero image slideshow or background video with content overlaid. Designed for MokoOnyx template. By Moko Consulting. + Random hero image slideshow, video backgrounds, solid colour/gradient, parallax, content animations, A/B testing, scheduling, and overlay with card support. Free and open source. By Moko Consulting. script.php