MVdWPlaceholderAPI for Featherboard LATEST(2.3.1)

About the API
MVdW Placeholder API is an API that allows you to register placeholders to all my MVdW Placeholder plugins at once. It also has the ability to replace placeholders for your own plugin if any of my placeholder plugins is present giving you a large 5k+ and growing placeholder count.

Note that this plugin/API does not contain any placeholders itself. It is a bridge between all my placeholder plugins and custom or 3rd party plugins.


This plugin acts as an interfacing method between placeholders and my placeholder plugins.

In order to make my placeholders compatible will my various placeholder plugins this acts as a shared API between them.

Downloading and loading is still handled by the placeholder plugin. The MVdWPlaceholderAPI provides the required shared classes.

Requirements
- Java 7+
- Any MVdW Placeholder plugin (See above)

Usage for server owners

1. Make sure you have any MVdW Placeholder plugin
2. Place the plugin in your plugins folder
3. Start your server, if you have multiple MVdW placeholder plugins this plugin will say in the console what plugin it is using to get placeholder from. This is useful to know since the configuration of the placeholders is still done in that plugin.
4. If you have any plugins that hook into MVdWPlaceholderAPI it will show a message in the console for every placeholder that is being added.

API source and Maven repository

GitHub source
The API and inline documentation is available on github:
https://github.com/Maximvdw/MVdWPlaceholderAPI

The main classes you have to worry about are:
https://github.com/Maximvdw/MVdWPla...e/maximvdw/placeholderapi/PlaceholderAPI.java
https://github.com/Maximvdw/MVdWPla...w/placeholderapi/PlaceholderReplaceEvent.java
https://github.com/Maximvdw/MVdWPla...imvdw/placeholderapi/PlaceholderReplacer.java

Jenkins builds
To get custom versions or for development builds please use the Jenkins build server: http://ci.mvdw-software.be/job/MVdWPlaceholderAPI/


Maven repository
Maven is the easiest way to hook into the Placeholder API to easily get the latest version.

Repositories
HTML:

<repository>
<id>mvdw-software</id>
<name>MVdW Public Repositories</name>
<url>http://repo.mvdw-software.be/content/groups/public/</url>
</repository>

Dependencies
NOTE: Change the version depending on the latest version
HTML:

<dependency>
<groupId>be.maximvdw</groupId>
<artifactId>MVdWPlaceholderAPI</artifactId>
<version>2.1.1-SNAPSHOT</version>
</dependency>


API usage for developers
First thing you have to do is make sure you have a reference to the plugin. DO NOT SHADE or include the jar in your plugin.

Explaining the internals
The way this API works is that you can register an interface that will be executed when you want a specific placeholder to be replaced. Those interface references linked to specific placeholders are stored in the API itself.

When FeatherBoard or any other MVdW placeholder plugin animated or requests the replacement of placeholders the API is checked to see if there any placeholders matching the ones you have added. If this is the case the interface is fired with an event holding the player for who the placeholder is being replaced.

When your plugin requests the replacement of placeholders in the API the MVdW Plugin that hooked into the API first will be used to get placeholders from. Both the placeholders from the MVdW placeholder plugin and the custom placeholders you or someone else added will be replaced.

Hooking into the API
The first thing you should do is to hook in the API. You have to know that the API is present before trying to do something with it.

NOTE: In this example we are doing everything in the main class. It is advised to separate this

(Soft)depend
In your plugin.yml set the MVdWPlaceholderAPI as a soft or hard dependency


Imports

Code (Text):
import be.maximvdw.placeholderapi.PlaceholderAPI;
import be.maximvdw.placeholderapi.PlaceholderReplacer;
import be.maximvdw.placeholderapi.PlaceholderReplaceEvent;
Check if the plugin is present

Once we know the plugin present we can do things with it


Register a custom placeholder
Registering a custom placeholder that can be used in all MVdW Placeholder plugins.

Code (Text):
PlaceholderAPI.registerPlaceholder(Plugin plugin, String placeholder, PlaceholderReplacer replacer);

The registerPlaceholder method takes 3 arguments
plugin: The plugin that is registering the placeholders (yours)
placeholder: The placeholder without { } you are registering (lowercase)
replacer: The placeholder replacer interface instance


The event comes with the online player and the offline player depending on the condition of the placeholder. Do NULL checks yourself!




NOTE: Always cache if you are using MySQL or any type of database. These requests can be made multiple times a second and have to be returned as fast as possible.


Replacing placeholders
The plugin has the ability to replace placeholders using the first MVdW Placeholder plugin that hooked into the API (see topic "Usage for server admins")




Example 1
The above example can be found here:
https://github.com/Maximvdw/MVdWPlaceholderAPIExample
http://ci.mvdw-software.be/job/MVdWPlaceholderAPIExample/

License and usage
- Usage in free/public plugins is allowed if credit is given.
- Usage in premium plugins is also allowed if credit is given but the placeholders should not be your main selling point. Same applies for API plugins that act as an interface for multiplie placeholder cores
- I hold the rights on both the source code and binary form of this placeholder API.
- I hold the right to block placeholders or plugins adding placeholders if those are having a bad influence on the general performance such as no caching or very intensive tasks.
- It is requested to allow users to define (in a config) if they allow your plugin to add placeholders to the API (and in extend to the MVdW Placeholder plugins).
- Support is provided to Spigot users who bought one of my placeholder plugins. Having no bought plugin = no support