Categories, Middlewares and Afterwares

🍳 Categories, Middlewares and Afterwares

Velen offers three features that reduce the amount of code that you need to use, and these three are called "categories", "middleware" and "afterware" which we will be going into depth in a bit. If you want to view an example ahead of time, feel free to click here.

🧑‍⚖️ Middlewares

Middlewares are like judges, they intercept commands before it reaches completion, deciding whether the user executing the command meets the conditions needed for the command or not. Middlewares, as its name implies, is executed between the moment Discord sends the event to the bot and the moment before the command is executed which gives you the power to choose whether to stop the user from moving forward or not.

This is inspired by Laravel's implementation wherein you have to specify whether to allow the command to execute or not. An example of a middleware is:

🔴 We do not recommend using middleware for logging command execution, etc. Please use afterwares instead, but for the sake of simplicity of the example, we will use it here.

velen.addHybridMiddleware("log_command", (event, arguments, command, gate) -> {
    System.out.println(event.getUser().getId() + " executed " + command.getName());
    return gate.allow();
});

velen.addMessageMiddleware("log_command", (event, command, options, gate) -> {
    System.out.println(event.getMessageAuthor().getId() + " executed " + command.getName());
    return gate.allow();
});

velen.addSlashMiddleware("log_command", (event, command, gate) -> {
    System.out.println(event.getSlashCommandInteraction().getUser().getId() + " executed " + command.getName());
    return gate.allow();
});

As seen, there are always three arguments that are consistently on middleware: command, event, and the most important part: gate. A gate has one purpose and that is to tell Velen whether to continue on with performing this command or not. Please note that you may have to use event#respondLater for slash commands if you are using long-running tasks.

To explain the gate function, we have to take a look at its three methods:

allow();
deny();
deny(String reason);

If it wasn't obvious so far, the methods of gate allow YOU to specify whether to let the command continue or not and if you should deny, you can also specify a message that Velen will send to the user (as ephemeral if slash command).

You can add middleware to your commands or categories by adding this one piece of line:

middleware: name_of_middleware

🪐 Afterwares

Afterwares is a similar implementation to Middlewares, but instead of being executed between, afterwares are executed AFTER a command was executed (with executed being the event being dispatched to your code from Velen). You can think of this as "aftershocks" and this generally contains the event. BUT, do note that the responder methods for slash commands may end up useless at that point and may cause you errors. The event argument should just be meant for fetching information such as the user id and so forth.

An example of an afterware is:

velen.addHybridAfterware("hybrid.log_command",
                (event, arguments, command) -> System.out.println(event.getUser().getId() + " used the command : " + command.getName()));

velen.addMessageAfterware("message.log_command",
                (event, command, options) -> System.out.println(event.getMessageAuthor().getId() + " used the command : " + command.getName()));

velen.addSlashAfterware("slash.log_command",
                (event, command) -> System.out.println(event.getSlashCommandInteraction().getUser().getId() +
                        " used the command : " + command.getName()));

You can add afterwares to your commands or categories by adding this one piece of line:

afterware: name_of_afterware

🎲 Categories

A category is a mean of grouping a cluster of commands under a name, description while having similar settings (middleware and afterware). There are many different uses of a category such as a help command where the user specified a category to look, and so forth. To create a category, all you need to do is create a .vecomp file (you can also use the pure Java way which I will go into in a bit).

To view the example for a .vecomp file, please click here.

You can also create categories through pure Java by using the VelenCategoryBuilder class, for example:

VelenCategory category = new VelenCategoryBuilder()
                        .setName("someCategoryName")
                        .setDescription("This is a category.")
                        .addMiddleware("test")
                        .create(velen);