PlaceholderAPI expansion tutorial

Oct 13, 2017
PlaceholderAPI expansion tutorial
  • [​IMG]
    PlaceholderAPI utilizes a .jar based module system which allows placeholders to be packaged in .a .jar file and loaded/enabled dynamically when the .jar for a specific set of placeholders is located within the /PlaceholderAPI/expansions/ folder. This system offers many benefits, including, but not limited to:
    • The core plugin of PlaceholderAPI is not dependent on any external resources aside from the Spigot API​
    • The end user can choose which expansions are loaded / enabled, reducing memory usage and/or bloat​
    • If any placeholders break, the entire plugin does not break or require an update​
    • It is easier for maintainability. Most placeholders depend on an external 3rd plugins to obtain data from. Sometimes those plugins update and cause the expansion or a placeholder to break. The developer of the expansion can update the single expansion to support the new plugin version.​
    • It is easier for a developer who wants to add new placeholders to contribute​
    • Updates be deployed and accessed in real time without restarting the server.​

    Want to share your expansions with the world of PlaceholderAPI users?
    Click here for info how


    How to create an expansion
    that does not have any extra dependencies

    If you want to create an expansion that does not require any other 3rd party dependencies for it to work, making an expansion is as simple as creating a new project, adding the spigot api and PlaceholderAPI.jar to your build path, then making a single class which extends PlaceholderExpansion. when this class compiled as a jar is added to the /plugins/PlaceholderAPI/expansions/ folder, it will be loaded when PlaceholderAPI handles registering all of the expansions it finds within that folder on startup or reload.

    Here is an example of an expansion that does not require any 3rd party dependency​
    Code (Java):
    package com.extendedclip.papi.expansion.example;

    import me.clip.placeholderapi.expansion.PlaceholderExpansion;

    import org.bukkit.entity.Player;

    /**
    * This class will automatically register as a placeholder expansion
    * when a jar including this class is added to the /plugins/placeholderapi/expansions/ folder
    *
    */

    public class ExampleExpansion extends PlaceholderExpansion {

        /**
         * This method should always return true unless we
         * have a dependency we need to make sure is on the server
         * for our placeholders to work!
         * This expansion does not require a dependency so we will always return true
         */

        @Override
        public boolean canRegister() {
            return true;
        }

        /**
         * The name of the person who created this expansion should go here
         */

        @Override
        public String getAuthor() {
            return "clip";
        }

        /**
         * The placeholder identifier should go here
         * This is what tells PlaceholderAPI to call our onPlaceholderRequest method to obtain
         * a value if a placeholder starts with our identifier.
         * This must be unique and can not contain % or _
         */

        @Override
        public String getIdentifier() {
            return "example";
        }

        /**
         * if an expansion requires another plugin as a dependency, the proper name of the dependency should
         * go here. Set this to null if your placeholders do not require another plugin be installed on the server
         * for them to work
         */

        @Override
        public String getPlugin() {
            return null;
        }

        /**
         * This is the version of this expansion
         */

        @Override
        public String getVersion() {
            return "1.0.0";
        }

        /**
         * This is the method called when a placeholder with our identifier is found and needs a value
         * We specify the value identifier in this method
         */

        @Override
        public String onPlaceholderRequest(Player p, String identifier) {

            // %example_placeholder1%
            if (identifier.equals("placeholder1")) {
                return "placeholder1 works";
            }
            // %example_placeholder2%
            if (identifier.equals("placeholder2")) {
                return "placeholder2 works";
            }

            return null;
        }
    }
    How to create an expansion that has a 3rd party dependency
    If you want to create an expansion that requires a 3rd party dependencie for it to work, making an expansion is as simple as creating a new project, adding the spigot api, PlaceholderAPI.jar, and dependency jar to your build path, then making a single class which extends PlaceholderExpansion. when this class compiled as a jar is added to the /plugins/PlaceholderAPI/expansions/ folder, it will be loaded.as long as the class is setup to require a dependency and that dependency was found on the server.

    Here is an example of an expansion that requires a 3rd party dependency​
    Code (Java):
    package com.extendedclip.papi.expansion.example;

    import me.clip.placeholderapi.PlaceholderAPI;
    import me.clip.placeholderapi.expansion.PlaceholderExpansion;

    import org.bukkit.Bukkit;
    import org.bukkit.entity.Player;

    /**
    * This class will automatically register as a placeholder expansion
    * when a jar including this class is added to the /plugins/placeholderapi/expansions/ folder
    *
    */

    public class ExampleExpansion extends PlaceholderExpansion {

        private SomePlugin plugin;
        /**
         * Since this expansion requires api access to the plugin "SomePlugin"
         * we must check if "SomePlugin" is on the server in this method
         */

        @Override
        public boolean canRegister() {
            return Bukkit.getPluginManager().getPlugin(getPlugin()) != null;
        }

        /**
         * We can optionally override this method if we need to initialize variables within this class if we need to
         * or even if we have to do other checks to ensure the hook is properly setup.
         */

        @Override
        public boolean register() {
            /*
             * Make sure "SomePlugin" is on the server
             */

            if (!canRegister()) {
                return false;
            }
     
            /*
             * "SomePlugin" does not have static methods to access its api so we must
             * create set a variable to obtain access to it
             */

            plugin = (SomePlugin) Bukkit.getPluginManager().getPlugin(getPlugin());
     
            /*
             * if for some reason we can not get our variable, we should return false
             */

            if (plugin == null) {
                return false;
            }
            /*
             * Since we override the register method, we need to manually
             * register this hook
             */

            return PlaceholderAPI.registerPlaceholderHook(getIdentifier(), this);
        }

        /**
         * The name of the person who created this expansion should go here
         */

        @Override
        public String getAuthor() {
            return "clip";
        }

        /**
         * The placeholder identifier should go here
         * This is what tells PlaceholderAPI to call our onPlaceholderRequest method to obtain
         * a value if a placeholder starts with our identifier.
         * This must be unique and can not contain % or _
         */

        @Override
        public String getIdentifier() {
            return "someplugin";
        }

        /**
         * if an expansion requires another plugin as a dependency, the proper name of the dependency should
         * go here. Set this to null if your placeholders do not require another plugin be installed on the server
         * for them to work. This is extremely important to set if you do have a dependency because
         * if your dependency is not loaded when this hook is registered, it will be added to a cache to be
         * registered when plugin: "getPlugin()" is enabled on the server.
         */

        @Override
        public String getPlugin() {
            return "SomePlugin";
        }

        /**
         * This is the version of this expansion
         */

        @Override
        public String getVersion() {
            return "1.0.0";
        }

        /**
         * This is the method called when a placeholder with our identifier is found and needs a value
         * We specify the value identifier in this method
         */

        @Override
        public String onPlaceholderRequest(Player p, String identifier) {

            if (p == null) {
                return "";
            }
            // %example_placeholder1%
            if (identifier.equals("placeholder1")) {
                return plugin.getConfig().getString("placeholder1", "value doesnt exist");
            }
            // %example_placeholder2%
            if (identifier.equals("placeholder2")) {
                return plugin.getConfig().getString("placeholder2", "value doesnt exist");
            }
     
            return null;
        }
    }
     
    That is pretty much all you need to get going. You can also do tons of more complex stuff with this but the key things are shown in the examples above.
  • Loading...
  • Loading...