MVdWPlaceholderAPI 3.0.1

Add/Get placeholders to/from any MVdW Placeholder plugin at once

  1. Maximvdw
    [​IMG]
    THIS IS AN API FOR MY PREMIUM PLUGINS. IF YOU DO NOT OWN ANY OF MY PREMIUM PLUGINS THEN DO NOT USE THIS API

    YOU HAVE TO USE THE VERY LATEST VERSION OF MY PLUGINS.

    SUPPORT IS PROVIDED ON THE DISCUSSION THREADS OF THE PREMIUM PLUGINS

    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.

    [​IMG]
    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
    [​IMG]

    Imports

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

    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);
    [​IMG]
    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

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

    [​IMG]
    [​IMG]

    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")

    [​IMG]

    [​IMG]

    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

Recent Reviews

  1. Zed_Designs
    Zed_Designs
    5/5,
    Version: 3.0.1
    I don't understand how there are people who don't know how to use placeholders like the one below. XD
  2. jonnycp9
    jonnycp9
    1/5,
    Version: 3.0.1
  3. starwarsfreak219
    starwarsfreak219
    5/5,
    Version: 3.0.1
    Author released it, had a few bugs, fixed them same day. Author gives excellent support and I would recommend any of his plugins, they all run smoothly, and are very well optimized!
    1. Maximvdw
      Author's Response
      Thank you :)
  4. p82183645
    p82183645
    1/5,
    Version: 3.0.0
    Can't understand why you want to force this plugin
    This makes no sense
    And didn't help
    This plugin often breaks the server's papi
    1. Maximvdw
      Author's Response
      Reviews is not a place to ask for help. If you want help with your issue, please contact me. Support will not be provided in the reviews
  5. canhucko
    canhucko
    4/5,
    Version: 2.5.1
    I want to use MVdWplaceholderapi for savage factions placeholders. But it says put one of your plugins. But Savage factions is free. help me how can i use savagefactions placeholders
    1. Maximvdw
      Author's Response
      This is an API for my plugins - not for Savage factions. Savage factions basically links into my plugins using this API
  6. SebasG_
    SebasG_
    3/5,
    Version: 2.5.1
    help pls

    [WARNING] [MVdWPlaceholderAPI] There is no MVdW placeholder plugin installed!

    [WARNING] [MVdWPlaceholderAPI] Put one of Maximvdw's premium placeholder plugins in the server!
    1. Maximvdw
  7. jonnycp9
    jonnycp9
    3/5,
    Version: 2.5.1
    fix mvmplaceholder for plugin plotsquared build #178 (actually list don't work anymore with latest version of plotsquared) i have already contact your on pm
  8. Terrobility
    Terrobility
    5/5,
    Version: 2.5.1
    It's dead simple to create hooks for. One slight problem though... your pom.xml isn't correct! It makes builds fail :( You shouldn't depend on "spigot" but on "spigot-api". Also, version "1.9" is invalid - it should be "1.9-R0.1-SNAPSHOT" instead. Simply go onto GitHub and merge one of the PRs with the fix :)
  9. RAFAELESPADA
    RAFAELESPADA
    4/5,
    Version: 2.5.1
    Good plugin. But is difficult to plugin developers to implements they own plugin placeholders directly in this plugin. Better documentation and tutorials would be good
  10. Hoisting
    Hoisting
    5/5,
    Version: 2.5.1
    Great plugin, its a shame there are people like dexter78 with such a low iq. (spigot makes me type more)