mirror of
https://github.com/PlaceholderAPI/PlaceholderAPI
synced 2025-02-05 03:45:28 +01:00
Merge branch 'wiki' into feat/wiki-deluxemenus-placeholders
This commit is contained in:
Andre_601
GitHub
commit
721cc30e0c
4
.github/workflows/publish_site.yml
vendored
4
.github/workflows/publish_site.yml
vendored
@ -57,11 +57,11 @@ jobs:
|
||||
- name: Build pages
|
||||
run: mkdocs build
|
||||
- name: Configure GitHub Pages
|
||||
uses: actions/configure-pages@v4
|
||||
uses: actions/configure-pages@v5
|
||||
- name: Upload Pages Artifact
|
||||
uses: actions/upload-pages-artifact@v3
|
||||
with:
|
||||
path: 'site/'
|
||||
- name: Deploy to GitHub Pages
|
||||
uses: actions/deploy-pages@v4
|
||||
id: deployment
|
||||
id: deployment
|
||||
|
||||
48
README.md
48
README.md
@ -87,7 +87,7 @@ $ git checkout -b <branch>
|
||||
|
||||
It is now time to make your changes. It is recommended to use MkDocs and its live-preview feature to see your changes applied in real time whenever you save a file.
|
||||
|
||||
To use the live-preview, run `mkdocs serve` in the same folder where the `mkdocs.yml` file is located. This should start a server on `http://127.0.0.1:8000` that you can open in your browser.
|
||||
To use the live-preview, run `mkdocs serve` in the same folder where the `mkdocs.yml` file is located. This should start a server on `http://127.0.0.1:8000` that you can open in your browser. You can also append the `--open` argument to the command to make MkDocs open the preview directly, avoiding the need of having to open it yourself.
|
||||
Should the command not work, check that you actually installed MkDocs and any required dependencies. The easiest way is to just execute `pip install mkdocs-material` to download the Material for MkDocs theme alongside additional dependencies, including MkDocs.
|
||||
|
||||
To cancel the live preview, simply press <kbd>Ctrl</kbd>+<kbd>C</kbd> in the git-bash terminal to shut the live preview server down.
|
||||
@ -164,28 +164,32 @@ The following rules apply to all pages:
|
||||
|
||||
The following rules apply specifically to entries in the [Placeholder List][placeholder-list] page:
|
||||
|
||||
1. Entries need to be in alphabetical order.
|
||||
1. Entries need to be in alphabetical order.
|
||||
- Should an entry with the name already exist will you need to add yours after it.
|
||||
2. An entry follows this specific format:
|
||||
````markdown
|
||||
- ### [<name>](<link>)
|
||||
> <command>
|
||||
|
||||
<text>
|
||||
|
||||
```
|
||||
<placeholders>
|
||||
```
|
||||
````
|
||||
- `<name>` is the name of the Placeholder expansion you add.
|
||||
- `<link>` is a link to the plugin this expansion is made for. If the expansion is not for a plugin should no link be added (Only `- ### <name>` be used).
|
||||
- Links to spigot pages need to be sanitized, meaning a link such as `https://www.spigotmc.org/resources/placeholderapi.6245/` becomes `https://www.spigotmc.org/resources/6245/`
|
||||
- `<command>` is the [`/papi ecloud download`][download-command] used to get the expansion. Should the expansion not be on the eCloud will you need to put `NO DOWNLOAD COMMAND` here.
|
||||
- `<text>` is an optional text that can be used to point to extra documentation. Please keep it short and simple.
|
||||
- `<placeholders>` would be all available placeholders. Each entry should be on a new line.
|
||||
- Please avoid explicit examples and instead use `<>` and `[]` to indicate required or optional values (i.e. instead of `%expansion_SomePlayer%` it would be `%expansion_<player>%`)
|
||||
3. Make sure to also add an entry to the list at the top of the page, linking to your entry.
|
||||
4. Should your entry have entries before and/or after it will you need to add horizontal lines (`----`) to separate yours from these entries. Keep an empty line between the horizontal line and any entry.
|
||||
2. An entry follows this specific format:
|
||||
````markdown
|
||||
### [<name>](<link>)
|
||||
/// <command>
|
||||
///
|
||||
|
||||
<text>
|
||||
|
||||
```
|
||||
<placeholders>
|
||||
```
|
||||
````
|
||||
- `<name>` is the name of the Placeholder expansion you add.
|
||||
- `<link>` is a link to the plugin this expansion is made for. If the expansion is not for a plugin should no link be added (Only `- ### <name>` be used).
|
||||
- Links to spigot pages need to be sanitized, meaning a link such as `https://www.spigotmc.org/resources/placeholderapi.6245/` becomes `https://www.spigotmc.org/resources/6245/`
|
||||
- `<command>` needs to be replaced with one of the following values, depending on how the expansion can be added:
|
||||
- Should your expansion be built-in into a Plugin, add `integrated | Built into Plugin`
|
||||
- Should your expansion be obtainable via the [`/papi ecloud download`][download-command] command, add `command | papi ecloud download <name of expansion>`
|
||||
- Should your expansion only be downloadable via external sources (i.e. a GitHub Release), add `download | <link to download>`
|
||||
- `<text>` is an optional text that can be used to point to extra documentation. Please keep it short and simple.
|
||||
- `<placeholders>` would be all available placeholders. Each entry should be on a new line.
|
||||
- Please avoid explicit examples and instead use `<>` and `[]` to indicate required or optional values (i.e. instead of `%expansion_SomePlayer%` it would be `%expansion_<player>%`)
|
||||
3. Make sure to also add an entry to the list at the top of the page, linking to your entry.
|
||||
4. Should your entry have entries before and/or after it will you need to add horizontal lines (`----`) to separate yours from these entries. Keep an empty line between the horizontal line and any entry.
|
||||
|
||||
> A [online tool][papi-list-gen] exists for your convenience to create the markdown for a new entry.
|
||||
|
||||
|
||||
@ -10,10 +10,12 @@ document$.subscribe(async => {
|
||||
}
|
||||
|
||||
async function fetchAPIInfo() {
|
||||
const release = await fetch("https://papi-repo-proxy.vercel.app/repo/latest-release").then(_ => _.json());
|
||||
const release = await fetch("https://repo.extendedclip.com/api/maven/latest/version/releases/me/clip/placeholderapi").then(_ => _.json());
|
||||
|
||||
console.log(release)
|
||||
|
||||
const data = {
|
||||
"version": release.name
|
||||
"version": release.version
|
||||
}
|
||||
|
||||
__md_set("__api_tag", data, sessionStorage);
|
||||
|
||||
@ -1,7 +1,65 @@
|
||||
:root {
|
||||
--md-admonition-icon--command: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16"><path d="M13.94 3.045a.75.75 0 0 0-1.38-.59l-4.5 10.5a.75.75 0 1 0 1.38.59l4.5-10.5ZM5 11.5a1.5 1.5 0 1 1-3 0 1.5 1.5 0 0 1 3 0Z"></path></svg>');
|
||||
--md-admonition-icon--integrated: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16"><path d="M4 8H2.5a1 1 0 0 0-1 1v5.25a.75.75 0 0 1-1.5 0V9a2.5 2.5 0 0 1 2.5-2.5H4V5.133a1.75 1.75 0 0 1 1.533-1.737l2.831-.353.76-.913c.332-.4.825-.63 1.344-.63h.782c.966 0 1.75.784 1.75 1.75V4h2.25a.75.75 0 0 1 0 1.5H13v4h2.25a.75.75 0 0 1 0 1.5H13v.75a1.75 1.75 0 0 1-1.75 1.75h-.782c-.519 0-1.012-.23-1.344-.63l-.761-.912-2.83-.354A1.75 1.75 0 0 1 4 9.867Zm6.276-4.91-.95 1.14a.753.753 0 0 1-.483.265l-3.124.39a.25.25 0 0 0-.219.248v4.734c0 .126.094.233.219.249l3.124.39a.752.752 0 0 1 .483.264l.95 1.14a.25.25 0 0 0 .192.09h.782a.25.25 0 0 0 .25-.25v-8.5a.25.25 0 0 0-.25-.25h-.782a.25.25 0 0 0-.192.09Z"></path></svg>');
|
||||
--md-admonition-icon--download: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16"><path d="M2.75 14A1.75 1.75 0 0 1 1 12.25v-2.5a.75.75 0 0 1 1.5 0v2.5c0 .138.112.25.25.25h10.5a.25.25 0 0 0 .25-.25v-2.5a.75.75 0 0 1 1.5 0v2.5A1.75 1.75 0 0 1 13.25 14Z"></path><path d="M7.25 7.689V2a.75.75 0 0 1 1.5 0v5.689l1.97-1.969a.749.749 0 1 1 1.06 1.06l-3.25 3.25a.749.749 0 0 1-1.06 0L4.22 6.78a.749.749 0 1 1 1.06-1.06l1.97 1.969Z"></path></svg>');
|
||||
}
|
||||
|
||||
.md-header__button.md-logo img {
|
||||
height: 3rem;
|
||||
}
|
||||
|
||||
.md-typeset .grid.cards.hide-list > ul > li > ul > li {
|
||||
list-style-type: none;
|
||||
}
|
||||
|
||||
/***************************
|
||||
* Custom Admonition boxes *
|
||||
***************************/
|
||||
|
||||
/* Command */
|
||||
.md-typeset .admonition.command,
|
||||
.md-typeset details.command {
|
||||
border-color: #00c853;
|
||||
}
|
||||
.md-typeset .command > .admonition-title,
|
||||
.md-typeset .command > summary {
|
||||
background-color: #00c8531a;
|
||||
}
|
||||
.md-typeset .command > .admonition-title::before,
|
||||
.md-typeset .command > summary::before {
|
||||
background-color: #00c853;
|
||||
-webkit-mask-image: var(--md-admonition-icon--command);
|
||||
mask-image: var(--md-admonition-icon--command);
|
||||
}
|
||||
|
||||
/* Integrated (built-in) */
|
||||
.md-typeset .admonition.integrated,
|
||||
.md-typeset details.integrated {
|
||||
border-color: #9e9e9e;
|
||||
}
|
||||
.md-typeset .integrated > .admonition-title,
|
||||
.md-typeset .integrated > summary {
|
||||
background-color: #9e9e9e1a;
|
||||
}
|
||||
.md-typeset .integrated > .admonition-title::before,
|
||||
.md-typeset .integrated > summary::before {
|
||||
background-color: #9e9e9e;
|
||||
-webkit-mask-image: var(--md-admonition-icon--integrated);
|
||||
mask-image: var(--md-admonition-icon--integrated);
|
||||
}
|
||||
|
||||
/* Download */
|
||||
.md-typeset .admonition.download,
|
||||
.md-typeset details.download {
|
||||
border-color: #00c853;
|
||||
}
|
||||
.md-typeset .download > .admonition-title,
|
||||
.md-typeset .download > summary {
|
||||
background-color: #00c8531a;
|
||||
}
|
||||
.md-typeset .download > .admonition-title::before,
|
||||
.md-typeset .download > summary::before {
|
||||
background-color: #00c853;
|
||||
-webkit-mask-image: var(--md-admonition-icon--download);
|
||||
mask-image: var(--md-admonition-icon--download);
|
||||
}
|
||||
@ -107,7 +107,7 @@ This method of creating a PlaceholderExpansion is recommended as it has the foll
|
||||
Internal PlaceholderExpansions are not automatically registered by PlaceholderAPI, due to them not being a separate jar file located in the expansion folder.
|
||||
Please see the [Regsister your Expansion](#register-your-expansion) section for more details.
|
||||
|
||||
You are also required to override and set `persistent()` to `true`. This tells PlaceholderAPI to not unload your expansion during plugin reload, as it would otherwise unregister your expansion, making it no longer work.
|
||||
You are also required to override and set `persist()` to `true`. This tells PlaceholderAPI to not unload your expansion during plugin reload, as it would otherwise unregister your expansion, making it no longer work.
|
||||
///
|
||||
|
||||
/// details | Full Example
|
||||
|
||||
@ -18,7 +18,7 @@ Use the below code example matching your dependency manager.
|
||||
<repositories>
|
||||
<repository>
|
||||
<id>placeholderapi</id>
|
||||
<url>https://repo.extendedclip.com/content/repositories/placeholderapi/</url>
|
||||
<url>https://repo.extendedclip.com/releases/</url>
|
||||
</repository>
|
||||
</repositories>
|
||||
<dependencies>
|
||||
@ -36,7 +36,7 @@ Use the below code example matching your dependency manager.
|
||||
```{ .groovy title="build.gradle" data-md-component="api-version" }
|
||||
repositories {
|
||||
maven {
|
||||
url = 'https://repo.extendedclip.com/content/repositories/placeholderapi/'
|
||||
url = 'https://repo.extendedclip.com/releases/'
|
||||
}
|
||||
}
|
||||
|
||||
@ -62,27 +62,39 @@ Next step is to go to your plugin.yml or paper-plugin.yml and add PlaceholderAPI
|
||||
/// tab | :simple-spigotmc: plugin.yml
|
||||
|
||||
//// tab | Optional dependency
|
||||
```yaml
|
||||
|
||||
///// note |
|
||||
Tab the :material-plus-circle: icons in the code block below for additional information.
|
||||
/////
|
||||
|
||||
```{ .yaml .annotate title="plugin.yml" }
|
||||
name: ExamplePlugin
|
||||
version: 1.0
|
||||
author: author
|
||||
main: your.main.path.Here
|
||||
|
||||
# This sets PlaceholderAPI as an optional dependency for your plugin.
|
||||
softdepend: [PlaceholderAPI]
|
||||
softdepend: ["PlaceholderAPI"] # (1)
|
||||
```
|
||||
|
||||
1. This sets PlaceholderAPI as an optional dependency for your plugin.
|
||||
////
|
||||
|
||||
//// tab | Required dependency
|
||||
```yaml
|
||||
|
||||
///// note |
|
||||
Tab the :material-plus-circle: icons in the code block below for additional information.
|
||||
/////
|
||||
|
||||
```{ .yaml .annotate title="plugin.yml" }
|
||||
name: ExamplePlugin
|
||||
version: 1.0
|
||||
author: author
|
||||
main: your.main.path.Here
|
||||
|
||||
# This sets PlaceholderAPI as a required dependency for your plugin.
|
||||
depend: [PlaceholderAPI]
|
||||
depend: ["PlaceholderAPI"] # (1)
|
||||
```
|
||||
|
||||
1. This sets PlaceholderAPI as a required dependency for your plugin.
|
||||
////
|
||||
|
||||
///
|
||||
@ -90,7 +102,12 @@ depend: [PlaceholderAPI]
|
||||
/// tab | :fontawesome-regular-paper-plane: paper-plugin.yml
|
||||
|
||||
//// tab | Optional dependency
|
||||
```yaml
|
||||
|
||||
///// note |
|
||||
Tab the :material-plus-circle: icons in the code block below for additional information.
|
||||
/////
|
||||
|
||||
```{ .yaml .annotate title="paper-plugin.yml" }
|
||||
name: ExamplePlugin
|
||||
version: 1.0
|
||||
author: author
|
||||
@ -99,14 +116,21 @@ main: your.main.path.Here
|
||||
dependencies:
|
||||
server:
|
||||
PlaceholderAPI:
|
||||
# Load order is relative to the dependency. So here PlaceholderAPI loads before our plugin.
|
||||
load: BEFORE
|
||||
load: BEFORE # (1)
|
||||
required: false
|
||||
```
|
||||
|
||||
1. Load order is relative to the Dependency.
|
||||
This means that in this example, PlaceholderAPI is loaded **before** your plugin.
|
||||
////
|
||||
|
||||
//// tab | Required dependency
|
||||
```yaml
|
||||
|
||||
///// note |
|
||||
Tab the :material-plus-circle: icons in the code block below for additional information.
|
||||
/////
|
||||
|
||||
```{ .yaml .annotate title="paper-plugin.yml" }
|
||||
name: ExamplePlugin
|
||||
version: 1.0
|
||||
author: author
|
||||
@ -115,10 +139,12 @@ main: your.main.path.Here
|
||||
dependencies:
|
||||
server:
|
||||
PlaceholderAPI:
|
||||
# Load order is relative to the dependency. So here PlaceholderAPI loads before our plugin.
|
||||
load: BEFORE
|
||||
load: BEFORE # (1)
|
||||
required: true
|
||||
```
|
||||
|
||||
1. Load order is relative to the Dependency.
|
||||
This means that in this example, PlaceholderAPI is loaded **before** your plugin.
|
||||
////
|
||||
|
||||
///
|
||||
@ -134,10 +160,19 @@ To use placeholders from other plugins in our own plugin, we simply have to [(so
|
||||
|
||||
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).
|
||||
|
||||
/// example
|
||||
/// details | Example
|
||||
type: example
|
||||
|
||||
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:
|
||||
```java
|
||||
|
||||
//// note |
|
||||
The below example assumes a **soft dependency** on PlaceholderAPI to handle PlaceholderAPI not being present more decently.
|
||||
|
||||
Tab the :material-plus-circle: icons in the code block below for additional information.
|
||||
////
|
||||
|
||||
```{ .java .annotate title="JoinExample.java" }
|
||||
package at.helpch.placeholderapi;
|
||||
|
||||
import me.clip.placeholderapi.PlaceholderAPI;
|
||||
@ -155,18 +190,10 @@ public class JoinExample extends JavaPlugin implements Listener {
|
||||
@Override
|
||||
public void onEnable() {
|
||||
|
||||
if (Bukkit.getPluginManager().getPlugin("PlaceholderAPI") != null) {
|
||||
/*
|
||||
* We register the EventListener here, when PlaceholderAPI is installed.
|
||||
* Since all events are in the main class (this class), we simply use "this"
|
||||
*/
|
||||
Bukkit.getPluginManager().registerEvents(this, this);
|
||||
if (Bukkit.getPluginManager().isPluginEnabled("PlaceholderAPI")) {
|
||||
Bukkit.getPluginManager().registerEvents(this, this); // (1)
|
||||
} else {
|
||||
/*
|
||||
* We inform about the fact that PlaceholderAPI isn't installed and then
|
||||
* disable this plugin to prevent issues.
|
||||
*/
|
||||
getLogger().warn("Could not find PlaceholderAPI! This plugin is required.");
|
||||
getLogger().warn("Could not find PlaceholderAPI! This plugin is required."); // (2)
|
||||
Bukkit.getPluginManager().disablePlugin(this);
|
||||
}
|
||||
}
|
||||
@ -175,16 +202,17 @@ public class JoinExample extends JavaPlugin implements Listener {
|
||||
public void onJoin(PlayerJoinEvent event) {
|
||||
String joinText = "%player_name% joined the server! They are rank %vault_rank%";
|
||||
|
||||
/*
|
||||
* We parse the placeholders using "setPlaceholders"
|
||||
* This would turn %vault_rank% into the name of the Group, that the
|
||||
* joining player has, assuming Vault and the Vault expansion are
|
||||
* on the server.
|
||||
*/
|
||||
joinText = PlaceholderAPI.setPlaceholders(event.getPlayer(), joinText);
|
||||
joinText = PlaceholderAPI.setPlaceholders(event.getPlayer(), joinText); // (3)
|
||||
|
||||
event.setJoinMessage(joinText);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
1. We check that PlaceholderAPI is present and enabled to then register events to handle (See below).
|
||||
2. In case PlaceholderAPI is not present are we reporting this issue and disable the plugin.
|
||||
3. Using `PlaceholderAPI.setPlaceholders(Player, String)` we can parse `%placeholder%` text in the provided String, should they have a matching expansion and said expansion return a non-null String.
|
||||
In our example are we providing a text containing `%player_name%` and `%vault_rank%` to be parsed, which require the Player and Vault expansion respectively.
|
||||
|
||||
Example output: `Notch joined the server! They are rank Admin`
|
||||
///
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -215,6 +215,9 @@ If your plugin isn't shown here and you want it to be added, [read the Wiki READ
|
||||
- **[CitizensBooks](https://www.spigotmc.org/resources/37465/)**
|
||||
- [x] Supports placeholders.
|
||||
- [ ] Provides own placeholders. [Link]
|
||||
- **[ClaimChunk](https://www.spigotmc.org/resources/44458/)**
|
||||
- [x] Supports placeholders.
|
||||
- [x] Provides own placeholders. [**[Link](placeholder-list.md#claimchunk)**]
|
||||
- **[Clans-API for Spigot/Clan tag in chat](https://www.spigotmc.org/resources/31547/)**
|
||||
- [ ] Supports placeholders.
|
||||
- [x] Provides own placeholders. [**[Link](placeholder-list.md#clans-api-for-spigotclan-tag-in-chat)**]
|
||||
|
||||
@ -40,10 +40,11 @@ The way PlaceholderAPI's system works, allows a Placeholder Expansion and its co
|
||||
Depending on what type you have, will you need to do some extra steps to use the placeholder from the Placeholder Expansion.
|
||||
|
||||
One way to find out, if an Expansion is included or separate, is to check the [Placeholder List](placeholder-list.md) page for any entry of it.
|
||||
If it exists on the page, can you check, if the line right after the title says `NO DOWNLOAD COMMAND` or `/papi ecloud download ...` (i.e. `/papi ecloud download Player`).
|
||||
If it exists on the page, can you check the infobox right below the title of the Expansion for one of the following cases:
|
||||
|
||||
If the line says the former, does it mean, the expansion is part of the plugin and doesn't need any extra steps to be active (Unless the plugin author mentions otherwise).
|
||||
In the case of the later, will you need to download the expansion from the eCloud. Simply copy the command and execute it either in the console, or in-game. Afterwards, reload PlaceholderAPI using `/papi reload`.
|
||||
- `papi ecloud download <expansion>`: The expansion is on the ecloud and needs to be downloaded using the [`/papi ecloud download` command](commands.md#papi-ecloud-download).
|
||||
- `Built into Plugin`: The expansion is part of the plugin it depends on and doesn't require any steps to install, unless stated otherwise.
|
||||
- *A URL*: The Expansion needs to be downloaded from a separate source (i.e. a GitHub Release). You need to manually download and move the jar into the expansions folder.
|
||||
|
||||
You can check what expansions are loaded by running `/papi list`.
|
||||
|
||||
|
||||
@ -127,6 +127,9 @@ markdown_extensions:
|
||||
- bug
|
||||
- example
|
||||
- quote
|
||||
- command
|
||||
- integrated
|
||||
- download
|
||||
- pymdownx.blocks.details
|
||||
- pymdownx.blocks.tab:
|
||||
alternate_style: true
|
||||
|
||||
Loading…
Reference in New Issue
Block a user