Créer des Tokens de Placeholders

Au cœur de l’API de Placeholder de Sponge se trouve la possibilité de créer vos propres tokens et de les rendre accessible à tous les plugins. Pour créer votre propre placeholder, vous devez créer un objet qui implémente PlaceholderParser et l’enregistrer dans le Registre Sponge.

Créer des PlaceholderParsers

Il y a deux façons de créer un PlaceholderParser :

• Utiliser PlaceholderParser#builder(), en fournissant votre PluginContainer, un ID sans namespace, et une fonction qui prend un PlaceholderContext et qui retourne un Text.

• Implémenter directement l’interface.

Note

Les PlaceholderParsers sont des Catalog Types. Si vous implémentez l’interface directement, souvenez-vous que l’ID du parser doit avoir le namespace du plugin, de la forme [pluginid]:[placeholderid]. Les IDs doivent également être uniques.

Les objets PlaceholderParser prennent un objet PlaceholderContext en argument, qui contient le contexte de la requête et retourne un Text basé sur ce contexte. Dans les informations que le PlaceholderContext peut contenir se trouvent :

• Un objet associé, comme un Player

• Un string d’argument, qui sera généralement fourni par un moteur de template.

C’est le minimum spécifié par Sponge.

Si votre placeholder est incapable de fournir du texte parce que le contexte ne fournit pas le contexte ou les arguments requis, le placeholder doit retourner un Text vide et ne pas lancer d’exception.

Astuce

Si vous souhaitez fournir la possibilité d’ajouter plusieurs arguments à votre placeholder, envisagez de spécifier un moyen de séparer le string d’argument.

N’oubliez pas de dire aux utilisateurs de votre plugin ce à quoi votre string d’argument doit ressembler.

Exemple : PlaceholderParser pour le Nom du Monde par Défaut

Ce PlaceholderParser essaie de récupérer le nom du monde par défaut, en retournant un Text vide s’il n’arrive pas à le trouver. Il utilise le builder pour créer le parser avec l’ID spongedocs:defaultworld, en supposant que le plugin a un ID de 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();

Exemple : PlaceholderParser pour la Position du Joueur

Ce PlaceholderParser tente de récupérer la position du joueur dans le monde. Si il est utilisé sans Player en tant qu’objet associé, il retournera un Text vide. Il implémente l’interface PlaceholderParser directement.

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

Exemple : PlaceholderParser pour l’Heure Actuelle

Ce PlaceholderParser retourne l’heure actuelle dans le fuseau horaire local du serveur. Si le string « UTC » est fourni comme string d’argument, il retournera l’heure dans le fuseau horaire UTC. Il implémente l’interface PlaceholderParser directement.

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

}

Enregistrer Votre PlaceholderParser

Pour que votre parser soit facilement accessible aux autres plugins, il doit être enregistré dans le registre. Cela doit se faire en écoutant l’événement GameRegistryEvent.Register<PlaceholderParser> et en enregistrant vos parsers avec la méthode register.

Exemple : Enregistrer un PlaceholderParser

PlaceholderParser parser = ...;

@Listener
public void registerTokensEvent(GameRegistryEvent.Register<PlaceholderParser> event) {
    event.register(this.parser);
}