Hooking into PlaceholderAPI

May 10, 2018
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.7</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);
        }
    }
     

    -------------------------------------------------------------------------------------------------------------------
    Using Placeholder Expansion to register Placeholder in your local Jar
    With the newly PlaceholderExpansion introduced and EZPlaceholderHook got deprecated recently, it is good to use it by now, this section is for the one who doesn't want to give the trouble of creating a seperate Jar for the plugin.
    For example, I will create a placeholder which shows the number of Player is online and the player name.

    First, just create the Main class like usual.
    Code (Java):
    package me.banbeucmas;

    import org.bukkit.Bukkit;
    import org.bukkit.plugin.java.JavaPlugin;

    public class ExpansionTutorial extends JavaPlugin {

        @Override
        public void onEnable(){
            if( Bukkit.getPluginManager().isPluginEnabled("PlaceholderAPI")){
                //Registering placeholder will be done here
            }
        }
    }
    Now, to create the expansion, all you need to do is creating a class that extends PlaceholderExpansion, you can look for more information here https://www.spigotmc.org/wiki/placeholderapi-expansion-tutorial/ . This will somewhat similar to EZPlaceholderHook

    Code (Java):
    package me.banbeucmas;

    import me.clip.placeholderapi.expansion.PlaceholderExpansion;
    import org.bukkit.Bukkit;
    import org.bukkit.entity.Player;

    public class TutorialPlaceholder extends PlaceholderExpansion {

        /*
        The identifier, shouldn't contain any _ or %
         */

        public String getIdentifier() {
            return "tutorial";
        }

        public String getPlugin() {
            return null;
        }


        /*
         The author of the Placeholder
         This cannot be null
         */

        public String getAuthor() {
            return "Banbeucmas";
        }

        /*
         Same with #getAuthor() but for versioon
         This cannot be null
         */


        public String getVersion() {
            return "SomeMagicalVersion";
        }

        /*
        Use this method to setup placeholders
        This is somewhat similar to EZPlaceholderhook
         */

        public String onPlaceholderRequest(Player player, String identifier) {
            /*
             %tutorial_onlines%
             Returns the number of online players
              */

            if(identifier.equalsIgnoreCase("onlines")){
                return String.valueOf(Bukkit.getOnlinePlayers().size());
            }
     
            /*
            Check if the player is online,
            You should do this before doing anything regarding players
             */

            if(player == null){
                return "";
            }
     
            /*
            %tutorial_name%
            Returns the player name
             */

            if(identifier.equalsIgnoreCase("name")){
                return player.getName();
            }
     
     
            return null;
        }
    }
     
    After that, the rest is easy, just register the PlaceholderExpansion and you are good to go.
    Code (Java):
    package me.banbeucmas;

    import org.bukkit.Bukkit;
    import org.bukkit.plugin.java.JavaPlugin;

    public class ExpansionTutorial extends JavaPlugin {

        @Override
        public void onEnable(){
            if( Bukkit.getPluginManager().isPluginEnabled("PlaceholderAPI")){
                //Registering placeholder will be use here
                new TutorialPlaceholder().register();
            }
        }
    }
     
  • Loading...
  • Loading...