Since version 1.8 the plugin supports auto-generation of menus.
The menu is generated like this:
1) The catalog of objects is taken. It can contain additional parameters for filtering objects, etc.
2) A matrix of cells is set, into which items from the catalog will be placed according to the template. The matrix should have as many rows as the menu itself.
3) One or more item templates are set. It is in these items that the necessary placeholders from the catalog are indicated.
4) The constructed menu can have several pages. Special actions are used to navigate the pages.
The catalogs are listed below. Here we will show you how to create a simple generated menu. We will use the PLAYERS directory, which generates a list of all the players that are on the server.
```hocon
title:"Generated Menu"
size:4
# Object catalog data to generate
catalog{
# Name of the registered directory
type:PLAYERS
}
# A matrix of cells that will be used to generate
matrix{
# Templates for matrix
templates{
"x"{
skullOwner:"% ctg_player_name%"
name:"& 7Player & e% ctg_player_name%"
}
}
# This is a matrix of cells
cells:[
"_________",
"_xxxxxxx_",
"_xxxxxxx_",
"_________",
]
}
```
Here we have created a menu with 4 lines. Once we have specified the `catalog` parameter, the plugin will assume that our menu is auto-generated and will behave accordingly.
`templates` - This is a list of menu templates. There can be many such templates. Each matrix template must have its own tag. A tag is any Latin character from `a` to `z`, or a special character. After we have created the tag, inside it we can describe any menu item, as if we were doing it in the `items` block for the menu buttons. Note that we are not specifying a slot. This is because the slot is automatically detected when the menu is generated.
`cells` - This is a matrix of cells. It is essentially a list of strings. Each row of the matrix is a menu row. Each symbol represents an inventory slot. The `_` character (or any other character that is not in the `templates` templates) denotes an empty slot, that is, no item will be added to that inventory slot. The `x` character is the template tag that we defined earlier. This means that only the item of the template `x` and no other item can be added to this inventory slot.
As a result, with enough online, we will get such a menu.
Since there may be many objects in the provided directory, the menu is paginated when generated. To scroll through these pages, two new actions were created for the buttons: `pageNext` and `pagePrev`, which scroll the next and previous page respectively.
To add buttons for scrolling, you need to define a list of static buttons, as we do on a regular menu.
```hocon
title:"Generated menu"
size:4
# Object catalog data to generate
catalog{
# Name of the registered directory
type:PLAYERS
}
# A matrix of cells that will be used to generate
matrix{
templates{
"x"{
skullOwner:"%ctg_player_name%"
name:"&7Player & e%ctg_player_name%"
}
}
# This is a matrix of cells
cells:[
"_________",
"_xxxxxxx_",
"_xxxxxxx_",
"_________",
]
}
# Regular buttons, not generated
items:[
{
slot:27
material:ARROW
name:"&e&l<<"
click{
// This action turns the previous page
pagePrev:1
}
},
{
slot:35
material:ARROW
name:"&e&l>>"
click{
// This action turns the next page
pageNext:1
}
}
]
```
Here we have specified the usual buttons with actions for turning the pages of the generated menu. These buttons will be displayed on all pages of the menu (unless we specify some rule for their display). Thus, we can specify any static items in which placeholders from the catalog will also work.
## <a name="placeholders"> Placeholders </a>
An important part of the auto-generated menu is special. placeholders. During menu generation, placeholders are generated for each directory object that can be used almost anywhere in the menu.
Catalog placeholders look like this:
```hocon
%ctg_<placeholder>%
```
Here `ctg` is a prefix, short for `catalog`. `<placeholder>` is a specific placeholder, which is usually written as `% <placeholder>%`, between the characters `%`.
Each directory has its own placeholders, you can find them under the description of each directory. However, there are also common placeholders that exist outside the directory. They are described below.
| Placeholder | Type | Description |
| ----------- | ---- | ----------- |
| `page` | Number | Current menu page |
| `pages` | Number | Number of menu pages |
| `page_next` | Number | Next menu page |
| `page_prev` | Number | Previous Menu Page |
| `elements` | Number | Total number of menu items |
For example, to use the persistent placeholder from this list, you would write `%ctg_page%`.
## <a name="catalogs"> Catalogs </a>
A directory is a collection of objects of the same type. Each directory has its own type (unique name), which is specified in the menu file.
The directory can also have additional. parameters that are specified in the same `catalog` block.
Each directory has its own placeholders. They can be used almost anywhere in the menu, including templates for generation. Below are the standard catalogs available from AbstractMenus.
> **Tip**: You can create your own directories using the API. This will integrate your plugin with AbstractMenus.
#### <a name="catalog-players"> Players </a>
Type: `PLAYERS`
Returns all the players on the server. Unlike other directories, it has no placeholders. Instead, you can use any placeholders, but in the format of directory placeholders, that is, with the `ctg_` prefix. During the generation of the menu, the placeholder will be replaced according to the player's object from the catalog, not the player who opened the menu. See the example below.
hocon
catalog {
type: PLAYERS
}
matrix {
templates {
"x" {
skullOwner: "%ctg_player_name%"
name: "Player level is %ctg_player_name%"
}
}
cells: [
"_________",
"_xxxxxxx_",
"_xxxxxxx_",
"_________",
]
}
``
That is, after the `ctg_` prefix, we can write any placeholder (without the `%` chars), and it will be replaced in the context of the player from the directory.
#### <a name="catalog-worlds"> Worlds </a>
Type: `WORLDS`
Returns all worlds on the server. Has the following placeholders:
| `world_type` | String | World type (flat, etc.) |
| `world_time` | Number | Time in the world |
| `world_difficulty` | String | Complexity of the World |
| `world_players` | Number | Number of players in the world |
| `world_entities` | Number | Number of entities in the world |
#### <a name="catalog-entities"> Entities </a>
Type: `ENTITIES`
Returns all entities in the world the player is in. Has an additional parameter to search for entities of a certain type only.
`allowedTypes` - List of strings. If this parameter is specified, only entities of the specified types are returned. See the entity types here: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/entity/EntityType.html
| `server_online` | Number | Number of players on the server |
#### <a name="catalog-iterator"> Iterator </a>
Type: `ITERATOR`
Returns a generated list of numbers from A to B. Useful for generating an exact number of items from a pattern.
Has three parameters:
`start` - Number. Seed (inclusive)
`end` - Number. Final number (inclusive)
`desc` - Optional. true/false. If true, numbers will be generated in reverse order. That is, if `start` is 1, and` end` is 10, then it will generate `10, 9, 8, ..., 1`
Standard placeholders (not directory placeholders) can be used in these parameters. This means that you can use, for example, the value of a variable.
So far, these are all available directories. In general, the catalog system is designed for independent expansion by the user to suit his needs. Regardless, standard catalogs will be added and modified over time.
