---
description: This page describes how to create and register custom placeholders.
---

# 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:

<pre class="language-java"><code class="lang-java"><strong>public class PlayerPingPlaceholder implements Placeholder {
</strong>
    @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());
    }
}
</code></pre>

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

<table><thead><tr><th width="281">Method name</th><th>Description</th></tr></thead><tbody><tr><td><code>String getName()</code></td><td>Returns the name of the placeholder. It is recommended to use the format <code>%placeholder_name%</code>.</td></tr><tr><td><code>String getValue(Context context)</code></td><td>Returns the value the placeholder for the provided context.</td></tr><tr><td><code>boolean accept(Context context)</code></td><td>Check that the placeholder can be applied using the provided context.</td></tr></tbody></table>

> Note: Some of these methods relies on a `Context` that is explained in the [Context page](context).&#x20;

### 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:

```java
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`:

```java
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());
    }
}
```
