diff --git a/src/main/java/me/clip/placeholderapi/PlaceholderHook.java b/src/main/java/me/clip/placeholderapi/PlaceholderHook.java index 622260f..49c9ede 100644 --- a/src/main/java/me/clip/placeholderapi/PlaceholderHook.java +++ b/src/main/java/me/clip/placeholderapi/PlaceholderHook.java @@ -25,8 +25,22 @@ import org.bukkit.entity.Player; import org.jetbrains.annotations.NotNull; import org.jetbrains.annotations.Nullable; +@Deprecated public abstract class PlaceholderHook { + + /** + * Please see {@link me.clip.placeholderapi.expansion.PlaceholderExpansion#parsePlaceholders(OfflinePlayer, String) PlaceholderExpansion#parsePlaceholder(OfflinePlayer, String)} + * for a full description of what this method is used for. + * + * @param player Possibly-null OfflinePlayer instance to use. + * @param params String after {@code %_} and before the second percent symbol. + * @return Possibly-null String depending on the Expansions returned value. + * @deprecated Planned for removal in 2.14.0 + *
Please use {@link me.clip.placeholderapi.expansion.PlaceholderExpansion#parsePlaceholders(OfflinePlayer, String) parsePlaceholders(OfflinePlayer, String)} + * instead + */ @Nullable + @Deprecated public String onRequest(final OfflinePlayer player, @NotNull final String params) { if (player != null && player.isOnline()) { return onPlaceholderRequest((Player) player, params); @@ -35,7 +49,20 @@ public abstract class PlaceholderHook { return onPlaceholderRequest(null, params); } + /** + * Please see {@link me.clip.placeholderapi.expansion.PlaceholderExpansion#parsePlaceholders(Player, String) PlaceholderExpansion#parsePlaceholder(Player, String)} + * for a full description of what this method is used for. + * + * @param player Possibly-null Player instance to use. + * @param params String after {@code %_} and before the second percent symbol. + * @return Possibly-null String depending on the Expansions returned value. + * + * @deprecated Planned for removal in 2.14.0 + *
Please use {@link me.clip.placeholderapi.expansion.PlaceholderExpansion#parsePlaceholders(Player, String) parsePlaceholders(Player, String)} + * instead + */ @Nullable + @Deprecated public String onPlaceholderRequest(final Player player, @NotNull final String params) { return null; } diff --git a/src/main/java/me/clip/placeholderapi/expansion/PlaceholderExpansion.java b/src/main/java/me/clip/placeholderapi/expansion/PlaceholderExpansion.java index 5cd3029..e2970fe 100644 --- a/src/main/java/me/clip/placeholderapi/expansion/PlaceholderExpansion.java +++ b/src/main/java/me/clip/placeholderapi/expansion/PlaceholderExpansion.java @@ -26,7 +26,9 @@ import java.util.logging.Level; import me.clip.placeholderapi.PlaceholderAPIPlugin; import me.clip.placeholderapi.PlaceholderHook; import org.bukkit.Bukkit; +import org.bukkit.OfflinePlayer; import org.bukkit.configuration.ConfigurationSection; +import org.bukkit.entity.Player; import org.jetbrains.annotations.ApiStatus; import org.jetbrains.annotations.Contract; import org.jetbrains.annotations.NotNull; @@ -398,6 +400,45 @@ public abstract class PlaceholderExpansion extends PlaceholderHook { getAuthor(), getVersion()); } + /** + * PlaceholderAPI will call this method whenever a valid placeholder pattern with a matching + * PlaceholderExpansion is found. + *
The provided Player can be one of 3 possible states: + * + * + * + * By default will PlaceholderAPI check if the OfflinePlayer is both not null and online. + *
If both checks return true will it call {@link #parsePlaceholders(Player, String) parsePlaceholder(Player, String)} + * with the provided OfflinePlayer casted to a Player. Otherwise will the same method be called, + * but with {@code null} as Player value. + * + *

To use this method in your PlaceholderExpansion, override it. + * + *

When {@code null} is returned will PlaceholderAPI see this as "invalid placeholder" and + * return the placeholder as-is in the final String. + * + * @param player The OfflinePlayer to use. + * @param params The params from {@code %_%} + * @return Parsed placeholder, or null, depending on the Expansion's handling of it. + */ + @Nullable + public String parsePlaceholders(OfflinePlayer player, String params) { + if (player != null && player.isOnline()) { + this.onPlaceholderRequest((Player) player, params); + } + + return parsePlaceholders(null, params); + } + + @Nullable + public String parsePlaceholders(Player player, String params){ + return this.onRequest(player, params); + } + // === Deprecated API === /** diff --git a/src/main/java/me/clip/placeholderapi/expansion/Relational.java b/src/main/java/me/clip/placeholderapi/expansion/Relational.java index 9d39785..627c711 100644 --- a/src/main/java/me/clip/placeholderapi/expansion/Relational.java +++ b/src/main/java/me/clip/placeholderapi/expansion/Relational.java @@ -21,23 +21,29 @@ package me.clip.placeholderapi.expansion; import org.bukkit.entity.Player; +import org.jetbrains.annotations.NotNull; +import org.jetbrains.annotations.Nullable; /** - * Implementing this interface allows your {@link me.clip.placeholderapi.expansion.PlaceholderExpansion PlaceholderExpansion} - * to be used as a relational placeholder expansion. + * This interface should be used when your {@link me.clip.placeholderapi.expansion.PlaceholderExpansion PlaceholderExpansion} + * should support relational placeholders. * - *

Relational placeholders take two Players as input and are always prefixed with {@code rel_}, - * so {@code %foo_bar%} becomes {@code %rel_foo_bar%} + *

The difference between relational placeholders and normal ones is, that relational ones start + * with a {@code rel_} prefix and have two Players provided, instead of one. + *
The main purpose is to return a String based on the "relationship" between the two players + * (i.e. if both are within the same world). */ public interface Relational { /** - * This method is called whenever a placeholder starting with {@code rel_} is called. + * This method will be called whenever a valid placeholder in the format {@code %rel__%} + * is found. * - * @param one The first player used for the placeholder. - * @param two The second player used for the placeholder. - * @param identifier The text right after the expansion's name (%expansion_identifier%) - * @return Parsed String from the expansion. + * @param one The first player to use for comparison. + * @param two The second player to use for comparison + * @param identifier String right after {@code %rel__} and before the second percent symbol. + * @return Possibly-null String, depending on what the expansion returns. */ - String onPlaceholderRequest(Player one, Player two, String identifier); + @Nullable + String onPlaceholderRequest(Player one, Player two, @NotNull String identifier); } diff --git a/src/main/java/me/clip/placeholderapi/replacer/CharsReplacer.java b/src/main/java/me/clip/placeholderapi/replacer/CharsReplacer.java index 0fc6f8d..3660027 100644 --- a/src/main/java/me/clip/placeholderapi/replacer/CharsReplacer.java +++ b/src/main/java/me/clip/placeholderapi/replacer/CharsReplacer.java @@ -116,7 +116,7 @@ public final class CharsReplacer implements Replacer { continue; } - final String replacement = placeholder.onRequest(player, parametersString); + final String replacement = placeholder.parsePlaceholders(player, parametersString); if (replacement == null) { builder.append(closure.head).append(identifierString); diff --git a/src/main/java/me/clip/placeholderapi/replacer/RegexReplacer.java b/src/main/java/me/clip/placeholderapi/replacer/RegexReplacer.java index b9e1261..9a37b45 100644 --- a/src/main/java/me/clip/placeholderapi/replacer/RegexReplacer.java +++ b/src/main/java/me/clip/placeholderapi/replacer/RegexReplacer.java @@ -61,7 +61,7 @@ public final class RegexReplacer implements Replacer { continue; } - final String requested = expansion.onRequest(player, parameters); + final String requested = expansion.parsePlaceholders(player, parameters); matcher.appendReplacement(builder, requested != null ? requested : matcher.group(0)); } while (matcher.find());