# Placeholders

## PlaceholderAPI Integration

### Overview

Both Jails and JailsPlus support PlaceholderAPI, allowing you to display jail-related information in scoreboards, chat, holograms, and other plugins that support PlaceholderAPI placeholders.

### Available Placeholders

All placeholders use the `jails` identifier. Use them in any PlaceholderAPI-compatible plugin with the format `%jails_<placeholder>%`.

**Total Placeholders**: 48

#### Player Status Placeholders

These placeholders require a player context and show individual player information.

| Placeholder            | Description                                             | Example Output                              |
| ---------------------- | ------------------------------------------------------- | ------------------------------------------- |
| `%jails_isjailed%`     | Returns true/false if player is currently jailed        | `true` or `false`                           |
| `%jails_ishandcuffed%` | Returns true/false if player is currently handcuffed    | `true` or `false`                           |
| `%jails_jailname%`     | Returns the name of the jail where player is imprisoned | `Prison1` or empty if not jailed            |
| `%jails_reason%`       | Returns the reason for being jailed                     | `Griefing` or `No reason`                   |
| `%jails_jailer%`       | Returns the name of who jailed the player               | `Admin123` or `Unknown`                     |
| `%jails_jail_status%`  | Returns current jail status                             | `FREE`, `JAILED`, `PERMANENT`, or `EXPIRED` |
| `%jails_spawn_option%` | Returns where player will spawn after unjail            | `world_spawn` or `original_location`        |

#### Time-based Placeholders

Display remaining jail time in various formats.

| Placeholder                   | Description                                       | Example Output                 |
| ----------------------------- | ------------------------------------------------- | ------------------------------ |
| `%jails_timeleft%`            | Returns formatted time remaining (human-readable) | `2 days, 5 hours, 30 minutes`  |
| `%jails_timeleft_seconds%`    | Returns time remaining in seconds                 | `189000` or `-1` for permanent |
| `%jails_timeleft_minutes%`    | Returns time remaining in minutes                 | `3150` or `-1` for permanent   |
| `%jails_timeleft_hours%`      | Returns time remaining in hours                   | `52` or `-1` for permanent     |
| `%jails_timeleft_days%`       | Returns time remaining in days                    | `2` or `-1` for permanent      |
| `%jails_endtime_timestamp%`   | Returns Unix timestamp when jail ends             | `1729329600000` or `0`         |
| `%jails_jailtime_percentage%` | Returns percentage of jail time served            | `75` (0-100)                   |

**Note**: Time placeholders return `PERMANENT` or `-1` for permanent jails, and `Expired` or `0` for expired sentences.

#### Location Placeholders

Display jail and original location information.

| Placeholder                       | Description                        | Example Output      |
| --------------------------------- | ---------------------------------- | ------------------- |
| `%jails_jail_location%`           | Returns full jail location         | `world 100 64 200`  |
| `%jails_jail_location_world%`     | Returns jail world name            | `world`             |
| `%jails_jail_location_x%`         | Returns jail X coordinate          | `100`               |
| `%jails_jail_location_y%`         | Returns jail Y coordinate          | `64`                |
| `%jails_jail_location_z%`         | Returns jail Z coordinate          | `200`               |
| `%jails_original_location%`       | Returns player's pre-jail location | `world 500 70 -300` |
| `%jails_original_location_world%` | Returns original world name        | `world`             |

#### Bail System Placeholders

Display bail information (requires Vault and economy plugin).

| Placeholder        | Description                           | Example Output              |
| ------------------ | ------------------------------------- | --------------------------- |
| `%jails_bail%`     | Returns formatted bail amount         | `$5000.00` or `No bail set` |
| `%jails_bail_raw%` | Returns raw bail amount (number only) | `5000.0` or `0`             |
| `%jails_hasbail%`  | Returns true/false if bail is set     | `true` or `false`           |

#### IP Jail Placeholders

| Placeholder          | Description                                 | Example Output    |
| -------------------- | ------------------------------------------- | ----------------- |
| `%jails_isipjailed%` | Returns true/false if player's IP is jailed | `true` or `false` |

**Note**: This placeholder requires the player to be online.

#### Server Statistics Placeholders

These placeholders don't require a player context and show server-wide statistics.

| Placeholder                | Description                                  | Example Output |
| -------------------------- | -------------------------------------------- | -------------- |
| `%jails_totalcount%`       | Total number of currently jailed players     | `5`            |
| `%jails_handcuffed_count%` | Total number of currently handcuffed players | `2`            |
| `%jails_jail_count%`       | Total number of jail locations configured    | `3`            |
| `%jails_flag_count%`       | Total number of flag zones configured        | `4`            |
| `%jails_ipjail_count%`     | Total number of IP-jailed addresses          | `1`            |

#### List Placeholders

Get lists of jails, flags, and players (newline-separated).

| Placeholder                             | Description                                             | Example Output              |
| --------------------------------------- | ------------------------------------------------------- | --------------------------- |
| `%jails_jails_list%`                    | List of all jail names (newline-separated)              | `Prison1\nPrison2\nJail3`   |
| `%jails_jails_list_comma%`              | List of all jail names (comma-separated)                | `Prison1, Prison2, Jail3`   |
| `%jails_flags_list%`                    | List of all flag names (newline-separated)              | `Flag1\nFlag2\nFlag3`       |
| `%jails_flags_list_comma%`              | List of all flag names (comma-separated)                | `Flag1, Flag2, Flag3`       |
| `%jails_jailed_players_list%`           | List of all jailed player names (newline-separated)     | `Player1\nPlayer2\nPlayer3` |
| `%jails_jailed_players_list_comma%`     | List of all jailed player names (comma-separated)       | `Player1, Player2, Player3` |
| `%jails_handcuffed_players_list%`       | List of all handcuffed player names (newline-separated) | `Player1\nPlayer2`          |
| `%jails_handcuffed_players_list_comma%` | List of all handcuffed player names (comma-separated)   | `Player1, Player2`          |

#### Per-Jail Statistics Placeholders

Get the count of players in a specific jail. Use the format `jail_<jailname>_count`.

| Placeholder                     | Description                         | Example Output |
| ------------------------------- | ----------------------------------- | -------------- |
| `%jails_jail_<jailname>_count%` | Number of players in specified jail | `3`            |

**Examples**:

* `%jails_jail_Prison1_count%` - Returns count in "Prison1"
* `%jails_jail_MainJail_count%` - Returns count in "MainJail"
* `%jails_jail_spawn_count%` - Returns count in "spawn"

### Usage Examples

#### Scoreboard (with DeluxeScoreboard, FeatherBoard, etc.)

```yaml
lines:
  - "&6=== Jail Status ==="
  - "&eJailed: &f%jails_isjailed%"
  - "&eJail: &f%jails_jailname%"
  - "&eTime Left: &f%jails_timeleft%"
  - "&eBail: &f%jails_bail%"
  - ""
  - "&7Total Jailed: &f%jails_totalcount%"
```

#### Chat Format (with ChatControl, EssentialsChat, etc.)

```yaml
format: "[%jails_jailname%] {player}: {message}"
# Shows jail name in brackets before player's message
```

#### Tab List (with TAB plugin)

```yaml
tabprefix: "%jails_isjailed% == true ? &c[JAILED] : ''"
# Shows [JAILED] prefix if player is jailed
```

#### Hologram (with HolographicDisplays, DecentHolograms)

```yaml
lines:
  - "&c&lJAIL STATISTICS"
  - "&eJailed Players: &f%jails_totalcount%"
  - "&eHandcuffed: &f%jails_handcuffed_count%"
  - "&eTotal Jails: &f%jails_jail_count%"
```

#### Custom Menu (with DeluxeMenus)

```yaml
items:
  jail_status:
    material: IRON_BARS
    display_name: "&cYour Jail Status"
    lore:
      - "&7Status: %jails_isjailed%"
      - "&7Jail: %jails_jailname%"
      - "&7Time Left: %jails_timeleft%"
      - "&7Bail: %jails_bail%"
```

#### Action Bar (with ActionBarAPI, CMI, etc.)

```yaml
message: "&c⚠ Jailed in %jails_jailname% | Time: %jails_timeleft%"
```

#### Boss Bar

```yaml
title: "&c&lJAILED: %jails_timeleft% remaining"
# Shows remaining time in boss bar
```

### Conditional Placeholders

You can use PlaceholderAPI's conditional system with JailsPlus placeholders:

#### Using ParseOther

```
%parseother_{player}_jails_isjailed%
# Check if another player is jailed
```

#### Using Conditions (with PAPI expansion)

```
%jails_isjailed% == true ? &c[JAILED] : &a[FREE]
# Shows [JAILED] in red or [FREE] in green
```

### Testing Placeholders

Use these commands to test placeholders in-game:

```
/papi parse me %jails_isjailed%
/papi parse me %jails_jailname%
/papi parse me %jails_timeleft%
/papi parse me %jails_totalcount%
```

### Troubleshooting

#### Placeholders show as raw text

**Problem**: `%jails_isjailed%` appears literally instead of showing true/false

**Solutions**:

1. Verify PlaceholderAPI is installed: `/papi version`
2. Check expansion is registered: `/papi list` (look for "jails")
3. Ensure the plugin supports PlaceholderAPI
4. Try `/papi reload` to refresh expansions

#### Placeholders return empty or incorrect values

**Problem**: Placeholder doesn't show expected value

**Solutions**:

1. Verify player is actually jailed: `/jails list prisoners`
2. Check placeholder spelling (case-sensitive)
3. Ensure player context is available (player-specific placeholders need a player)
4. Review server logs for errors

#### Expansion not registering

**Problem**: Console shows "PlaceholderAPI not found - placeholder support disabled"

**Solutions**:

1. Install PlaceholderAPI from [SpigotMC](https://www.spigotmc.org/resources/placeholderapi.6245/)
2. Ensure it's version 2.11.6 or higher
3. Restart the server (don't just reload)
4. Check for startup errors in console

#### Time placeholders show wrong format

**Problem**: Time shows as seconds instead of formatted string

**Solutions**:

1. Use `%jails_timeleft%` for human-readable format
2. Use `%jails_timeleft_seconds%`, `_minutes%`, or `_hours%` for specific units
3. Remember: `-1` means permanent jail, `0` means expired

### Advanced Usage

#### Multiple Conditions

```yaml
# Show different messages based on bail status
lore:
  - "%jails_hasbail% == true ? &eBail: %jails_bail% : &cNo bail available"
```

#### Formatted Time Display

```yaml
# Custom time format in menus
lore:
  - "&7Time Left:"
  - "&f%jails_timeleft_hours% hours"
  - "&f%jails_timeleft_minutes% minutes remaining"
```

#### Server Statistics Dashboard

```yaml
# Complete server overview
hologram:
  - "&6&l⚔ JAIL STATISTICS ⚔"
  - ""
  - "&e━━━━━━━━━━━━━━━━━━━━"
  - "&fJailed Players: &c%jails_totalcount%"
  - "&fHandcuffed: &6%jails_handcuffed_count%"
  - "&fJail Locations: &a%jails_jail_count%"
  - "&fFlag Zones: &b%jails_flag_count%"
  - "&e━━━━━━━━━━━━━━━━━━━━"
```

### API for Developers

If you're a plugin developer, you can use PlaceholderAPI to get JailsPlus data programmatically:

```java
import me.clip.placeholderapi.PlaceholderAPI;

// get placeholder value for a player
Player player = ...;
String isJailed = PlaceholderAPI.setPlaceholders(player, "%jails_isjailed%");
String jailName = PlaceholderAPI.setPlaceholders(player, "%jails_jailname%");
String timeLeft = PlaceholderAPI.setPlaceholders(player, "%jails_timeleft%");

// get server statistics, a player isnt needed here
String totalJailed = PlaceholderAPI.setPlaceholders(null, "%jails_totalcount%");
```

### Support

If you encounter issues with placeholders:

1. Check this documentation first
2. Verify PlaceholderAPI is installed and updated
3. Review server console for errors
4. Contact plugin support with relevant logs

***
