public class CustomInventoryDescriptor implements InventoryDescriptor {

    public static final String INVENTORY_ID = "custom-inventory";
    private static final String INVENTORY_CONFIG_PATH = "menus/waypoint-icons-menu.yml";

    private final Plugin plugin;
    private final InventoryConfigDAO inventoryConfigDAO;

    public CustomInventoryDescriptor(Plugin plugin, InventoryConfigDAO inventoryConfigDAO) {
        this.plugin = plugin;
        this.inventoryConfigDAO = inventoryConfigDAO;
    }

    @Override
    public String getInventoryResourceFile() {
        // Path to the configuration file of the inventory in the plugin's resources.
        return INVENTORY_CONFIG_PATH;
    }

    @Override
    public Path getInventoryConfigFile() {
        // Path to the inventory configuration file in the plugin's folder.
        return Paths.get(this.plugin.getDataFolder() + File.separator + INVENTORY_CONFIG_PATH);
    }

    @Override
    public String getInventoryId() {
        // This id must be unique. t is also recommended to only use the 
        // following characters: A-Z, a-z, 0-9, -, _.
        return INVENTORY_ID;
    }

    @Override
    public InventoryConfigDAO getInventoryConfigDAO() {
        return this.inventoryConfigDAO;
    }
}

public class CraftVentoryPlugin extends JavaPlugin {

    private InventoryService inventoryService;

    @Override
    public void onEnable() {
        this.inventoryService = CraftVentoryLibrary.createInventoryService(this);
        this.loadInventoryProviders();
    }

    private void loadInventoryProviders() {

        ClickActionLoaderFactory<ConfigurationSection> factory =
                FastInventoryLibrary.createDefaultClickActionLoaderFactory();

        InventoryConfigDAO dao = FastInventoryLibrary.createDefaultConfigDAO(factory);

        // Register inventory providers here.
        this.inventoryService.createProvider(new CustomInventoryDescriptor(this, dao));
    }
}

close:
  # Item configuration section.
  # See the 'Item configuration' chapter of this tutorial.
  item:
    type: BARRIER
  # Symbol of the item to place it in the inventory.
  symbol: "C"
  # Set of actions executed when a player clicks on the item.
  actions:
      # Action name.
    - action: "CLOSE"
      # Additionnal properties may be listed below depending on the action.

actions:
    # Action name.
  - action: "CLOSE"

actions:
    # Action name.
  - action: "MESSAGE"
    # List of messages to send.
    # Features supported:
    # - Placeholders
    # - Color codes prefixed by the character '&' (ex: &e)
    # - Hexadecimal color codes prefixed by the character '#' (ex: #FFFFFF)
    messages: 
      - "message 1"
      - "message 2"
      - "message 3"

actions:
    # Action name.
  - action: "BROADCAST"
    # List of messages to broadcast.
    # Features supported:
    # - Placeholders
    # - Color codes prefixed by the character '&' (ex: &e)
    # - Hexadecimal color codes prefixed by the character '#' (ex: #FFFFFF)
    messages:
      - "message 1"
      - "message 2"
      - "message 3"

actions:
    # Action name.
  - action: "PLAYER_COMMAND"
    # List of commands to execute without slash.
    # Supported placeholders:
    # - %player_name%: Name of the player who executes the action.
    # - %player_uuid%: UUID of the player who executes the action.
    commands: 
      - "command_1"
      - "command 2 arg1"
      - "command 3 arg1 arg2 arg3"

actions:
    # Action name.
  - action: "CONSOLE_COMMAND"
    # List of commands to execute without slash.
    # Supported placeholders:
    # - %player_name%: Name of the player who executes the action.
    # - %player_uuid%: UUID of the player who executes the action.
    commands: 
      - "command_1"
      - "command 2 arg1"
      - "command 3 arg1 arg2 arg3"

actions:
    # Action name.
  - action: "SOUND"
    # Sound name to play.
    sound: "<name>"
    # How far the sound can be heard.
    volume: <float>
    # How fast the sound is played.
    pitch: <float>

actions:
    # Action name.
  - action: "UPDATE_CONTENT"

actions:
    # Action name.
  - action: "UPDATE_PAGINATIONS"
    # The ids of the paginations to update.
    pagination-ids:
      - <pagination-id-1>
      - <pagination-id-2>
      - <pagination-id-3>

actions:
    # Action name.
  - action: "OPEN_INVENTORY"
    # The id of the inventory to open.
    inventory-id: "<id>"
    # If true, a new history will be created for the inventory.
    # If false, the inventory will be appended at the end of it. 
    new-history: <true|false>

actions:
    # Action name.
  - action: "HOME"

actions:
    # Action name.
  - action: "BACKWARD"
    # This property is optional. When set, the action opens the previously opened inventory before the current
    # one which has the specified id. When not set, the inventory just before the current one in the history is opened.
    inventory-id: ""

actions:
    # The action name.
  - action: "FORWARD"
    # This property is optional. When set, the action opens the previously opened inventory after the current
    # one which has the specified id. When not set, the inventory just after the current one in the history is opened.
    inventory-id: ""

# List of click types to execute the action.
# Allowed click types:
# - LEFT: Left click
# - RIGHT: Right click
# - MIDDLE: Middle click
# You can use a combination of the above values.
# When this property is not set, all the click types are allowed.
click-types:
  - "LEFT"
  - "RIGHT"

actions:  
  - action: "MESSAGE"
    click-types:
      - "LEFT"
    messages: 
      - "left click"
      
  - action: "MESSAGE"
    click-types:
      - "RIGHT"
    messages: 
      - "right click"
  
  - action: "MESSAGE"
    click-types:
      - "MIDDLE"
    messages: 
      - "middle click"
      
  - action: "MESSAGE"
    messages: 
      - "message sent for each click"

inventory-id: "warp-inventory"

type: "CHEST_9x6"

title: "&6Warps"

pattern:
  - "OOOOOOOOO"
  - "OYYWWWYYO"
  - "OY1W2W3YO"
  - "OYW4W5WYO"
  - "OYYWWWYYO"
  - "OOOOOOOOC"

content:
  orange-stained-glass:
    item:
      type: ORANGE_STAINED_GLASS_PANE
      display-name: " "
    symbol: "O"
  yellow-stained-glass:
    item:
      type: YELLOW_STAINED_GLASS_PANE
      display-name: " "
    symbol: "Y"
  white-stained-glass:
    item:
      type: WHITE_STAINED_GLASS_PANE
      display-name: " "
    symbol: "W"
  warp-world:
    item:
      type: GRASS_BLOCK
      display-name: "&aOverworld"
      lore:
        - ""
        - "&fClick to be teleported to the overworld."
    symbol: "1"
    actions:
      - action: "CLOSE"
      - action: "PLAYER_COMMAND"
        command: "warp overworld"
  warp-nether:
    item:
      type: NETHERRACK
      display-name: "&cNether"
      lore:
        - ""
        - "&fClick to be teleported to the nether."
    symbol: "2"
    actions:
      - action: "CLOSE"
      - action: "PLAYER_COMMAND"
        command: "warp nether"
  warp-end:
    item:
      type: END_STONE
      display-name: "&5End"
      lore:
        - ""
        - "&fClick to be teleported to the End."
    symbol: "3"
    actions:
      - action: "CLOSE"
      - action: "PLAYER_COMMAND"
        command: "warp end"
  warp-mining:
    item:
      type: "IRON_ORE"
      display-name: "&7Mining"
      lore:
        - ""
        - "&fClick to be teleported to the mining world."
    symbol: "4"
    actions:
      - action: "CLOSE"
      - action: "PLAYER_COMMAND"
        command: "warp mining"
  warp-enchant:
    item:
      type: ENCHANTING_TABLE
      display-name: "&5Enchantment"
      lore:
        - ""
        - "&fClick to be teleported to the enchantment room."
    symbol: "5"
    actions:
      - action: "CLOSE"
      - action: "PLAYER_COMMAND"
        command: "warp enchant"
  close:
    item:
      type: BARRIER
      display-name: "&cClose"
    symbol: "C"
    actions:
      - action: "CLOSE"

# An id that uniquely identify the inventory.
inventory-id: "inventory-id"

# The type of view that will be used for the inventory.
# Available types:
# - CHEST_9x1 (1 row)
# - CHEST_9x2 (2 rows)
# - CHEST_9x3 (3 rows)
# - CHEST_9x4 (4 rows)
# - CHEST_9x5 (5 rows)
# - CHEST_9x6 (6 rows)
# - DROPPER
# - HOPPER
type: "CHEST_9x6"

# The title of the inventory.
# The following placeholders are available by default:
# - %player_name% : The name of the player who is viewing the inventory.
# - %inventory_type% : The name of the inventory type.
# - %inventory_size% : The number of slots of the inventory.
title: "title"

# The pattern of the inventory used to set items.
# A pattern must have the exact same number of rows and columns than the inventory.
# Items are represented by their associated symbol in the pattern.
# The symbol '&' must be used to represent an empty slot.
pattern:
  - "&&&&&&&&&"
  - "&1111111&"
  - "&1111111&"
  - "&1111111&"
  - "&P&&&&&N&"
  - "&&&&&&&&C"

# The content of the inventory.
# You can add as many items as you want.
content:
  # Each item is described by a section.
  close:
    # The item to display.
    # You can use the default YAML representation supported by Bukkit to define an ItemStack
    # or the custom one provided by the library.
    item:
      type: BARRIER
    # Symbol used in the pattern to place the item in the inventory.
    # You must ensure that two items do not have the same symbol.
    symbol: "C"
    # Actions executed when a player clicks on the item.
    # Each action is described by a new element in the list.
    actions:
      # The name of the action.
      - action: "CLOSE"

# Paginations used in the inventory.
# An inventory can contain several paginations.
paginations:
  # Each pagination is described by a section.
  pagination-1:
    # The internal id of the pagination.
    # It must be unique for the inventory, as an inventory can contain several paginations.
    id: "pagination-1"
    # The symbol used in the pattern to place the pagination items in the inventory.
    symbol: "1"
    # The item used to represent each value of the pagination.
    # The Bukkit ItemStack representation must be used.
    pagination-item:
      item:
        type: DIAMOND
    # Item to open the previous page.
    # It is configured like items in the 'content' section.
    previous-page-item:
      # Item displayed when a previous page is available.
      navigation-item:
        item:
          type: ARROW
          # The following placeholders are available by default and can be used in name and lore:
          # %previous_page%: Previous page number.
          # %current_page%: Current page number.
          # %total_pages%: Total number of pages.
          name: "Page %previous_page%"
      symbol: "P"
    # Item to open the next page.
    # It is configured like items in the 'content' section.
    next-page-item:
      # Item displayed when a next page is available.
      navigation-item:
        item:
          type: ARROW
          # The following placeholders are available by default and can be used in name and lore:
          # %next_page%: Next page number.
          # %current_page%: Current page number.
          # %total_pages%: Total number of pages.
        name: "Page %next_page%"
      symbol: "N"

InventoryService inventoryService = ... ;
Player player = ... ;

// Retrieve the InventoryViewer instance associated to a player.
InventoryViewer viewer = inventoryService.getInventoryViewer(player);

InventoryService inventoryService = ... ;

// Retrieve the provider for an inventory.
Optional<InventoryProvider> optional = inventoryService.getProvider("inventory-id");

InventoryService inventoryService = ... ;
Player player = ... ;

InventoryViewer viewer = inventoryService.getInventoryViewer(player);

inventoryService.getProvider("inventory-id").ifPresent(provider -> {
    CraftVentory inventory = provider.createInventory(this.service, player);
    viewer.getViewManager().openView(inventory);
});

public class CommandAction implements ClickAction {

    public static final String ACTION_NAME = "EXECUTE_COMMAND";

    private final String command;

    public CommandAction(String command) {

        if(command == null || command.isEmpty()) {
            throw new IllegalArgumentException("command cannot null or empty");
        }

        this.command = command;
    }

    @Override
    public void execute(FastInventoryClickEvent event) {
        Player player = event.getPlayer();
        player.performCommand(this.command);
    }

    @Override
    public String getName() {
        return ACTION_NAME;
    }
}

public class CommandActionLoader implements ClickActionLoader<ConfigurationSection> {

    private static final String COMMAND_KEY = "command";

    @Override
    public ClickAction load(ConfigurationSection section) throws InventoryConfigException {

        if(!section.isString(COMMAND_KEY)) {
            throw new InventoryConfigException(String.format("Property '%s' not found or not a string at '%s'", COMMAND_KEY, section.getCurrentPath()));
        }

        String command = section.getString(COMMAND_KEY);

        if(command.startsWith("/")) {
            command = command.substring(1);
        }

        return new CommandAction(command);
    }

    @Override
    public String getName() {
        return CommandAction.ACTION_NAME;
    }
}

ClickActionLoaderFactory<ConfigurationSection> factory = FastInventoryLibrary.createDefaultClickActionLoaderFactory();
factory.addLoader(new CommandActionLoader());

Hook<FastInventoryBeforeOpenEvent> hook = event -> {
    System.out.println("Hook called before opening the inventory");
};

public class CustomInventoryDescriptor implements InventoryDescriptor {
    
    ...
    
    @Override
    public void addHooks(HookManager manager) {

        manager.addHook("before-open", FastInventoryBeforeOpenEvent.class, event -> {
            System.out.println("Hook called before opening the inventory.");
        });

        manager.addHook("after-open", FastInventoryAfterOpenEvent.class, event -> {
            System.out.println("Hook called after the inventory has been opened.");
        });

        manager.addHook("close", FastInventoryCloseEvent.class, event -> {
            System.out.println("Hook called when the inventory is closed.");
        });

        manager.addHook("click", FastInventoryClickEvent.class, event -> {
            System.out.println("Hook called when the inventory viewer clicks on an item in the inventory.");
        });
    }
    
    ...

}

Enhancement<PaginationItemDto> enhancement = new Enhancement<>() {

    @Override
    public void enhance(PaginationItemDto dto, Context context) {
        
        // We only want to enhance the pagination with id 'pagination-1'.
        if(!dto.getPaginationId().equals("pagination-1")) {
            return;
        }
        
        // Enhancing the pagination item. If the slot is even, then setting a diamond.
        // If it is odd, setting an emerald.
        Integer slot = context.getData(CommonContextKey.SLOT.name(), Integer.class);
        Material material = slot % 2 == 0 ? Material.DIAMOND : Material.EMERALD;
        
        dto.getItem().setType(material);
    }

    @Override
    public Class<PaginationItemDto> getDTOClass() {
        // The class of the DTO the enhancement manipulates.
        return PaginationItemDto.class;
    }

    @Override
    public String getId() {
        // The unique id of the enhancement.
        return "pagination-1-item-enhancement";
    }
};

public class CustomInventoryDescriptor implements InventoryDescriptor {

    ...

    @Override
    public void addEnhancements(EnhancementManager manager) {
    
        Enhancement<PaginationItemDto> enhancement = new Enhancement<>() {

            @Override
            public void enhance(PaginationItemDto dto, Context context) {

                if(!dto.getPaginationId().equals("pagination-1")) {
                    return;
                }

                Integer slot = context.getData(CommonContextKey.SLOT.name(), Integer.class);
                Material material = slot % 2 == 0 ? Material.DIAMOND : Material.EMERALD;

                dto.getItem().setType(material);
            }

            @Override
            public Class<PaginationItemDto> getDTOClass() {
                return PaginationItemDto.class;
            }

            @Override
            public String getId() {
                return UUID.randomUUID().toString();
            }
        };
        
        manager.addEnhancement(DtoNameEnum.PAGINATION_ITEM.name(), enhancement);
    }

    ...

}

InventoryService service = CraftVentoryLibrary.createInventoryService(Plugin plugin);

// Factory used to load item click actions.
ClickActionLoaderFactory<ConfigurationSection> factory =
        FastInventoryLibrary.createDefaultClickActionLoaderFactory();

InventoryConfigDAO dao = FastInventoryLibrary.createDefaultConfigDAO(factory);

public class CraftVentoryPlugin extends JavaPlugin {

    private InventoryService inventoryService;

    @Override
    public void onEnable() {
        this.inventoryService = CraftVentoryLibrary.createInventoryService(this);
        this.loadInventoryProviders();
    }

    private void loadInventoryProviders() {

        ClickActionLoaderFactory<ConfigurationSection> factory =
                FastInventoryLibrary.createDefaultClickActionLoaderFactory();

        InventoryConfigDAO dao = FastInventoryLibrary.createDefaultConfigDAO(factory);

        // Register inventory providers here.
    }
}

List<Integer> values = new ArrayList<>();

for(int i = 0; i < 50; i++) {
    values.add(i);
}

public class CustomInventoryDescriptor implements InventoryDescriptor {

    ...

    @Override
    public void addProviders(ProviderManager manager) {

        List<Integer> values = new ArrayList<>();

        for(int i = 0; i < 50; i++) {
            values.add(i);
        }
        
        manager.addProvider(new PaginationProvider<>("pagination-1", Integer.class, inventory -> values));
    }
    
    ...
} 

inventory-id: "custom-inventory"

type: "CHEST_9x6"

title: "&6Custom title"

pattern:
  - "&&&&&&&&&"
  - "&1111111&"
  - "&1111111&"
  - "&1111111&"
  - "&P&&&&&N&"
  - "&&&&&&&&C"

content:
  close:
    item:
      type: BARRIER
    symbol: "C"
    actions:
      - action: "CLOSE"

paginations:
  pagination-1:
    id: "pagination-1"
    symbol: "1"
    pagination-item:
      item:
        type: DIAMOND
        display-name: "Item n°%pagination_item_number%"
    previous-page-item:
      navigation-item:
        item:
          type: ARROW
          display-name: "Page %previous_page%"
      symbol: "P"
    next-page-item:
      navigation-item:
        item:
          type: ARROW
          display-name: "Page %next_page%"
      symbol: "N"

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

public class CustomInventoryDescriptor implements InventoryDescriptor {  

    ... 

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

    ...
}

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