Hooking into PlaceholderAPI

Oct 7, 2017
Hooking into PlaceholderAPI
  • [​IMG]

    So you want to show stats or information from your plugin in other plugins that obtain placeholder information from PlaceholderAPI?

    Here is a guide on how to do it!

    NOTE: This guide uses API methods and classes only available in PlaceholderAPI 2.0.6 or higher!

    If you use maven, you will need to add the dependency information for PlaceholderAPI to your pom.xml:
    Code (XML):

        <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>2.8.2</version>
             <scope>provided</scope>
            </dependency>
        </dependencies>
     
    If you are not using maven, you will simply add the PlaceholderAPI.jar to your buildpath:
    Eclipse example:

    [​IMG]
    Now that we have our dependency imported in our project, we need to open the plugin.yml and add the "depend" or "softdepend" entry so the server knows that our plugin depends on PlaceholderAPI:
    [​IMG]

    -------------------------------------------------------------------------------------------------------------------
    Adding placeholders from your plugin to PlaceholderAPI

    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:
    https://www.spigotmc.org/wiki/placeholderapi-expansion-tutorial/


    This guide will show you how to register your own placeholders from your plugin which can be used in any plugin that obtains placeholders from PlaceholderAPI.

    See the guide below on how to obtain placeholders to use them in your plugin.

    So our plugin is going to soft depend on PlaceholderAPI. If PlaceholderAPI is not found,
    we will simply ignore adding our custom placeholders.
    [​IMG]

    Now, there are many ways to register a hook to add your own placeholders. I find it cleaner and easier to create a separate class which extends the abstract class PlaceholderHook or EZPlaceholderHook.

    These 2 abstract classes are essentially the same but the "EZ"PlaceholderHook just makes things easier for you as it has a few methods built in to do the work for you when it comes to registering the placeholders. :)
    [​IMG]

    So I have made a class named "OurCoolPlaceholders" which extends "EZPlaceholderHook".
    As soon as I did that, it make me create a constructor and it also told me that I need to add an
    unimplemented method which does the work for us when a placeholder value is needed.

    So in our plugin, we will keep track of who is staff and the amount of staff online.
    In our main class I have made a few event listeners so we can determine if a player is staff on join, if they are, add them to a set of player names of the staff online. On quit, we remove them from the set of online staff names.
    [​IMG]

    Now we have some stats we can make placeholders for!!!
    So lets go back and finish our placeholder class.
    [​IMG]
    Code (Java):

    package com.extendedclip.exampleplaceholderplugin;

    import org.bukkit.entity.Player;

    import me.clip.placeholderapi.external.EZPlaceholderHook;

    public class OurCoolPlaceholders extends EZPlaceholderHook {

        private ExamplePlugin ourPlugin;

        public OurCoolPlaceholders(ExamplePlugin ourPlugin) {
            // this is the plugin that is registering the placeholder and the identifier for our placeholder.
            // the format for placeholders is this:
            // %<placeholder identifier>_<anything you define as an identifier in your method below>%
            // the placeholder identifier can be anything you want as long as it is not already taken by another
            // registered placeholder.
            super(ourPlugin, "customplaceholder");
            // this is so we can access our main class below
            this.ourPlugin = ourPlugin;
        }

        @Override
        public String onPlaceholderRequest(Player p, String identifier) {
            // placeholder: %customplaceholder_staff_count%
            if (identifier.equals("staff_count")) {
                return String.valueOf(ourPlugin.getStaffCount());
            }
            // always check if the player is null for placeholders related to the player!
            if (p == null) {
                return "";
            }
            // placeholder: %customplaceholder_is_staff%
            if (identifier.equals("is_staff")) {
                return ourPlugin.isStaff(p.getName()) ? "yes" : "no";
            }
            // anything else someone types is invalid because we never defined %customplaceholder_<what they want a value for>%
            // we can just return null so the placeholder they specified is not replaced.
            return null;
        }
    }

    So there we go. Now all we need to do is create an instance of this class we made and call the "hook" method it provides :)
    [​IMG]

    -------------------------------------------------------------------------------------------------------------------

    Using placeholders from PlaceholderAPI in your plugin.

    So in our plugin we want to use placeholders in, we are going to announce the player name and rank when they join for the example. Using PlaceholderAPI in your plugin to obtain placeholders is very easy so there shouldn't be much to explain...
    [​IMG]
    Code (Java):
    package com.extendedclip.exampleplaceholderplugin;

    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;

    public class ExamplePlugin extends JavaPlugin implements Listener {

        @Override
        public void onEnable() {
     
            if (Bukkit.getPluginManager().isPluginEnabled("PlaceholderAPI")) {
         
                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 withoutPlaceholdersSet = "%player_name% &ajoined the server! He/she is rank &f%vault_rank%";
     
            String withPlaceholdersSet = PlaceholderAPI.setPlaceholders(event.getPlayer(), withoutPlaceholdersSet);
     
            event.setJoinMessage(withPlaceholdersSet);
        }
    }
     
  • Loading...
  • Loading...