Placeholders

This page describes how to create and register custom placeholders.

A placeholder is used to display a value in a text. The library provides default placeholders but also enables developers to create their own placeholders to display their custom values in texts.

Create a placeholder

A placeholder is defined by creating a class that implements the Placeholder interface. The following code represents a placeholder for the player's ping:

public class PlayerPingPlaceholder implements Placeholder {

    @Override
    public String getName() {
        return "%player_ping%";
    }

    @Override
    public String getValue(Context context) {
        InventoryViewer viewer = context.getData(CommonContextKey.VIEWER.name(), InventoryViewer.class);
        Player player = viewer.getPlayer();
        return Integer.toString(player.getPing());
    }

    @Override
    public boolean accept(Context context) {
        return context.hasData(CommonContextKey.VIEWER.name());
    }
}

When using the Placeholder interface, several methods must be implemented:

Method name	Description
String getName()	Returns the name of the placeholder. It is recommended to use the format %placeholder_name%.
String getValue(Context context)	Returns the value the placeholder for the provided context.
boolean accept(Context context)	Check that the placeholder can be applied using the provided context.

Note: Some of these methods relies on a Context that is explained in the Context page.

Register a placeholder

To be used in an inventory, a placeholder must be registered in its InventoryDescriptor. This can be done by redefining the addPlaceholders(PlaceholderManager manager) method. The following code registers the placeholder created in the previous step of this tutorial:

public class CustomInventoryDescriptor implements InventoryDescriptor {  

    ... 

    @Override
    public void addPlaceholders(PlaceholderManager manager) {
        manager.addPlaceholder(new PlayerPingPlaceholder());
    }

    ...
}

Placeholders for pagination items

The library enables developers to paginate items in an inventory and it is then a common use case to need to display some values of what is paginated. This can be done using placeholders.

The process is nearly the same as the previous example. However, the only difference is that, as inventories may contain several paginations, you must ensure that the placeholder is only applied on items of the targeted pagination.

This is done by taking the pagination id as parameter in the class constructor and comparing it in the accept(Context context) method. The following code gives an example for a pagination that paginates a list of Integer:

public class PaginationItemNumberPlaceholder implements Placeholder {
    
    private final String paginationId;
    
    public PaginationItemNumberPlaceholder(String paginationId) {
        this.paginationId = paginationId;
    }
    
    @Override
    public String getName() {
        return "%pagination_item_number%";
    }

    @Override
    public String getValue(Context context) {
    
        // Using the key PAGINATION_ITEM to retrieve the value of the current item in the pagination.
        // The variable type depends on the data type paginated.
        Integer number = context.getData(CommonContextKey.PAGINATION_ITEM.name(), Integer.class);
        
        return Integer.toString(number);
    }

    @Override
    public boolean accept(Context context) {
        
        // Checking that the pagination id has been provided.
        if(!context.hasData(CommonContextKey.PAGINATION_ID.name())) {
            return false;
        }
        
        // Retrieving the pagination id.
        String paginationId = context.getData(CommonContextKey.PAGINATION_ID.name(), String.class);
        
        // Comparing ids and checking that there is a pagination item in the context.
        return paginationId.equals(this.paginationId) && context.hasData(CommonContextKey.PAGINATION_ITEM.name());
    }
}