SpigotMC-Mirrors/PlaceholderAPI
1
0
Fork 0
mirror of https://github.com/PlaceholderAPI/PlaceholderAPI synced 2026-04-09 14:32:27 +02:00
Code Issues Packages Projects Releases Wiki Activity

Update Info

Browse Source
This commit is contained in:
Andre601
2026-01-31 15:04:08 +01:00
parent bd6928414d b3825b5c45
commit 39769506c2
3 changed files with 240 additions and 53 deletions
Download Patch File Download Diff File Expand all files Collapse all files

179
docs/developers/using-placeholderapi.md
View File

@@ -6,42 +6,43 @@ description: Guide on how to use PlaceholderAPI in your own plugin.
This page is about using PlaceholderAPI in your own plugin, to either let other plugins use your plugin, or just use placeholders from other plugins in your own.
Please note, that the examples in this page are only available for **PlaceholderAPI 2.10.0 or higher**!
Please note, that the examples in this page are only available for **PlaceholderAPI 2.10.0 (1.0.0 for Hytale version) or newer**!
## First steps
### Add PlaceholderAPI to your Project
Before you can actually make use of PlaceholderAPI, you first have to import it into your project.
Use the below code example matching your dependency manager.
Use the below code example matching your project type and dependency manager.
/// tab | :simple-apachemaven: Maven
```{ .xml .annotate title="pom.xml" data-md-component="api-version" }
/// tab | Minecraft (Spigot, Paper, ...)
//// tab | :simple-apachemaven: Maven
```{ .xml title="pom.xml" data-md-component="api-version" }
<repositories>
<repository>
<id>placeholderapi</id>
<url>https://repo.extendedclip.com/releases/</url>
<url>https://repo.helpch.at/releases/</url>
</repository>
</repositories>
<dependencies>
<dependency>
<groupId>me.clip</groupId>
<artifactId>placeholderapi</artifactId>
<version>{version}</version>
<version>{papiVersion}</version>
<scope>provided</scope>
</dependency>
<!-- Optional: Component support on Paper Servers (Since TBD) -->
<!-- Optional: Component support on Paper Servers (Since 2.12.0) -->
<dependency>
<groupId>me.clip</groupId>
<artifactId>placeholderapi-paper</artifactId>
<version>{version}</version>
<version>{papiVersion}</version>
<scope>provided</scope>
</dependencies>
```
///
////
/// tab | :simple-gradle: Gradle
//// tab | :simple-gradle: Gradle
```{ .groovy title="build.gradle" data-md-component="api-version" }
repositories {
maven {
@@ -50,18 +51,68 @@ repositories {
}
dependencies {
compileOnly 'me.clip:placeholderapi:{version}'
compileOnly 'me.clip:placeholderapi:{papiVersion}'
// Optional: Component support on Paper Servers (Since TBD)
compileOnly 'me.clip:placeholderapi-paper:{version}'
// Optional: Component support on Paper Servers (Since 2.12.0)
compileOnly 'me.clip:placeholderapi-paper:{papiVersion}'
}
```
////
///
/// details | What is `{version}`?
/// tab | Hytale
//// tab | :simple-apachemaven: Maven
```{ .xml title="pom.xml" data-md-component="api-version" }
<repositories>
<repository>
<id>hytale</id>
<url>https://repo.codemc.io/repository/hytale/</url>
</repository>
<repository>
<id>placeholderapi</id>
<url>https://repo.helpch.at/releases/</url>
</repository>
</repositories>
<dependencies>
<dependency>
<!-- Replace {hytaleVersion} with the version you need -->
<groupId>com.hypixel.hytale</groupId>
<artifactId>Server</artifactId>
<version>{hytaleVersion}</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>at.helpch</groupId>
<artifactId>placeholderapi-hytale</artifactId>
<version>{papiHytaleVersion}</version>
<scope>provided</scope>
</dependency>
</dependencies>
```
////
//// tab | :simple-gradle: Gradle
```{ .groovy title="build.gradle" data-md-component="api-version" }
repositories {
maven {
url = 'https://repo.codemc.io/repository/hytale/'
url = 'https://repo.helpch.at/releases/'
}
}
dependencies {
// Replace {hytaleVersion} with the version you need.
compileOnly 'com.hypixel.hytale:Server:{hytaleVersion}'
compileOnly 'at.helpch:placeholderapi-hytale:{papiHytaleVersion}'
}
```
////
///
/// details | What is `{papiVersion}`/`{papiHytaleVersion}`?
type: question
Using Javascript, `{version}` is replaced with the latest available API version of PlaceholderAPI.
Using Javascript, `{papiVersion}` and `{papiHytaleVersion}` is replaced with the latest available API version of PlaceholderAPI for Minecraft and Hytale respectively.
Should you see the placeholder as-is does it mean that you either block Javascript, or that the version couldn't be obtained in time during page load.
You can always find the latest version matching the API version on the [releases tab](https://github.com/PlaceholderAPI/PlaceholderAPI/releases) of the GitHub Repository.
@@ -83,7 +134,7 @@ Tab the :material-plus-circle: icons in the code block below for additional info
name: ExamplePlugin
version: 1.0
author: author
main: your.main.path.Here
main: com.example.plugin.ExamplePlugin
softdepend: ["PlaceholderAPI"] # (1)
```
@@ -101,7 +152,7 @@ Tab the :material-plus-circle: icons in the code block below for additional info
name: ExamplePlugin
version: 1.0
author: author
main: your.main.path.Here
main: com.example.plugin.ExamplePlugin
depend: ["PlaceholderAPI"] # (1)
```
@@ -123,7 +174,7 @@ Tab the :material-plus-circle: icons in the code block below for additional info
name: ExamplePlugin
version: 1.0
author: author
main: your.main.path.Here
main: com.example.plugin.ExamplePlugin
dependencies:
server:
@@ -146,7 +197,7 @@ Tab the :material-plus-circle: icons in the code block below for additional info
name: ExamplePlugin
version: 1.0
author: author
main: your.main.path.Here
main: com.example.plugin.ExamplePlugin
dependencies:
server:
@@ -161,6 +212,42 @@ dependencies:
///
/// tab | manifest.json (Hytale)
//// tab | Optional dependency
```{ .json .annotate title="manifest.json" }
{
"Group": "com.example",
"Name": "ExamplePlugin",
"Version": "1.0",
"Main": "com.example.plugin.ExamplePlugin",
"OptionalDependencies": {
"HelpChat:PlaceholderAPI": ">= 1.0.2"
}
}
```
////
//// tab | Required dependency
```{ .json .annotate title="manifest.json" }
{
"Group": "com.example",
"Name": "ExamplePlugin",
"Version": "1.0",
"Main": "com.example.plugin.ExamplePlugin",
"Dependencies": {
"HelpChat:PlaceholderAPI": ">= 1.0.2"
}
}
```
////
///
## Adding placeholders to PlaceholderAPI
A full guide on how to create expansions can be found on the [Creating a PlaceholderExpansion](creating-a-placeholderexpansion.md) page.
@@ -172,8 +259,8 @@ To use placeholders from other plugins in your own plugin, you simply have to [(
It is also important to point out, that any required plugin/dependency for an expansion has to be on the server and enabled, or the `setPlaceholders` method will just return the placeholder itself (do nothing).
/// info | New since TBD
Starting with version TBD is it now possible to provide Components from the Adventure library to have placeholders parsed in.
/// info | New since 2.12.0
Starting with version 2.12.0 is it now possible to provide Components from the Adventure library to have placeholders parsed in.
In order to use this new feature are the following things required to be true:
@@ -182,11 +269,9 @@ In order to use this new feature are the following things required to be true:
- You use `PAPIComponent` instead of `PlaceholderAPI` to parse Components.
///
/// details | Example
type: example
/// tab | Spigot, Paper, ...
Let's assume we want to send a custom join message that shows the primary group a player has.
To achieve this, we can do the following:
The following is an example plugin that sends `%player_name% joined the server! They are rank %vault_rank%` as the Join message, having the placeholders be replaced by PlaceholderAPI.
//// note |
The below example assumes a **soft dependency** on PlaceholderAPI to handle PlaceholderAPI not being present more decently.
@@ -195,7 +280,7 @@ Tab the :material-plus-circle: icons in the code block below for additional info
////
```{ .java .annotate title="JoinExample.java" }
package at.helpch.placeholderapi;
package com.example.plugin;
import me.clip.placeholderapi.PlaceholderAPI;
@@ -238,7 +323,47 @@ public class JoinExample extends JavaPlugin implements Listener {
Example output: `Notch joined the server! They are rank Admin`
//// info | New since TBD
//// info | New since 2.12.0
Using `placeholderapi-papi` and `PAPIComponents` instead of `PlaceholderAPI` allows you to parse placeholders inside Adventure Components.
////
///
/// tab | Hytale
The following is an example plugin that sends `Welcome %player_name%!` as the Join message, having the placeholders be replaced by PlaceholderAPI.
``` { .java .annotate title="JoinExample.java" }
packate com.example.plugin;
import at.helpch.placeholderapi.PlaceholderAPI;
import com.hypixel.hytale.server.core.event.events.player.PlayerReadyEvent;
import com.hypixel.hytale.server.core.Message;
import com.hypixel.hytale.server.core.plugin.JavaPlugin;
import com.hypixel.hytale.server.core.plugin.JavaPluginInit;
public class JoinExample extends JavaPlugin {
public JoinExample(JavaPluginInit init) {
super(init)
}
@Override
protected void setup() {
// (1)
getEventRegistry().registerGlobal(PlayerReadyEvent.class, this::onPlayerReady);
}
public void onPlayerReady(PlayerReadyEvent event) {
Player player = event.getPlayer();
// (2)
player.sendMessage(PlaceholderAPI.setPlaceholders(Message.raw("Welcome %player_name%!"), player))
}
}
```
1. We tell the server to call `onPlayerReady` whenever a `PlayerReadyEvent` fires.
2. PlaceholderAPI offers multiple `setPlaceholders` methods that can either return a `String` or a `Message` object, depending on your needs.
Note that these methods require input of the same type: `setPlaceholders(String, PlayerRef)` for String and `setPlaceholders(Message, PlayerRef)` for Messages.
///