# 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.

![Joomla](https://img.shields.io/badge/Joomla-5.x%20%7C%206.x-blue?style=flat-square&logo=joomla&logoColor=white) ![PHP](https://img.shields.io/badge/PHP-%E2%89%A5%208.1-777BB4?style=flat-square&logo=php&logoColor=white) ![License](https://img.shields.io/badge/license-GPL--3.0--or--later-green?style=flat-square) ![Platform](https://img.shields.io/badge/platform-Gitea-609926?style=flat-square&logo=gitea&logoColor=white) ![Wiki](https://img.shields.io/badge/wiki-MokoJoomHero-blue?style=flat-square)

---

## 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](https://git.mokoconsulting.tech/MokoConsulting/MokoJoomHero/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:

```bash
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](https://git.mokoconsulting.tech/MokoConsulting/MokoJoomHero/wiki).

| Page | Description |
|---|---|
| [Quick Start](https://git.mokoconsulting.tech/MokoConsulting/MokoJoomHero/wiki/QUICKSTART) | Get started with the license sync workflow |
| [Firewall Configuration](https://git.mokoconsulting.tech/MokoConsulting/MokoJoomHero/wiki/FIREWALL_CONFIGURATION) | Configure firewalls for automated license downloads |
| [Implementation Summary](https://git.mokoconsulting.tech/MokoConsulting/MokoJoomHero/wiki/IMPLEMENTATION_SUMMARY) | Technical details of the license download implementation |
| [Update Server](https://git.mokoconsulting.tech/MokoConsulting/MokoJoomHero/wiki/update-server.-.-) | How `update.xml` is automatically managed |

## Contributing

See [CONTRIBUTING.md](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](LICENSE) file.

---

*[Moko Consulting](https://mokoconsulting.tech) -- [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)*