# Installation — Leaderboards Pro

**Requires:** NamelessMC **2.2.x** · PHP **8.0+**
**Optional:** Forum module (for Top Posts / Reputation / Reactions data), a vote
module that records per-user votes (for Top Voters — e.g. **VotePro**).

---

## 1. Upload

This package mirrors your NamelessMC root. Upload the **contents of `upload/`**
into your site root so the paths merge:

```
upload/modules/LeaderboardsPro/                                  → modules/LeaderboardsPro/
upload/custom/templates/DefaultRevamp/leaderboards_pro.tpl       → custom/templates/DefaultRevamp/leaderboards_pro.tpl
upload/custom/templates/DefaultRevamp/widgets/leaderboard_widget.tpl
upload/custom/panel_templates/Default/leaderboards/panel_leaderboards.tpl
```

Nothing is overwritten in core or in other modules.

## 2. Enable

StaffCP → **Modules** → enable **LeaderboardsPro**.
On enable, the module creates `nl2_leaderboards_settings` (with 5 default
leaderboards) and seeds its settings. The trophy 🏆 **Leaderboards** link appears
in the navbar, and **Leaderboards Pro** appears in the StaffCP sidebar.

## 3. Configure (StaffCP → Leaderboards Pro)

- **Per leaderboard:** enable/disable, display order, result limit (1–100),
  display style (Auto / Podium / Compact list).
- **Public route:** default `/leaderboards`; change to `/stats`, `/top`,
  `/rankings`, `/leaderboards-pro`, … (takes effect immediately).
- **Appearance:** toggle "Use custom colours" and pick your palette, or leave it
  off to inherit the theme automatically.
- **Vote integration:** read-only diagnostics card.
- **Clear cache** button.

## 4. Widgets (optional)

StaffCP → **Widgets** → enable and position any of:
*Top Reputation, Top Posts, Top Reactions, Top Voters, Newest Members.*
They render a compact top-5 list and inherit your colours automatically.

---

## Themes

- **DefaultRevamp:** works out of the box.
- **MinecraftThemesLab:** first-class — the leaderboards automatically match the
  active preset (and recolour when you switch preset). StaffCP colour overrides
  win over the preset.
- **Custom/premium themes:** the page and widget templates are auto-provisioned
  into the active theme on first load (requires the theme directory to be
  writable). To customise, copy/edit
  `custom/templates/DefaultRevamp/leaderboards_pro.tpl` into your theme.

## Upgrading from v1.0

Overwrite the files with v1.1 — **do not re-install** the module. The
`display_style` column is added automatically on the first page load; your
configuration is preserved.

## Troubleshooting

- **Top Voters is hidden:** you need a vote module that records per-user votes
  (e.g. VotePro). The Partydragen "Vote" module only lists vote-site links and
  stores no per-user totals, so it cannot feed a leaderboard. The StaffCP
  **Vote integration** card tells you exactly what was detected.
- **A board is empty:** it has no data yet (e.g. no forum posts/reactions) — empty
  boards are hidden automatically.
- **Raw "Array" or a layout issue after a partial upload:** ensure both the
  module files **and** the `custom/...` template files were uploaded.
- **Banned/private members not shown:** by design — banned, private-profile and
  ghosted users are excluded.

## Uninstall

Disable the module in StaffCP. The settings table is intentionally retained so a
reinstall keeps your configuration. To remove data, drop
`nl2_leaderboards_settings` and delete the `LeaderboardsPro` rows from
`nl2_settings`.
