MokoJoomHero/README.md

<!-- Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>

 This file is part of a Moko Consulting project.

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

 # FILE INFORMATION
 REPO: https://git.mokoconsulting.tech/MokoConsulting/MokoJoomHero
 FILE: ./README.md
 BRIEF: MokoJoomHero - Joomla Hero Module
 -->

# MokoJoomHero

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 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](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

Or build from source:

```bash
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](CONTRIBUTING.md) for guidelines.

## Versioning

This project uses [Semantic Versioning](https://semver.org/). See [CHANGELOG.md](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](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)