jmiller
78c6b8468d
Repo Health / Access control (push) Successful in 1s
Cascade Main → Dev / Cascade main → branches (push) Successful in 1s
Repo Health / Release configuration (push) Failing after 3s
Repo Health / Scripts governance (push) Successful in 2s
Repo Health / Repository health (push) Failing after 3s
Secret Scanning / Gitleaks Secret Scan (push) Successful in 6s
Security Audit / Dependency Audit (push) Successful in 2s
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
104 lines
4.7 KiB
Markdown
104 lines
4.7 KiB
Markdown
# 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](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)*
|