Hook into PlaceholderAPI
*The GitHub release may be different from the spigot release
This page is about using PlaceholderAPI in your own plugin, to either let other plugins use your plugin, or just use placeholders from other plugins in your own.
Please note, that the examples in this page are only available for PlaceholderAPI 2.0.6 or higher!
Before you can actually make use of PlaceholderAPI, you first have to import it into your project.
To import PlaceholderAPI, simply add the following code to your pom.xml
Replace {VERSION}
with the version listed at the top of this page.
<repositories>
<repository>
<id>placeholderapi</id>
<url>http://repo.extendedclip.com/content/repositories/placeholderapi/</url>
</repository>
</repositories>
<dependencies>
<dependency>
<groupId>me.clip</groupId>
<artifactId>placeholderapi</artifactId>
<version>{VERSION}</version>
<scope>provided</scope>
</dependency>
</dependencies>
Here is how you can import PlaceholderAPI through gradle.
Put this into your Gradle.build.
Replace {VERSION}
with the version listed at the top of this page.
repositories {
maven {
name = 'placeholderapi'
url = 'http://repo.extendedclip.com/content/repositories/placeholderapi/'
}
}
dependencies {
compile group: 'me.clip', project: 'placeholderapi', version: '{VERSION}'
}
Do the following steps, if you can't import PlaceholderAPI through Maven or Gradle.
Rightclick your project and choose "Properties -> Java Build Path".
Click on "Add external jar" and add the PlaceholderAPI.jar (Pluginpage) to your project.
- Click on File -> Project Structure (Ctrl + Alt + Shift + S on windows)
- Go to the tab Modules
- Click the + on the right side and choose Library... -> Java
- Select the PlaceholderAPI.jar
Next step is to go to your plugin.yml and add PlaceholderAPI as a depend or softdepend, depending (no pun intended) on if it is optional or not.
Example Softdepend:
name: ExamplePlugin
version: 1.0
author: author
main: your.main.path.here
softdepend: [PlaceholderAPI] # This is used, if your plugin works without PlaceholderAPI.
Example Depend:
name: ExamplePlugin
version: 1.0
author: author
main: your.main.path.here
depend: [PlaceholderAPI] # If your plugin requires PlaceholderAPI, to work, use this.
- If you are not including placeholders from within the dependency, you probably want to create a placeholder expansion. A guide on how to create placeholder expansions can be found here!
- The later mentioned
EZPlaceholderHook
is deprecated since the implementation ofPlaceholderExpansion
. Just use the method explained in the above-linked page.
Please consider using the PlaceholderExpansion instead of EZPlaceholderHook, since this method is deprecated and no longer supported!
In our example, we set PlaceholderAPI as a softdepend and won't register our placeholders, if the plugin isn't installed and enabled:
package at.helpch.placeholderapiexample;
import org.bukkit.Bukkit;
import org.bukkit.plugin.java.JavaPlugin;
public class ExamplePlugin extends JavaPlugin {
@Override
public void onEnable(){
if(Bukkit.getPluginManager().getPlugin("PlaceholderAPI") != null) {
// Your register-code here
}
}
}
There are multiple ways to register your own placeholders. The best (and also cleanest) way would be to make a separate class that extends the abstract PlaceholderHook
or EZPlaceholderHook
to handle it.
Note: These two abstract methods are basically the same, but EZPlaceholderHook
makes it easier for you to register your placeholders because it has a few methods built in to do the work in terms of registering.
Let's assume I made the class MyPlaceholderExtension
which extends EZPlaceholderHook
.
As soon as I did that, does it make a constructor for me and tells me, that I need to implement some methods that are missing.
This method will do the work for us when a value is needed.
In our example will we keep track of who's staff and how many staff are online.
In the main class did we made some event listeners, to determine if a player is a staff when he joins. If they are, add them to a set of player names of the staff online. On disconnect, we do the opposite and remove them from the set.
package at.helpch.placeholderapiexample;
import org.bukkit.Bukkit;
import org.bukkit.plugin.java.JavaPlugin;
import java.util.HashSet;
import java.util.Set;
public class ExamplePlugin extends JavaPlugin implements Listener {
// We make a Set, that stores the player names as String
private final Set<String> staff = new HashSet<>();
@Override
public void onEnable() {
/*
* We register the EventListeneres here.
* Since all events are in the main class (this class), we simply use "this"
*/
Bukkit.getPluginManager().registerEvents(this, this);
if(Bukkit.getPluginManager().getPlugin("PlaceholderAPI") != null) {
// Your register-code here
}
}
@EventListener
public void onJoin(PlayerJoinEvent event) {
if(event.getPlayer().hasPermission("exampleplugin.staff");
addStaff(event.getPlayer().getName());
}
}
@EventHandler
public void onQuit(PlayerQuitEvent event) {
if(isStaff(event.getPlayer().getName()) {
removeStaff(event.getPlayer().getName());
}
}
public boolean isStaff(String name) {
return staff.contains(name);
}
public boolean addStaff(String name) {
return staff.add(name);
}
public boolean removeStaff(String name) {
return staff.remove(name);
}
// We use this one here in the later example
public int getStaffCount() {
return staff.size();
}
}
Now we can set up the stuff in our placeholder-class to make it work!
package at.helpch.placeholderapiexample;
import org.bukkit.entity.Player;
import me.clip.placeholderapi.external.EZPlaceholderHook;
public class MyPlaceholderExtension extends EZPlaceholderHook {
// Getting our main class with the stuff here
private ExamplePlugin myPlugin;
public MyPlaceholderExtension(ExamplePlugin myPlugin) {
/*
* We register and associate our plugin with an identifier.
* The format for placeholders is this:
* %<identifier>_<anything you define below>%
* The placeholder identifier can be anything you want, as
* long as it isn't already registered by another plugin.
* It also can't contain % or _
*/
super(myPlugin, "exampleplugin");
// This is to access our main class below
this.myPlugin = myPlugin;
}
@Override
public String onPlaceholderRequest(Player player, String identifier) {
// Placeholder: %exampleplugin_staff_count%
if(identifier.equals("staff_count")) {
// Since we return a String, we have to convert it from the integer
return String.value(myPlugin.getStaffCount());
}
// We always check, if player is null for player-related placeholders.
if(player == null) {
return "";
}
// Placeholder: %exampleplugin_is_staff%
if(identifier.equals("is_staff")) {
// Syntax: return <check-value> ? <true> : <false>;
return myPlugin.isStaff(player.getName()) ? "yes" : "no";
}
// We return null if any other identifier was provided
return null;
}
}
And that's it! Now we only have to create an instance of the class we made and call the hook
method it provides.
package at.helpch.placeholderapiexample;
import org.bukkit.Bukkit;
import org.bukkit.plugin.java.JavaPlugin;
import java.util.HashSet;
import java.util.Set;
public class ExamplePlugin extends JavaPlugin {
// We make a Set, that stores the player names as String
private final Set<String> staff = new HashSet<>();
@Override
public void onEnable() {
/*
* We register the EventListeneres here.
* Since all events are in the main class (this class), we simply use "this"
*/
Bukkit.getPluginManager().registerEvents(this, this);
if(Bukkit.getPluginManager().getPlugin("PlaceholderAPI") != null) {
new MyPlaceholderExtension(this).hook();
}
}
// All the stuff we did previously.
To use placeholders from other plugins in our own plugin, we simply have to use the setPlaceholders
method.
Let's assume we want to send an own join message that shows the group a player has.
To achieve that, we can do the following:
package at.helpch.placeholderapi;
import me.clip.placeholderapi.PlaceholderAPI;
import org.bukkit.Bukkit;
import org.bukkit.event.EventHandler;
import org.bukkit.event.EventPriority;
import org.bukkit.event.Listener;
import org.bukkit.event.player.PlayerJoinEvent;
import org.bukkit.plugin.java.JavaPlugin;
import me.clip.placeholderapi.PlaceholderAPI;
public class JoinExample extends JavaPlugin implements Listener {
@Override
public void onEnable() {
if (Bukkit.getPluginManager().getPlugin("PlaceholderAPI") != null) {
/*
* We register the EventListeneres here, when PlaceholderAPI is installed.
* Since all events are in the main class (this class), we simply use "this"
*/
Bukkit.getPluginManager().registerEvents(this, this);
} else {
throw new RuntimeException("Could not find PlaceholderAPI!! Plugin can not work without it!");
}
}
@EventHandler(priority = EventPriority.HIGHEST)
public void onJoin(PlayerJoinEvent event) {
String joinText = "%player_name% &ajoined the server! He/she is rank &f%vault_rank%";
// We parse the placeholders using "setPlaceholders"
joinText = PlaceholderAPI.setPlaceholders(event.getPlayer(), joinText);
event.setJoinMessage(withPlaceholdersSet);
}
}
© 2015 - 2024 PlaceholderAPI Team
Thanks for using PlaceholderAPI.Plugin-page | Placeholders | Plugins using PlaceholderAPI | Hook into PlaceholderAPI