How to work with Placeholders

Welcome to BearCommands Wiki!
Before we begin, this section will only work with the Bukkit part of the plugin and with the plugin PlaceholderAPI.
BearCommands allows to easily work with and maintain Placeholders in your project.

Contents
Placeholder Class
Implement placeholders
PlaceholderAPI required

Placeholder

To start working with placeholders, you will have to use the Placeholder class. This class offers a pletora of constructors to fulfill any of your needs. The most basic one is:

public Placeholder(String identifier, Function<Player, String> value, BiFunction<Player, String, String> subPlaceholdersHandler);

Let's go through the parameters:

• String identifier: the current identifier of the placeholder;
• Function<Player, String> value: the value to return when the placeholder is called;
• BiFunction<Player, String, String> subPlaceholdersHandler: the subplaceholders that the main one supports.

As you might tell, these parameters are not really user-friendly, but they can be simplified.
In particular:

• Function<Player, String> value can be replaced with String value if the value is constant, known or external to the player;
• BiFunction<Player, String, String> subPlaceholdersHandler can be replaced with an array of Placeholder that will automatically be handled.

Keeping these changes in mind, some of the constructors are:

public Placeholder(String identifier, String value, Placeholder... subPlaceholders);

public Placeholder(String identifier, Function<Player, String> value, Placeholder... subPlaceholders);

To better understand this, let's make an example:
Suppose you want to implement two placeholders: %testplugin_test% and %testplugin_test_nested%.
First thing first, you should not specify the plugin name, as this will always be added for you. Therefore, you can start by creating the first placeholder, which is the subplaceholder:

/* ... */
Placeholder subPlaceholder = new Placeholder("nested", "This is the nested placeholder");
/* ... */

Then, you proceed to create the main one by also adding the nested placeholder:

/* ... */
Placeholder placeholder = new Placeholder("test", "This is the main placeholder", subPlaceholder);
/* ... */

That's it!

Implement Placeholders

Now that we have covered the Placeholder class we can check how to use them in our plugin. We are assuming that you followed the How to start a plugin guide and you are working with a plugin main class that extends BearPlugin.
You can simply add your newly created placeholders using the addPlaceholder() method:

package it.fulminazzo.testplugin;

import it.angrybear.Bukkit.Objects.Placeholder;
import it.angrybear.Bukkit.SimpleBearPlugin;

public class TestPlugin extends SimpleBearPlugin {

    @Override
    public void onEnable() {
        Placeholder subPlaceholder = new Placeholder("nested", "This is the nested placeholder");
        Placeholder placeholder = new Placeholder("test", "This is the main placeholder", subPlaceholder);
        addPlaceholder(placeholder);
        super.onEnable();
    }
}

You can also create placeholders on the fly using the same method:

/* ... */
@Override
public void onEnable() {
    addPlaceholder(new Placeholder("test", "This is the main placeholder",
                    new Placeholder("nested", "This is the nested placeholder")));
    super.onEnable();
}
/* ... */

But do keep in mind that you must add placeholders before calling the super.onEnable() method.

PlaceholderAPI required

By default, BearCommands makes sure to check if the user has provided PlaceholderAPI among the list of plugins and, if it hasn't, prevent the loading of placeholders (that would return in an error). However, according to your needs, you might want to use it as a depend rather than a softdepend. While this could be easily done using the plugin.yml syntax, it is not visually appealing. You can instead specify PlaceholderAPI in your softdepend and set placeholderApiRequired to false in your plugin:

/* ... */
@Override
public void onEnable() {
    setPlaceholderApiRequired(true);
    super.onEnable();
}
/* ... */

This will prevent the plugin from loading if PlaceholderAPI has not been enabled.