knht / eris-pagination

🔀 An extremely easy to use Embed Paginator for the Eris Discord Library

Eris Pagination

Eris Pagination is a super simple to use Embed Paginator for the Node.js Discord library Eris.

The API is very straight forward but also offers a big amount of customizability as well!

Getting Started

Simply install Eris Pagination via NPM by typing npm install eris-pagination into your existing project and require the module wherever you need. That's it!

API

There's only a single asynchronous method needed for creating paginated Embeds with Eris:

EmbedPaginator.createPaginationEmbed(message, embeds, options);

Returns: Promise<Eris.Message> - The createPaginationEmbed method will return a Promise which resolves with an Eris.Message object of the paginated Embed. (E.g. to manually tinker with the paginator message).

Parameters:

• Eris.Message message - An Eris message emitted from the messageCreate event.
• Object[] embeds - An array containing all Embed objects you want to use with the paginator.
• Object options - An object containing optional settings to overwrite the default behavior of Eris Paginator.
  • Boolean options.showPageNumbers - Whether to show "Page n of m" over the Embed.
    • Optional: Yes
    • Default: True
  • Boolean options.extendedButtons - Whether to show advanced pagination buttons (Jump to First & Last page)
    • Optional: Yes
    • Default: False
  • Boolean options.cycling - Cycle through all embeds jumping from the first page to the last page on going back and from the last page to the first page going forth.
    • Optional: Yes
    • Default: False
  • Number options.startPage - Which page (element) of the provided array to show first initially.
    • Optional: Yes
    • Default: 1
  • Number options.maxMatches - Maximum amount of reaction button clicks to listen for.
    • Optional: Yes
    • Default: 50
    • Maximum: 100
  • Number options.timeout - Duration for how long the pagination embed should work for.
    • Optional: Yes
    • Default: 300000 (5 minutes)
    • Maximum: 900000 (15 minutes)
  • String options.firstButton - Emoji used as the first page button. Must be Unicode!
    • Optional: Yes
    • Default: ⏮
  • String options.backButton - Emoji used as the back button. Must be Unicode!
    • Optional: Yes
    • Default: ⬅
  • String options.forthButton - Emoji used as the forth button. Must be Unicode!
    • Optional: Yes
    • Default: ➡
  • String options.lastButton - Emoji used as the last page button. Must be Unicode!
    • Optional: Yes
    • Default: ⏭
  • String options.deleteButton - Emoji used as the delete button. Must be Unicode!
    • Optional: Yes
    • Default: 🗑

Notice: The Delete button does not delete the whole embed. It removes every reaction and resolves with an empty Promise!

Examples

Simple paginator without additional options:

const Eris = require('eris');
const EmbedPaginator = require('eris-pagination');
const bot = new Eris('BOT_TOKEN');

bot.on('ready', () => {
    console.log('Ready!');
});

bot.on('messageCreate', async (message) => {
    if (message.content === '!test') {
        const myEmbeds = [
            { title: 'Test Embed 1', color: 0x2ECC71 },
            { title: 'Test Embed 2', color: 0xE67E22 },
            { title: 'Test Embed 3', color: 0xE74C3C }
        ];

        const paginatedEmbed = await EmbedPaginator.createPaginationEmbed(message, myEmbeds);
        /* paginatedEmbed ⇨ Eris.Message */
    }
});

bot.connect();

---

Advanced paginator with overwriting options:

const Eris = require('eris');
const EmbedPaginator = require('eris-pagination');
const bot = new Eris('BOT_TOKEN');

bot.on('ready', () => {
    console.log('Ready!');
});

bot.on('messageCreate', async (message) => {
    if (message.content === '!test') {
        const myEmbeds = [
            { title: 'Test Embed 1', color: 0x2ECC71 },
            { title: 'Test Embed 2', color: 0xE67E22 },
            { title: 'Test Embed 3', color: 0xE74C3C }
        ];

        const paginatedEmbed = await EmbedPaginator.createPaginationEmbed(
            message, 
            myEmbeds, 
            {
                showPageNumbers: false,
                extendedButtons: true,
                maxMatches: 10,
                timeout: 150000,
                backButton: '◀',
                forthButton: '▶',
                deleteButton: '💩',
                startPage: 2
            }
        );
        /* paginatedEmbed ⇨ Eris.Message */
    }
});

bot.connect();

License

This repository makes use of the MIT License and all of its correlating traits.

While it isn't mandatory, a small credit if this repository was to be reused would be highly appreciated!

eris-pagination's Issues

How to get these page numbers in Embed Footer

I want the page number in the embed footer, How to do that?

Isn’t Working

I bought this issue up in the DAPI server, and I believe someone mentioned about it just not working when so I was having issues.

https://hastebin.com/sezihudude.yaml

This is the code I tried, simply doesn't edit through the two pages, other than that the other features work fine

Discord Buttons

Is this able to be updated to add support for the new buttons feature?

Pagination in DM throws an error.

When the bot tries to remove a users reaction after they react on a pagination message, Discord responds with "DiscordRESTError [50003]: Cannot execute action on a DM channel" and nothing happens.