Upstream/Plan
1
0
Fork 0
mirror of https://github.com/plan-player-analytics/Plan.git synced 2024-09-10 05:48:13 +02:00
Code Issues Projects Releases Wiki Activity

Update API.md

Browse Source
This commit is contained in:
Rsl1122 2017-05-24 13:34:01 +03:00 committed by GitHub
parent 426f126b4b
commit 8df6f349b1
1 changed files with 100 additions and 92 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

192
documentation/API.md
View File

@ -4,12 +4,25 @@
- [API class](/Plan/src/main/java/com/djrapitops/plan/api/API.java) - [API class](/Plan/src/main/java/com/djrapitops/plan/api/API.java)
- [API Javadocs](https://rsl1122.github.io/Plan-PlayerAnalytics/main/java/com/djrapitops/plan/api/API.html) - [API Javadocs](https://rsl1122.github.io/Plan-PlayerAnalytics/main/java/com/djrapitops/plan/api/API.html)
Accessing the API Methods: ## Accessing the API Methods:
Install the Plan.jar as a local dependency if you're using Maven.
Add soft-depend or depend in the plugin.yml
``` ```
API planAPI = Plan.getPlanAPI(); // Throws IllegalStateException if onEnable() method for Plan has not yet been called. import main.java.com.djrapitops.plan.api.API;
if (getPluginManager().isPluginEnabled("Plan")) {
try {
// Throws IllegalStateException if onEnable() method for Plan has not yet been called.
// Throws NoClassDefError if Plan is not installed
API planAPI = Plan.getPlanAPI();
} catch (Throwable e) {
// Do something (Plan is not installed)
}
}
``` ```
# Basics # Plugins Tab
- [PluginData](/Plan/src/main/java/com/djrapitops/plan/data/additional/PluginData.java) - [PluginData](/Plan/src/main/java/com/djrapitops/plan/data/additional/PluginData.java)
- [PluginData Javadoc](https://rsl1122.github.io/Plan-PlayerAnalytics/main/java/com/djrapitops/plan/data/additional/PluginData.html) - [PluginData Javadoc](https://rsl1122.github.io/Plan-PlayerAnalytics/main/java/com/djrapitops/plan/data/additional/PluginData.html)
@ -21,16 +34,78 @@ API planAPI = Plan.getPlanAPI(); // Throws IllegalStateException if onEnable() m
Plan has a flexible data addition system since 3.1.0. With it you can add Averages, Totals, Percentages, Tables & Other Html elements to the Plugins tab on the Analysis and/or Inspect pages. Plan has a flexible data addition system since 3.1.0. With it you can add Averages, Totals, Percentages, Tables & Other Html elements to the Plugins tab on the Analysis and/or Inspect pages.
To add data a class that extends PluginData class is needed. One PluginData object should only contain data for one user, but tables & other elements are an exception. To add data **a class that extends PluginData class is needed.**
One PluginData object should only contain data for one user, but tables & other elements are an exception.
Examples: ### Registering the data point
```
PluginData yourPluginDataObject = new YourClassThatExtendsPluginData();
Plan.getPlanAPI().addPluginDataSource(yourPluginDataObject);
```
**If you register multiple data sources, they will appear in the order they were registered.**
## Building the PluginData object
### Super Constructors
Constructor determines if the datapoint can be analyzed or not & how it should be analyzed.
The Inspect page visibility can be changed with another method call.
Constructor | Parameters | Description
-- | -- | --
super(pluginName, placeholder) | Name of the plugin & the placeholder, eg: "stepsTaken" | This datapoint will be only shown on the Inspect page
super(pluginName, placeholder, AnalysisType.INT_TOTAL) | Type is determined by return value of getValue(UUID)-method | This datapoint will be shown on the Analysis page with total for all Players
super(pluginName, plaheholder, AnalysisType.INT_AVG, AnalysisType.INT_TOTAL) | The constructor takes as many AnalysisTypes as needed. | This datapoint will be shown on the Analysis page with the total and average for all Players
### Method calls in the contructor
There are multiple methods that change the appearance of the PluginData object on the webpage:
Method | Description
-- | --
super.analysisOnly(boolean) | Determine whether or not the datapoint should be only shown on the Analysis page, Set to false to show it on the Inspect page as well.
super.setPrefix(String) | For example: super.setPrefix("Steps taken: "), determines the prefix
super.setSuffix(String) | For example: super.setSuffix(" steps"), determines the suffix.
super.setIcon(String) | Set the font awesome icon name: [Font Awesome Icons](http://fontawesome.io/icons/)
To not show the datapoint on Analysis page, do not give the constructor any AnalysisType variables.
### getHtmlReplaceValue(String modifier, UUID uuid)-method
This method is used by Inspect page & by Analysis Page when AnalysisType.HTML is specified.
**It should use the parseContainer(String modifier, String value) method when returning a value.**
The Prefix, Suffix & Icon are added to the value automatically when using the parseContainer(String modifier, String value)-method.
Example:
```
@Override
public String getHtmlReplaceValue(String modifier, UUID uuid) {
return parseContainer(modifier, stepCounter.getSteps(uuid)+"");
}
```
UUID is the UUID of the player whose Inspect page is displayed OR Random UUID on Analysispage when AnalysisType.HTML is specified
### getValue(UUID uuid)-method
This method is used by Analysis when calculating Totals & Averages for each PluginData object.
The return type is Serializable, so Integer, Double, Long, Boolean & String can be returned.
What type you return determines what AnalýsisType you should use in the super constructor.
**-1** should be returned if the player has no value / Your plugin has no data on the player
If -1 is returned, the value is ignored when calculating Averages & Totals.
**Wrong AnalysisType will cause an exception during calculation** - It is caught per AnalysisType, so test your plugin with /plan analyze.
# Examples:
- Basic Example - Basic Example
- Inspect Example
- Analysis Example - Analysis Example
- Table Example - Table Example
## Basic Example ## Basic Example
This class will show "Steps Taken" on the Inspect page.
``` ```
public class StepCounterSteps extends PluginData { public class StepCounterSteps extends PluginData {
@ -42,125 +117,58 @@ public class StepCounterSteps extends PluginData {
// A call to super constructor: PluginName, PlaceholderName // A call to super constructor: PluginName, PlaceholderName
super("StepCounter", "stepsTaken"); super("StepCounter", "stepsTaken");
super.setPrefix("Steps taken: ")
super.setSuffix(" steps");
super.setIcon("wheelchair");
this.stepCounter = stepCounter; // Setting the plugin this.stepCounter = stepCounter; // Setting the plugin
// Registering to the API, this can be done outside the class as well.
API api = Plan.getPlanAPI();
if (api.isEnabled()) {
api.addPluginDataSource(this);
}
} }
// Required method. // Required method.
// This method is used with AnalysisType.HTML and for Inspect page's values. // This method is used with AnalysisType.HTML and for Inspect page's values.
// All return values should use parseContainer(String modifier, String value)-method, more on that down below. // All return values should use parseContainer(String modifier, String value)-method, more on that down below.
@Override @Override
public String getHtmlReplaceValue(String modifier, UUID uuid) { public String getHtmlReplaceValue(String modifier, UUID uuid) {
return parseContainer(modifier, stepCounter.getSteps(uuid)+""); return parseContainer(modifier, stepCounter.getSteps(uuid)+"");
} }
// Required method. // Required method.
// This method is used to calculate values for the Analysis page. // This method is used to calculate values for the Analysis page.
@Override @Override
public Serializable getValue(UUID uuid) { public Serializable getValue(UUID uuid) {
return stepCounter.getSteps(uuid); return stepCounter.getSteps(uuid);
} }
} }
``` ```
**At the moment registering this data source will have Only show up on Inspect page.** It is disregarded on analysis page. Two variables inside PluginData determine what should be done with the datapoint:
- List<AnalysisType> analysisTypes
- boolean analysisOnly
- analysisOnly is 'true' by default. - Inspect page will ignore the data.
- analysisOnly is set to 'false' automatically when using the super constructor without AnalysisType parameters.
- analysisTypes is empty. - Thus Analysis page will ignore the data.
## Registering the data point
This might be the easiest step.
get the API and call a single method - all done!
```
Plan.getPlanAPI().addPluginDataSource(new StepCounterSteps(stepCounter));
```
**If you register multiple data sources, they will appear in the order they were registered.**
## Inspect Example
We can add the data to the Inspect page with `super.setAnalysisOnly(false);`-call inside the constructor:
```
public StepCounterSteps(StepCounterPlugin stepCounter) {
super("StepCounter", "stepsTaken");
super.setAnalysisOnly(false); //
this.stepCounter = stepCounter;
}
```
Now on the inspect page, there will be a "StepCounter" plugin box. Inside the box, however **is only a single number**
This is because no prefix has been set.
Let's do that:
```
public StepCounterSteps(StepCounterPlugin stepCounter) {
super("StepCounter", "stepsTaken");
super.setPrefix("Steps taken: ")
//super.setSuffix(" steps"); // You can also define the suffix
super.setAnalysisOnly(false);
this.stepCounter = stepCounter;
}
```
Why should parseContainer(String modifier, String value)-method be used with getHtmlReplaceValue-method?
- Automatically add `<div class="plugin-data"></div>` wrap around the text.
- Automatically add the prefix, suffix & icon to the value.
Wait, icons?
[Font Awesome Icons](http://fontawesome.io/icons/) can be used. They are added before the prefix when parseContainer method is called.
To set the icon call `super.setIcon(iconName)` in the constructor. Icon-names are visible on the linked page.
```
super.setIcon("wheelchair");
```
## Analysis Example ## Analysis Example
Adding data to the Analysis page is straightforward as well. Please note that one class can add a data to both Analysis & Inspect pages. Adding data to the Analysis page is straightforward as well. Please note that one class can add a data to both Analysis & Inspect pages.
To add data to the Analysis page, analysisTypes need to be set. To add data to the Analysis page, analysisTypes need to be set.
This is done in the super constructor. There are three ways to set them: This is done in the super constructor.
```
List:
List<AnalysisType> types = new ArrayList<>();
types.add(AnalysisType.LONG_AVG);
types.add(AnalysisType.LONG_TOTAL);
super("StepCounter", "stepsTaken", types);
```
```
Array:
AnalysisType[] types = new AnalysisType{AnalysisType.LONG_AVG, AnalysisType.LONG_TOTAL};
super("StepCounter", "stepsTaken", types);
```
```
Values (1):
super("StepCounter", "stepsTaken", AnalysisType.LONG_AVG);
Values (many):
super("StepCounter", "stepsTaken", AnalysisType.LONG_AVG, AnalysisType.LONG_TOTAL);
```
Refer to AnalysisType for what types you should add. The type depends on the return of the getValue(UUID uuid)-method you have written. Refer to AnalysisType for what types you should add. The type depends on the return of the getValue(UUID uuid)-method you have written.
- [AnalysisType](/Plan/src/main/java/com/djrapitops/plan/data/additional/AnalysisType.java) - [AnalysisType](/Plan/src/main/java/com/djrapitops/plan/data/additional/AnalysisType.java)
- [AnalysisType Javadoc](https://rsl1122.github.io/Plan-PlayerAnalytics/main/java/com/djrapitops/plan/data/additional/AnalysisType.html) - [AnalysisType Javadoc](https://rsl1122.github.io/Plan-PlayerAnalytics/main/java/com/djrapitops/plan/data/additional/AnalysisType.html)
AnalysisType.HTML is for all other elements you might want to add. AnalysisType.HTML is for all other elements you might want to add - parseContainer method will be used instead of the getValue method.
**If you want this same datapoint to show data on the inspect page call super.analysisOnly(false);**
Good example is the [FactionsPower](/Plan/src/main/java/com/djrapitops/plan/data/additional/factions/FactionsPower.java)
## Table Example ## Table Example
A good example is the [AdvancedAchievementsTable](/Plan/src/main/java/com/djrapitops/plan/data/additional/advancedachievements/AdvanceAchievementsTable.java). A good example is the [AdvancedAchievementsTable](/Plan/src/main/java/com/djrapitops/plan/data/additional/advancedachievements/AdvanceAchievementsTable.java).
You can use the [Html Enum] to quickly create table html. You can use the [Html Enum](/Plan/src/main/java/com/djrapitops/plan/ui/Html.java) to quickly create table html.
The Html Enum has easy lines for 2, 3 & 4 line columns - More than that will most likely not fit in the box. The Html Enum has easy lines for 2, 3 & 4 line columns - More than that will most likely not fit in the box.
the parse(String... p)-method takes as many strings as parameters as needed to replace all the REPLACE# placeholders on the line. the parse(String... p)-method takes as many strings as parameters as needed to replace all the REPLACE# placeholders on the line.