Upstream
/
Plan
mirror of https://github.com/plan-player-analytics/Plan.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Updated APIv5 (markdown)

Risto Lahtela 2019-03-29 13:44:15 +02:00
parent 9d61bb55ba
commit b4f04c6959
1 changed files with 177 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

192
APIv5.md

@ -86,7 +86,9 @@ Every `DataExtension` implementation **requires** `@PluginInfo` annotation.
> **Notation:**
> `*` means required parameter
Example usage:
<details>
<summary>Usage & Parameters</summary>
```
@PluginInfo(
name* = "Your Plugin",
@ -106,6 +108,8 @@ public class YourExtension implements DataExtension {}
- `updatePlayerDataOnLeave` - Provider methods about players will also be called when the player leaves the server. By default the player methods are called shortly after the player joins.
- `updateServerDataPeriodically` - Provider methods about server will also be called periodically. By default the server methods are called shortly after registering the `DataExtension`.
</details>
## 📏 Provider Annotations
Provider annotations are method annotations that tell Plan what kind of data methods in your `DataExtension` class provide.
@ -127,7 +131,9 @@ T method(Group group); // The value is about a Group a player is in
**Speciality:** `boolean` values, Can work with `@Conditional`-annotation for conditional execution
Example usage:
<details>
<summary>Usage & Parameters</summary>
```
@BooleanProvider(
text* = "Has Island",
@ -136,7 +142,8 @@ Example usage:
iconName = "question",
iconFamily = Family.SOLID,
iconColor = Color.NONE,
conditionName = "islandCondition"
conditionName = "islandCondition",
hidden = false
)
public boolean hasIsland(UUID playerUUID) {...}
```
@ -148,12 +155,55 @@ public boolean hasIsland(UUID playerUUID) {...}
- `iconFamily` - Icon family should match details on the site above
- `iconColor` - Color of the icon that appears next to the value
- `conditionName` - Name of a condition this boolean represents, used with `@Conditional` annotations
- `hidden` - Should this value be hidden from the web panel?
</details>
<details>
<summary>Usage with @Conditional</summary>
```
@BooleanProvider(
...
conditionName = "hasIsland"
)
public boolean hasIsland(UUID playerUUID) {
return true;
}
@Conditional("hasIsland)
@StringProvider(...) // Another provider is required, can be any Provider.
public String islandName(UUID playerUUID) {...}
```
- `conditionName` is provided by a `@BooleanProvider`.
- If the value is `true`, other methods with `@Conditional(conditionName)` will be called.
- See [Conditional](https://github.com/plan-player-analytics/Plan/wiki/APIv5#conditional) for more
</details>
<details>
<summary>Hiding "Yes"/"No" results</summary>
```
@BooleanProvider(
...
conditionName* = "hasLinkedAccount",
hidden = true
)
public boolean hasLinkedAccount(UUID playerUUID) {...}
```
- If `hidden` is `true`, the `conditionName` parameter is required.
- "Yes" / "No" for this method will not appear on the web panel.
</details>
### `@NumberProvider`
**Speciality:** Whole numbers, Time amounts, Timestamps
Example usage:
<details>
<summary>Usage & Parameters</summary>
```
@NumberProvider(
text* = "Number of Islands",
@ -175,11 +225,32 @@ public long islandCount(UUID playerUUID) {...}
- `iconColor` - Color of the icon that appears next to the value
- `format` - `FormatType` tells that the value is time amount (milliseconds) or a timestamp
</details>
<details>
<summary>FormatTypes (Dates / Time amounts)</summary>
```
@NumberProvider(
...
format = FormatType.DATE_YEAR
)
public long banDate(UUID playerUUID) {...}
```
- `DATE_YEAR` - Value is an Epoch Millisecond, Formats the date based on Plan settings. Year is given importance
- `DATE_SECOND` - Value is an Epoch Millisecond, Formats the date based on Plan settings. Seconds are given importance
- `TIME_MILLISECOND` - Value is amount of milliseconds, Formats time amount based on Plan settings.
- `NONE` - Value is not formatted
</details>
### `@DoubleProvider`
**Speciality:** Floating point numbers
Example usage:
<details>
<summary>Usage & Parameters</summary>
```
@DoubleProvider(
text* = "Balance",
@ -199,11 +270,15 @@ public double balance(UUID playerUUID) {...}
- `iconFamily` - Icon family should match details on the site above
- `iconColor` - Color of the icon that appears next to the value
</details>
### `@PercentageProvider`
**Speciality:** Percentages between 0% and 100%. Requires return values between 0.0 and 1.0.
Example usage:
<details>
<summary>Usage & Parameters</summary>
```
@PercentageProvider(
text* = "Quest completion",
@ -223,11 +298,15 @@ public double questCompletion(UUID playerUUID) {...}
- `iconFamily` - Icon family should match details on the site above
- `iconColor` - Color of the icon that appears next to the value
</details>
### `@StringProvider`
**Speciality:** String values, Links to player page when `playerName` is `true`
Example usage:
<details>
<summary>Usage & Parameters</summary>
```
@StringProvider(
text* = "Town Name",
@ -249,14 +328,36 @@ public String townName(UUID playerUUID) {...}
- `iconColor` - Color of the icon that appears next to the value
- `playerName` - Does this provider return a player name that can be linked to? Links are automatic
</details>
<details>
<summary>Links to player pages</summary>
```
@StringProvider(
...
playerName = true
)
public String townMayor(Group town) {...}
```
- If `playerName` is `true`, the returned value will be formatted to display a link to a player's page.
</details>
## 🔨 Special Provider annotations
These annotations can be used to add information structures. They might have different limitations than other providers.
### `@GroupProvider`
> `@GroupProvider` will be included in the second update for DataExtension API.
**Speciality:** Multiple `Group`s the player is in. Any providers with `Group` parameter will be called with the groups that this method provides.
<details>
<summary>Limitations and Additional data (Expand)</summary>
- **There can only be one GroupProvider per DataExtension** - If you need multiple kinds of groups, create another `DataExtension` class.
- **GroupProvider method requires UUID or String as method parameter.**
@ -267,7 +368,10 @@ Plan will construct following from given group data:
- Additional data about players is grouped based on groups.
- Additional data is displayed under a dropdown of the group.
Example usage:
</details>
<details>
<summary>Usage & Parameters</summary>
```
@GroupProvider(
text* = "Jobs",
@ -287,8 +391,12 @@ public String[] playerJobs(UUID playerUUID) {...}
- `iconFamily` - Icon family should match details on the site above
- `iconColor` - Color of the icon that appears next to the value
</details>
### `@TableProvider`
> `@TableProvider` will be included in the second update for DataExtension API.
**Speciality:** Table structures.
- Player tables can have 4 columns.
@ -296,10 +404,12 @@ public String[] playerJobs(UUID playerUUID) {...}
> If you want to display a table that lists how many players are using something (or data about groups), eg. Players on each version, use `@GroupProvider` (and `Group` parameter methods) instead.
Example usage:
<details>
<summary>Usage & Parameters</summary>
```
@TableProvider(tableColor = Color.NONE)
Table banHistory(UUID playerUUID) {
public Table banHistory(UUID playerUUID) {
Table.Factory banTable = Table.builder()
.columnOne("When", new Icon(Family.SOLID, "gavel")) // Define column names and icons
.columnTwo("...", new Icon(...)) // Icon colors are ignored.
@ -316,6 +426,8 @@ Table banHistory(UUID playerUUID) {
- `tableColor` - Color of the table header.
</details>
### `@GraphProvider`
**Speciality:** Graphs.
@ -330,7 +442,9 @@ These annotations can be used to further control how the values are displayed.
**Specialilty:** Control what plugin-tab the provided value appears in.
Example usage:
<details>
<summary>Usage & Parameters</summary>
```
@TabInfo(
tab* = "Economy",
@ -355,16 +469,20 @@ public class YourExtension implements DataExtension {
- `iconFamily` - Icon family should match details on the site above
- `elementOrder` - Order different elements are placed inside the tab. `VALUES` represents all single values
</details>
### `@Conditional`
**Specialilty:** Control execution of another methods. If the provided `boolean` is `false` the method with `@Conditional` annotation is not called.
**Specialilty:** Control execution of another methods. If provided `boolean` is `true` the method with `@Conditional` annotation will be called.
<details>
<summary>Usage & Parameters</summary>
Example usage:
```
@BooleanProvider(..., conditionName="hasPet")
public boolean hasPet(UUID playerUUID) {...}
@Conditional("hasPet", negated = false)
@Conditional("hasPet")
@StringProvider(text = "Pet Name")
public String petName(UUID playerUUID) {...}
```
@ -372,11 +490,51 @@ public String petName(UUID playerUUID) {...}
- `value` - Name of the condition
- `negated` - Require the condition to be `false` for this method to be called.
</details>
<details>
<summary>Reversed Conditions</summary>
```
@BooleanProvider(..., conditionName="permanentBan")
public boolean isPermanentlyBanned(UUID playerUUID) {...}
@Conditional(value = "permanentBan", negated = true)
@NumberProvider(...)
public long expiryDate(UUID playerUUID) {...}
```
- Negated Conditionals are only called when the provided condition is `false`.
</details>
<details>
<summary>Nested Conditions (Conjunction / AND)</summary>
```
@BooleanProvider(..., conditionName="isBanned")
public boolean isBanned(UUID playerUUID) {...}
@Conditional("isBanned")
@BooleanProvider(..., conditionName="isTemporaryBan")
public boolean isTemporaryBan(UUID playerUUID) {...}
@Conditional("isTemporaryBan")
@NumberProvider(...)
public long expireDate(UUID playerUUID) {...}
```
- Conditions can be nested by adding a `@Conditional` `@BooleanProvider` that returns a second condition.
</details>
### `@InvalidateMethod`
**Speciality:** Removes old values from database if you decide to rename a method. The method name is used when storing the values, so this annotation exists to remove the old values.
Example usage:
<details>
<summary>Usage & Parameters</summary>
```
@InvalidateMethod("oldMethodName")
@PluginInfo(...)
@ -386,6 +544,10 @@ public class YourExtension implements DataExtension {
}
```
- `value` - Name of a removed method, for removing stored results of that method.
</details>
## ❕ Preventing runtime errors
Since annotations do not have any compiler checks, invalid implementation can not be enforced at compile time, and runtime exceptions are used instead.