Creating Placeholder Tokens
At the heart of the Sponge Placeholder API is the ability to create your own tokens and have them accessible to all plugins. To create your own placeholder, you must create an object that implements PlaceholderParser and register it in the Sponge Registry.
Creating PlaceholderParsers
There are two ways you can create a PlaceholderParser
:
Using PlaceholderParser#builder(), supplying your PluginContainer, un-namespaced ID and a function that takes a
PlaceholderContext
and returns aText
.Directly implement the interface.
注釈
PlaceholderParsers
are Catalog Types. If you implement the interface directly,
remember that the ID of the parser should be plugin namespaced, of the form [pluginid]:[placeholderid]
. IDs
must also be unique.
PlaceholderParser objects take a PlaceholderContext object which contains the context of the
request and returns a Text based on that context. Information that the PlaceholderContext
may
contain includes:
An associated object, such as a Player
An argument string which generally will be provided by a templating engine
This is the minimum as specified by Sponge.
If your placeholder is unable to provide text because the context does not provide the context or arguments it requires,
the placeholder should return an empty Text
and not throw an exception.
ちなみに
If you wish to provide the ability to add multiple arguments to your placeholder, consider specifying a way to split up the argument string.
Remember to tell users of your plugin what you expect your argument string to look like.
Example: Default World Name PlaceholderParser
This PlaceholderParser
attempts to get the default world’s name, returning an empty Text
if it cannot be
found. It uses the builder to create the parser with ID spongedocs:defaultworld
, assuming the plugin has an ID of
spongedocs
.
PluginContainer thisPlugin = ...;
PlaceholderParser parser = PlaceholderParser.builder()
.plugin(this.thisPlugin)
.id("defaultworld")
.name("Default World Placeholder")
.parser(placeholderContext -> {
return Sponge.getServer()
.getDefaultWorld()
.map(x -> x.getWorldName())
.orElse(Text.EMPTY);
})
.build();
Example: Player Location PlaceholderParser
This PlaceholderParser
attempts to get the player’s location in the world. If used without a Player
as the
associated object, it returns an empty Text. This implements the PlaceholderParser
interface directly.
public class PlayerLocationPlaceholder implements PlaceholderParser {
@Override
public String getId() {
return "spongedocs:location"
}
@Override
public String getName() {
return "Location Placeholder"
}
@Override
public Text parse(PlaceholderText placeholderText) {
placeholderText.getAssociatedReceiver()
.filter(x -> x instanceof Player)
.map(player -> ((Player) player).getLocation())
.map(location -> Text.of("World: ", location.getExtent().getName(), " - ", location.getPosition()))
.orElse(Text.EMPTY);
}
}
Example: Current Time PlaceholderParser
This PlaceholderParser
returns the current time in the server’s local timezone. If the string 「UTC」 is provided as
the argument string, it returns the current time in the UTC time zone. This implements the PlaceholderParser
interface directly.
public class CurrentTimePlaceholder implements PlaceholderParser {
@Override
public String getId() {
return "spongedocs:currenttime";
}
@Override
public String getName() {
return "Current Time parser";
}
@Override
public Text parse(PlaceholderContext placeholderContext) {
if (placeholderContext.getArgumentString().filter(x -> x.equalsIgnoreCase("UTC")).isPresent()) {
return Text.of(OffsetDateTime.now(ZoneOffset.UTC).format(FORMATTER));
}
return Text.of(OffsetDateTime.now().format(FORMATTER));
}
}
Registering Your PlaceholderParser
For your parser to be easily accessible to other plugins, it must be registered in the registry. This should be done by listening to the GameRegistryEvent.Register<PlaceholderParser> event and registering your parsers using the register method.
Example: Registering a PlaceholderParser
PlaceholderParser parser = ...;
@Listener
public void registerTokensEvent(GameRegistryEvent.Register<PlaceholderParser> event) {
event.register(this.parser);
}