Tworzenie Placeholderów

Główną umiejętnością Sponge Placeholder API jest tworzenie swoich własnych tokenów i udostępnianie ich innym pluginom. Aby stworzyć swój własny placeholder, musisz utworzyć obiekt implementujący PlaceholderParser i zarejestrować go w Sponge Registry.

Tworzenie PlaceholderParserów

Istnieją dwa sposoby na utworzenie PlaceholderParser'a:

• Używając PlaceholderParser#builder(), dostarczając w nim swój PluginContainer, ID bez namespace oraz funkcję, która przyjmie PlaceholderContext i zwróci Text.

• Bezpośrednio zaimplementuj interfejs.

Informacja

PlaceholderParser'y są Catalog Types. Jeśli implementujesz interfejs bezpośrednio, pamiętaj, aby ID parsera zawierało namespace pluginu w formie [pluginid]:[placeholderid]. ID muszą być również unikatowe.

Obiekty PlaceholderParser przyjmują obiekt PlaceholderContext, który zawiera kontekst żądania oraz zwracają Text bazując na otrzymanym kontekście. Informacje jakie PlaceholderContext może zawierać to:

• Powiązany obiekt, taki jak Player

• Argument string, który na zazwyczaj będzie dostarczony przez silnik szablonów.

Jest to minimum określone przez Sponge.

Jeśli twój placeholder nie jest w stanie dostarczyć tekstu, dlatego że kontekst nie zawiera kontekstu lub argumentów, których potrzebuje, placeholder powinien zwrócić pusty Text i nie rzucać wyjątku.

Wskazówka

Jeśli chcesz dodać możliwość przekazywania wielu argumentów do swojego placeholder’a, zastanów się nad dzieleniem argumentu string.

Pamiętaj aby poinformować użytkowników Twojego pluginu jak argument string powinien wyglądać.

Przykład: PlaceholderParser dla nazwy domyślnego świata

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);
}