PlaceholderAPI

PlaceholderAPI Integration (SimpleRanks)

PlaceholderAPI support allows SimpleRanks to provide dynamic values (placeholders) that can be used in chat formats, scoreboards, tab lists, GUIs, and other plugins.

This page explains how the SimpleRanks PlaceholderExpansion works and how to use it.

---

What is PlaceholderAPI?

PlaceholderAPI is a popular Spigot plugin that allows plugins to expose variables (called placeholders) which can be used in other plugins.

Placeholders look like this:

%identifier_placeholder%

In SimpleRanks, the identifier is:

%simpleranks_...%

---

Expansion Details

The PlaceholderExpansion class registers SimpleRanks placeholders with PlaceholderAPI.

Identifier

simpleranks

Author

TomMustBe12

Persist

true

This means the expansion stays loaded even after PlaceholderAPI reloads.

---

How It Works

When another plugin requests a placeholder like:

%simpleranks_rank%

PlaceholderAPI calls:

onPlaceholderRequest(Player player, String id)

• player → the player the placeholder is being resolved for
• id → the part after simpleranks_

Example:

%simpleranks_rank%

→ id = "rank"

The plugin then uses a switch statement to return the correct value.

---

Available Placeholders

%simpleranks_rank%

Function

Returns the fully formatted rank prefix, including color codes.

Behavior

• Gets the player's rank
• Retrieves the prefix from config
• Translates & color codes into Minecraft colors

Example Output

[ADMIN]

---

%simpleranks_raw_rank%

Function

Returns the raw rank name without formatting.

Example Output

ADMIN

---

%simpleranks_prefix%

Function

Returns only the prefix of the rank (with color applied).

Example Output

&c[ADMIN] → [ADMIN] (colored in red)

---

%simpleranks_important%

Function

Returns whether the rank is marked as important.

Output

true
false

---

Code Breakdown

onPlaceholderRequest

@Override
public @Nullable String onPlaceholderRequest(Player player, @NotNull String id)

This method:

1. Ensures the player is not null
2. Matches the placeholder ID
3. Returns the correct value

If no match is found:

return null;

---

Rank Fetching Logic

Example:

String rankName = rankManager.getRank(player.getUniqueId());

• Retrieves the player's assigned rank
• Used in multiple placeholders

---

Color Translation

ChatColor.translateAlternateColorCodes('&', text);

• Converts & color codes into Minecraft formatting
• Example: &cADMIN → red text

---

Usage Examples

Chat Plugin (EssentialsX / CMI / etc.)

%simpleranks_rank% %player_name%: %message%

Scoreboard

Rank: %simpleranks_raw_rank%

Tab List

%simpleranks_prefix% %player_name%

---

Requirements

• PlaceholderAPI installed
• SimpleRanks installed
• Expansion registered (automatically if coded in plugin)

---

Notes

• Placeholders require a valid player context
• If player == null, an empty string is returned
• Invalid placeholders return null
• All rank data is retrieved via RankManager

---

Tips

• Use %simpleranks_rank% for full formatting
• Use %simpleranks_raw_rank% for logic-based plugins
• Combine with chat plugins for clean formatting
• Keep rank prefixes consistent in your config

---

Summary

SimpleRanks integrates with PlaceholderAPI by registering a custom expansion. This allows other plugins to dynamically access player rank data, making it easy to display ranks across your server.