MokoJoomHero/README.md

MokoJoomHero

A Joomla module that displays a random hero image from a configurable folder with overlay content -- perfect for dynamic landing pages, splash screens, and promotional banners.

---

Features

• Random hero images -- automatically selects a random image from a specified folder on each page load
• Content overlay -- display titles, text, and call-to-action buttons on top of hero images
• Joomla 5/6 native -- built as a modern Joomla module following current extension standards
• Automated update server -- update.xml is managed automatically via CI/CD workflows for one-click updates in the Joomla admin
• GPL-3.0 licensed -- fully open-source with automated license sync workflows
• CI/CD pipeline -- includes Gitea Actions workflows for linting, testing, building, packaging, and releasing
• MokoStandards governed -- follows Moko Consulting's platform standards for quality and consistency

Requirements

Requirement	Version
Joomla	5.x or 6.x
PHP	8.1 or later
Web Server	Apache or Nginx

Installation

From Joomla Admin (Recommended)

1. Download the latest .zip release from Releases
2. In Joomla admin, go to System > Install > Extensions
3. Upload the .zip package and click Upload & Install

Automatic Updates

Once installed, MokoJoomHero registers itself with the Joomla update server. New versions appear automatically under System > Update > Extensions in the Joomla admin panel.

Configuration

After installation, configure the module in System > Site Modules > MokoJoomHero:

1. Image folder -- set the path to the folder containing your hero images (relative to /images/)
2. Overlay content -- configure the title, description, and CTA button text
3. Module position -- assign the module to a template position (e.g., hero, banner, top)
4. Display options -- control visibility per menu item, access level, and publishing schedule

Usage

1. Place your hero images (JPG, PNG, WebP) into the configured image folder
2. Assign the module to the desired position in your Joomla template
3. Each page load randomly selects and displays one image with your overlay content

Development

This project uses a Makefile for common development tasks:

make lint       # Run linters
make validate   # Validate extension structure
make test       # Run tests
make build      # Build the extension
make package    # Create installable .zip package
make release    # Full release workflow
make clean      # Clean build artifacts

Project Structure

MokoJoomHero/
  src/              # Joomla module source files
  scripts/          # Build and utility scripts
  docs/             # Documentation
  .gitea/workflows/ # CI/CD pipeline (Gitea Actions)
  update.xml        # Joomla update server manifest
  updates.xml       # Joomla update server manifest (alternate)
  Makefile          # Build automation
  phpstan.neon      # Static analysis configuration

Documentation

Full documentation is available on the Wiki.

Page	Description
Quick Start	Get started with the license sync workflow
Firewall Configuration	Configure firewalls for automated license downloads
Implementation Summary	Technical details of the license download implementation
Update Server	How update.xml is automatically managed

Contributing

See CONTRIBUTING.md for development guidelines and contribution instructions.

License

This project is licensed under the GNU General Public License v3.0 or later -- see the LICENSE file.

---

Moko Consulting -- MokoStandards