MokoJoomHero/README.md

MokoJoomHero

A Joomla site module for random hero image slideshows, video backgrounds, solid colours, gradients, and content overlays.

Overview

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

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 or 6.x

Installation

1. Download the latest release from the releases page
2. Upload mod_mokojoomhero-*.zip via System > Install > Upload Package File
3. Assign the module to a template position and configure

Or build from source:

make build

Usage

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

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

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Versioning

This project uses Semantic Versioning. See CHANGELOG.md for version history.

License

Copyright (C) 2026 Moko Consulting hello@mokoconsulting.tech

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

SPDX-License-Identifier: GPL-3.0-or-later

Support

• Wiki: MokoJoomHero Wiki
• Issues: Issue Tracker
• Contact: hello@mokoconsulting.tech
• Website: mokoconsulting.tech