Pagination

JDA-Chewtils offers the same pagination as JDA-Utilities, plus 2 exclusive new types. Three have been deprecated, so the supported ones will be shown with examples below.

Building a Paginator

First, you must build and add elements to your paginator. The supported types are follows:

• Paginator
• EmbedPaginator
• ButtonEmbedPaginator

Once your paginator has been built, you'll want to display your paginator.

Paginator

This is the basic paginator type. It only accepts a list of Strings to page through. Overall, it's very basic. Pagination is through reactions, and not with native Discord buttons.

A basic paginator can be instantiated like this:

Paginator.Builder paginatorBuilder = new Paginator.Builder().setColumns(1)
  .setItemsPerPage(10) // Only show 10 items on a single page
  .showPageNumbers(true) // Show page numbers on the bottom
  .waitOnSinglePage(false) // Do nothing if there's only 1 page
  .useNumberedItems(false) // Don't number items
  .setFinalAction(m -> {
    try {
      m.clearReactions().queue();
    } catch(PermissionException ignored) { }
  }) // Clear reactions when time out is reached
  .setEventWaiter(eventWaiter) // Your JDA Event Waiter. This MUST be added with jda.addEventListener()
  .setTimeout(1, TimeUnit.MINUTES) // The timeout before it stops listening for pagination
  .clearItems(); // Clear the items to start adding

Now, you can add string items with paginatorBuilder.addItems("My Item"); You can also add text with .setText() and the embed color with .setColor(). View the paginator javadocs to see all methods.

Embed Paginator

Embed Paginator is similar to the normal paginator, however, you supply full MessageEmbeds, giving you more control of what you will show. Much like Paginator, you navigate with reactions.

A sample instantiation is as follows:

EmbedPaginator.Builder paginatorBuilder = new EmbedPaginator.Builder()
  .waitOnSinglePage(false) // If there is a single page, do nothing
  .setFinalAction(m -> {
    try {
      m.clearReactions().queue();
    } catch(PermissionException | IllegalStateException ignored) { }
  }) // Clear reactions when timeout is reached
  .setEventWaiter(eventWaiter) // Your JDA Event Waiter. This MUST be added with jda.addEventListener()
  .setTimeout(1, TimeUnit.MINUTES) // The timeout before it stops listening for pagination
  .clearItems(); // Clear the items to start adding

Now, you can add embeds with paginatorBuilder.addItems(). View the EmbedPaginator javadocs to see all the methods.

Button Embed Paginator

The ButtonEmbedPaginator is exactly like the normal EmbedPaginator; however, it uses Discord's native buttons instead of reactions, and is generally recommended because of this reason.

A sample instantiation can be seen below:

ButtonEmbedPaginator.Builder paginatorBuilder = new ButtonEmbedPaginator.Builder()
  .waitOnSinglePage(false) // If a single page, do nothing
  .setFinalAction(m -> m.editMessageComponents().queue()) // Clear the buttons when the timeout is reached
  .setEventWaiter(eventWaiter) // Your JDA Event Waiter. This MUST be added with jda.addEventListener()
  .setTimeout(1, TimeUnit.MINUTES) // The timeout before it stops listening for pagination
  .clearItems(); // Clear the items to start adding

Now, you can add your Embeds exactly the same as with EmbedPaginator. See ButtonEmbedPaginator javadocs for all possible methods.

Displaying Your Paginator

Once you have added all your items, run Paginator paginator = paginatorBuilder.build(); to build it. Replace Paginator with whatever one you decided to use. You have 3 ways of showing the Paginator:

1. Editing an existing message
2. Sending a new message
3. Responding to an interaction hook

Editing An Existing Message

If the bot has sent a message, such as a "Loading!" message with event.reply(), you can supply this message to have the bot edit that message. For example:

event.reply("Loading!", m -> {
  // build the paginator //

  Paginator paginator = paginatorBuilder.build();

  paginator.display(m);
});

Sending A New Message

You can also send a new message entirely by supplying a channel to send the message to. For example:

// build the paginator //

Paginator paginator = paginatorBuilder.build();

paginator.display(event.getChannel());

Responding To An Interaction Hook

If your bot uses slash commands, you can do the following to easily create an embed after you defer reply or send a loading message:

// build your paginator //

event.deferReply().queue(paginator::display);