Upstream
/
PlaceholderAPI
mirror of https://github.com/PlaceholderAPI/PlaceholderAPI.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Updated Hook into PlaceholderAPI (markdown)

Ryan 2019-05-07 15:48:42 -04:00
parent 23e86d24e7
commit 753ef7e464
1 changed files with 0 additions and 172 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

172
Hook-into-PlaceholderAPI.md

@ -94,178 +94,6 @@ depend: [PlaceholderAPI] # If your plugin requires PlaceholderAPI, to work, use
- 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|PlaceholderExpansion]]!
- The later mentioned `EZPlaceholderHook` is deprecated since the implementation of `PlaceholderExpansion`. Just use the method explained in the above-linked page.
### EZPlaceholderHook (Deprecated)
**Please consider using the [PlaceholderExpansion](#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:
```java
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.
```java
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!
```java
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.
```java
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.
```
## Using placeholders from PlaceholderAPI in your plugin
To use placeholders from other plugins in our own plugin, we simply have to use the `setPlaceholders` method.