This tutorial attempts to guide you through adding a DataExtension to your plugin, for more in-depth documentation about different parts of the API, see DataExtension API.

These icons are used to aid understanding

💭 Question about possible issues (Someone has had these before)
💡 Extra stuff

✔️ Requirements

A java plugin project for a minecraft server

🚩 Tutorial Goals

Here are the goals the tutorial aims to guide you through.
At the end of this tutorial you will have

.. Added Plan API as a dependency to your project
- (.. added Plan as soft-dependency to your plugin)
.. Created 2 new classes to use the API
.. Created 1 new test class to test use of the API
.. Defined a DataExtension that adds a number to a player's page

💭 What is this API for?

DataExtension API is for displaying data from a plugin on the Plan website.

Goal #1: Adding Plan API as a dependency

1.1: Add Plan repository to your project

Maven

Add the repository to your <repositories>-block in pom.xml of your project

<repository>
    <id>jitpack</id>
    <url>https://jitpack.io</url>
</repository>

Gradle

Add the repository to your repositories-block in build.gradle of your project

maven {
    url  "https://jitpack.io" 
}

Other build tools

Add Plan API as a dependency in your build tool. (you can download it from here https://github.com/plan-player-analytics/Plan/releases)

1.2: Add Plan API as a dependency

Go to https://github.com/plan-player-analytics/Plan/tags and see what is the latest version number. No need to download anything.

Maven

Add Plan API as a dependency to your <dependencies>-block in in pom.xml of your project

<dependency>
  <groupId>com.github.plan-player-analytics</groupId>
  <artifactId>Plan</artifactId>
  <version>{jitpack version}</version> <!-- Add the version number here -->
  <scope>provided</scope>
</dependency>

Gradle

Add Plan API as a compile & test compile time dependency to your dependencies-block in build.gradle of your project.

compileOnly 'com.github.plan-player-analytics:Plan:{jitpack version}'
testCompileOnly 'com.github.plan-player-analytics:Plan:{jitpack version}'

Other

Add Plan as a dependency in your build tool. (you can download it from here https://github.com/plan-player-analytics/Plan/releases)

1.3: Add Plan as a soft-dependency in your plugin

Spigot, Nukkit & Bungeecord (plugin.yml)

Add Plan in softdepend in plugin.yml of your project

softdepend:
- Plan
# nukkit
softdepend: ["Plan"]
# bungee
softDepends:
- Plan

Sponge & Velocity (Plugin annotation)

Add Plan as an optional dependency to the @Plugin annotation

@Plugin(
        id = ...,
        dependencies = {
                @Dependency(id = "plan", optional = true)
        }
)

✔️ Your project now includes Plan API as a dependency!

Goal #2: Access Plan API from your plugin

2.1: Create a class to separate Plan imports from your main class

In order to keep Plan as an optional dependency, all access to the Plan API should be made from a separate class. In this tutorial this will be called PlanHook, but you can call it whatever you want.

Let's take a look at this example class:

import com.djrapitops.plan.capability.CapabilityService;
import com.djrapitops.plan.extension.ExtensionService;

public class PlanHook {
    private final MyPluginDatabase database; // Replace with whatever you use to store your plugin's data
    
    public PlanHook(MyPluginDatabase database) {
        this.database = database;
    }

    public void hookIntoPlan() {
        if (!areAllCapabilitiesAvailable()) return;
        registerDataExtension();
        listenForPlanReloads();
    }

    private boolean areAllCapabilitiesAvailable() {
        CapabilityService capabilities = CapabilityService.getInstance();
        return capabilities.hasCapability("DATA_EXTENSION_VALUES");
    }

    private void registerDataExtension() {
        try {
            ExtensionService.getInstance().register(new MyPluginDataExtension(database));
        } catch (IllegalStateException planIsNotEnabled) {
            // Plan is not enabled, handle exception
        } catch (IllegalArgumentException dataExtensionImplementationIsInvalid) {
            // The DataExtension implementation has an implementation error, handle exception
        }
    }

    private void listenForPlanReloads() {
        CapabilityService.getInstance().registerEnableListener(
            isPlanEnabled -> {
                // Register DataExtension again
                if (isPlanEnabled) registerDataExtension();
            }
        )
    }
}

Creating a separate class is necessary to keep NoClassDefFoundError away from loading your plugin when Plan is not enabled!

Here is some more explanation for each section of the code in case you need more information.

Construction

    private final MyPluginDatabase database; // Replace with whatever you use to store your plugin's data
    
    public PlanHook(MyPluginDatabase database) {
        this.database = database;
    }

MyPluginDatabase is the database of the example plugin, and is given so that the DataExtension has some data to display later.

hookIntoPlan()

    public void hookIntoPlan() {
        if (!areAllCapabilitiesAvailable()) return;
        registerDataExtension();
        listenForPlanReloads();
    }

This method checks if Plan has the capabilities you need, the check is similar to how some plugins ask you to check the version number.
If the capabilities are available, the extension is registered.
Additionally a listener for Plan reloads is registered to re-register the data extension.

areAllCapabilitiesAvailable()

    private boolean areAllCapabilitiesAvailable() {
        CapabilityService capabilities = CapabilityService.getInstance();
        return capabilities.hasCapability("DATA_EXTENSION_VALUES");
    }

Checks that DATA_EXTENSION_VALUES capability is available. Some features might need more capabilities, and when they do it is mentioned in the documentation. Those capabilities can then be added here.

registerDataExtension()

    private void registerDataExtension() {
        try {
            ExtensionService.getInstance().register(new MyPluginDataExtension(database));
        } catch (IllegalStateException planIsNotEnabled) {
            // Plan is not enabled, handle exception
        } catch (IllegalArgumentException dataExtensionImplementationIsInvalid) {
            // The DataExtension implementation has an implementation error, handle exception
        }
    }

Creates MyPluginDataExtension with the database of the plugin, and registers it to Plan
IllegalStateException might be thrown if Plan has not enabled properly
IllegalArgumentException might be thrown if the MyPluginDataExtension has an implementation error. Later a test class is created to avoid this issue.

listenForPlanReloads()

    private void listenForPlanReloads() {
        CapabilityService.getInstance().registerEnableListener(
            isPlanEnabled -> {
                // Register DataExtension again
                if (isPlanEnabled) registerDataExtension();
            }
        )
    }

Registers a listener to Plan that registers the extension again in case Plan is reloaded.

2.2: Construct and call the PlanHook in your plugin enable.

In this example the Spigot JavaPlugin#onEnable is used, but you can add these methods to wherever you wish, as long as it is called after Plan has been loaded & enabled.

💭 When does Plan enable?

Spigot & Nukkit: After dependencies have enabled & worlds have been loaded

Sponge: After dependencies on GameStartedServerEvent

BungeeCord: After dependencies

Velocity: After dependencies on ProxyInitializeEvent

MyPluginDatabase database; // Replace with whatever you use to store your plugin's data

public void onEnable() {
    ... // The example plugin enables itself
    
    try {
        new PlanHook(database).hookIntoPlan();
    } catch (NoClassDefFoundError planIsNotInstalled) {
        // Plan is not installed
    }
}

✔️ You can now access Plan API from somewhere!

Goal #3: Creating a DataExtension

You might have noticed that there was a MyPluginDataExtension in the previous section, this is what is going to be implemented next.

3.1: Create your DataExtension class

Let's look at this example class:

@PluginInfo(
    name = "MyPlugin", 
    iconName = "vial", 
    iconFamily = Family.SOLID, 
    color = Color.LIGHT_BLUE
)
public class MyPluginDataExtension implements DataExtension {

    private final MyPluginDatabase database; // Replace with whatever you use to store your plugin's data

    public MyPluginDataExtension(MyPluginDatabase database) {
        this.database = database;
    }

    @Override
    public CallEvents[] callExtensionMethodsOn() {
        return new CallEvents[]{
                CallEvents.PLAYER_JOIN,
                CallEvents.PLAYER_LEAVE
        };
    }

    @NumberProvider(
            text = "Completed Challenges",
            description = "How many challenges has the player completed",
            iconName = "bookmark",
            iconColor = Color.GREEN,
            priority = 100,
            showInPlayerTable = true
    )
    public long challengesCompleted(UUID playerUUID) {
        return database.getCompletedChallengeCount(playerUUID);
    }

}

Individual sections explained:

PluginInfo annotation

@PluginInfo(
    name = "MyPlugin", 
    iconName = "vial", 
    iconFamily = Family.SOLID, 
    color = Color.LIGHT_BLUE
)
public class MyPluginDataExtension implements DataExtension {...}

PluginInfo annotation provides meta-data to Plan on how to display your plugin on the page.
It is a class annotation, the class needs to implement DataExtension
Documentation (middle-click to open to new tab)

Construction

    private final MyPluginDatabase database; // Replace with whatever you use to store your plugin's data
    
    public MyPluginDataExtension(MyPluginDatabase database) {
        this.database = database;
    }

MyPluginDatabase is the database of the example plugin, and is given so that the DataExtension has some data to display.

Overriding callExtensionMethodsOn

    @Override
    public CallEvents[] callExtensionMethodsOn() {
        return new CallEvents[]{
                CallEvents.PLAYER_JOIN,
                CallEvents.PLAYER_LEAVE
        };
    }

This method determines when Plan calls the Provider methods you declare in your DataExtension. You might need to change this depending on what kind of methods you put in. Forcing updates is also possible.
Documentation (controlling when Plan calls your DataExtension methods) (middle-click to open to new tab)

NumberProvider and challengesCompleted method

    @NumberProvider(
            text = "Completed Challenges",
            description = "How many challenges has the player completed",
            iconName = "bookmark",
            iconColor = Color.GREEN,
            priority = 100,
            showInPlayerTable = true
    )
    public long challengesCompleted(UUID playerUUID) {
        return database.getCompletedChallengeCount(playerUUID);
    }

Provider annotations give meta-data to Plan on how to display the data you are about to give, such as name, description, where to show it on the page etc.
Each provider annotation needs specific return type, NumberProvider requires long to be returned.
The method parameters determine if the method is a "Player method" or "Server method", in this case UUID -> This is a player method
Documentation for NumberProvider (middle-click to open to new tab)
Documentation for all Provider annotations (middle-click to open to new tab)

✔️ You now have a DataExtension!

Goal #4: Test your DataExtension implementation

Place a test method to a test class.

@Test
public void noImplementationErrors() {
    DataExtension yourExtension = new MyPluginExtension();

    // Throws IllegalArgumentException if there is an implementation error or warning.
    new ExtensionExtractor(yourExtension).validateAnnotations();
}

✔️ Less errors at runtime!

There is still a lot of additional annotations to further control the meta-data and for different kinds of data. I'll list some here for you to check out from the DataExtension API documentation

Providers
- BooleanProvider: Yes/No answers and possibility for conditional data
- NumberProvider: Numbers, time amounts and dates.
- DoubleProvider: Floating point numbers
- PercentageProvider: Percentages between 0% and 100%
- StringProvider: Strings and player names that link to the player's page
- GroupProvider: Names of different groups the player belongs in, eg. Permission groups
- TableProvider: Data for displaying a table
Extra annotations
- Tab, TabInfo and TabOrder: Place provided data to different sections on the page (For cases like where your plugin provides lots of different kinds of data, such as an Essentials or punishment plugin)
- Conditional: Controls conditional execution of the provider method
- InvalidateMethod: If you remove a extension method later this annotation is used to remove the old data

DataExtension API - Getting started

✔️ Requirements

🚩 Tutorial Goals

Goal #1: Adding Plan API as a dependency

1.1: Add Plan repository to your project

Maven

Gradle

Other build tools

1.2: Add Plan API as a dependency

Maven

Gradle

Other

1.3: Add Plan as a soft-dependency in your plugin

Spigot, Nukkit & Bungeecord (plugin.yml)

Sponge & Velocity (Plugin annotation)

Goal #2: Access Plan API from your plugin

2.1: Create a class to separate Plan imports from your main class

2.2: Construct and call the PlanHook in your plugin enable.

Goal #3: Creating a DataExtension

3.1: Create your DataExtension class

Goal #4: Test your DataExtension implementation

Documentation

Tutorials

Configuration

Customization

How-to's