PlaceholderAPI expansion tutorial

Sep 3, 2017
PlaceholderAPI expansion tutorial
  • [​IMG]
    Creating 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.

    Here is an example of an expansion that does not require any 3rd party dependency[/CENTER]
    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;
        }
    }
    Creating 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. If you ever want to expand your expansion, you can always check out the 2.2.0+ javadoc: here

    If you are releasing your expansion public here in the Spigot resources, feel free to use the plugin icon and header image created by @funnycube.

    icon: http://i.imgur.com/FpDf70T.png
    header image: http://i.imgur.com/V4Z8KYL.png

    Also if your expansion is public, be sure to add your placeholders to the placeholders list:
    https://www.spigotmc.org/wiki/placeholderapi-placeholders/

    If you wish to further publish your expansion to the PlaceholderAPI Cloud you can do so here,
    https://api.extendedclip.com/all/
  • Loading...
  • Loading...