- #### getAuthor This method allows you to set the name of the expansion's author. - #### getIdentifier The identifier is the part in the placeholder that is between the first `%` (Or `{` if bracket placeholders are used) and the first `_`. Because of that can you not use `%`, `{`, `}` or `_` in your identifier. If you still want to use those symbols can you override the `getName()` method to display a different name. - #### getVersion This is a string, which means it can contain more than just a number. This is used to determine if a new update is available or not when the expansion is shared on the eCloud. For expansions that are part of a plugin, this does not really matter. Those are all the neccessary parts for your PlaceholderExpansion. Any other methods that are part of the [`PlaceholderExpansion`][placeholderexpansion] class are optional and will usually not be used, or will default to a specific value. Please read the Javadoc comments of those methods for more information.
> Please read the [`Common Parts` Section](#common-parts) for details on all the methods. Below is a full example of an internal Expansion class. Please note the override of the `persist()` method to guarantee the Expansion isn't unloaded during a `/papi reload` operation. We also use the provided `SomePlugin` instance for information such as the version and authors. This allows us to keep the code clean while not having to deal with updating the expansion's information every time we make changes to the plugin. ```java package at.helpch.placeholderapi.example.expansion; import at.helpch.placeholderapi.example.SomePlugin; import me.clip.placeholderapi.expansion.PlaceholderExpansion; import org.bukkit.OfflinePlayer; public class SomeExpansion extends PlaceholderExpansion { private final SomePlugin plugin; public SomeExpansion(SomePlugin plugin) { this.plugin = plugin; } @Override public String getAuthor() { return String.join(", ", plugin.getDescription().getAuthors()); } @Override public String getIdentifier() { return "example"; } @Override public String getVersion() { return plugin.getDescription().getVersion(); } // This override is required or PlaceholderAPI will unregister your expansion on /papi reload @Override public boolean persist() { return true; } @Override public String onRequest(OfflinePlayer player, String params) { if (params.equalsIgnoreCase("placeholder1")) { return plugin.getConfig().getString("placeholders.placeholder1", "default1"); } if (params.equalsIgnoreCase("placeholder2")) { return plugin.getConfig().getString("placeholders.placeholder2", "default2"); } return null; // Unknown Placeholder provided } } ```
> Please read the [`Common Parts` Section](#common-parts) for details on all the methods. Below is a full example of an external PlaceholderExpansion without any dependencies such as plugins. ```java package at.helpch.placeholderapi.example.expansion; import me.clip.placeholderapi.expansion.PlaceholderExpansion; import org.bukkit.OfflinePlayer; public class SomeExpansion extends PlaceholderExpansion { @Override public String getAuthor() { return "SomeAuthor"; } @Override public String getIdentifier() { return "example"; } @Override public String getVersion() { return "1.0.0"; } @Override public String onRequest(OfflinePlayer player, String params) { if (params.equalsIgnoreCase("player_name")) { // player_name requires a valid OfflinePlayer return player == null ? null : player.getName(); } if (params.equalsIgnoreCase("placeholder1")) { return "Placeholder Text 1"; } if (params.equalsIgnoreCase("placeholder2")) { return "Placeholder Text 2"; } return null; // Unknown Placeholder provided } } ```
> Please read the [`Common Parts` Section](#common-parts) for details on all the methods. The below example shows a possible setup of an external PlaceholderExpansion that depends on a Plugin to be present. ```java package at.helpch.placeholderapi.example.expansion; import at.helpch.placeholderapi.example.SomePlugin; import me.clip.placeholderapi.expansion.PlaceholderExpansion; import org.bukkit.OfflinePlayer; public class SomeExpansion extends PlaceholderExpansion { // This instance is assigned in canRegister() and can therefore not be final private SomePlugin plugin; @Override public String getAuthor() { return "SomeAuthor"; } @Override public String getIdentifier() { return "example"; } @Override public String getVersion() { return "1.0.0"; } // Allows us to define a plugin the expansion depends on @Override public String getRequiredPlugin() { return "SomePlugin"; } /* * This method needs to be overriden if your Expansion requires * a plugin or other dependency to be present to work. * * Returning false will cancel the Expansion registration. */ @Override public boolean canRegister() { /* * We do 2 things here: * 1. Check if the required plugin is present and enabled * 2. Obtain an instance of the plugin to use */ return (plugin = (SomePlugin) Bukkit.getPluginManager().getPlugin(getRequiredPlugin())) != null; } @Override public String onRequest(OfflinePlayer player, String params) { if (params.equalsIgnoreCase("placeholder1")) { return plugin.getConfig().getString("placeholders.placeholder1", "default1"); } if (params.equalsIgnoreCase("placeholder2")) { return plugin.getConfig().getString("placeholders.placeholder2", "default2"); } return null; // Unknown Placeholder provided } } ```
> Please read the [`Common Parts` Section](#common-parts) for details on all the methods. Below is a full example of using Relational Placeholders. For the sake of simplicity are we using parts of the [Internal Expansion Example](#making-an-internal-expansion) here and assume that the `SomePlugin` class offers a `areFriends(Player, Player)` method that returns a boolean value. ```java package at.helpch.placeholderapi.example.expansions; import at.helpch.placeholderapi.example.SomePlugin; import me.clip.placeholderapi.expansion.PlaceholderExpansion; import me.clip.placeholderapi.expansion.Relational; import org.bukkit.ChatColor; import org.bukkit.Player; public class SomeExpansion extends PlaceholderExpansion implements Relational { private final SomePlugin plugin; public SomeExpansion(SomePlugin plugin) { this.plugin = plugin; } @Override public String getAuthor() { return String.join(", ", plugin.getDescription().getAuthors()); } @Override public String getIdentifier() { return "example"; } @Override public String getVersion() { return plugin.getDescription().getVersion(); } // This override is required or PlaceholderAPI will unregister your expansion on /papi reload @Override public boolean persist() { return true; } @Override public String onPlaceholderRequest(Player one, Player two, String identifier) { if(one == null || two == null) return null; // We require both Players to be online if(params.equalsIgnoreCase("friend")) { if(plugin.areFriends(one, two)) { return ChatColor.GREEN + one.getName() + " and " + two.getName() + " are friends!"; } else { return ChatColor.GREEN + one.getName() + " and " + two.getName() + " are not friends!"; } } return null; // Placeholder is unknown by the Expansion } } ```