Class: PaginatedMessageEmbedFields
discord.js-utilities/src.PaginatedMessageEmbedFields
This is a utility of PaginatedMessage, except it exclusively paginates the fields of an embed. You must either use this class directly or extend it.
It differs from PaginatedFieldMessageEmbed as the items here are whole fields, that are added to the embed, whereas PaginatedFieldMessageEmbed concatenates the items in a single field with a given formatter function.
example
import { PaginatedMessageEmbedFields } from '@sapphire/discord.js-utilities';
new PaginatedMessageEmbedFields()
.setTemplate({ title: 'Test pager embed', color: '#006080' })
.setItems([
{ name: 'Sapphire Framework', value: 'discord.js Framework' },
{ name: 'Sapphire Framework 2', value: 'discord.js Framework 2' },
{ name: 'Sapphire Framework 3', value: 'discord.js Framework 3' }
])
.setItemsPerPage(2)
.make()
.run(message);
Hierarchy
↳
PaginatedMessageEmbedFields
Constructors
constructor
• new PaginatedMessageEmbedFields(__namedParameters?)
Constructor for the PaginatedMessage class
Parameters
| Name | Type | Description |
|---|---|---|
__namedParameters | PaginatedMessageOptions | The PaginatedMessageOptions for this instance of the PaginatedMessage class |
Inherited from
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:224
Properties
#thisMazeWasNotMeantForYouContent
• Private #thisMazeWasNotMeantForYouContent: Object
The response we send when someone gets into an invalid flow
Type declaration
| Name | Type |
|---|---|
content | string |
Inherited from
PaginatedMessage.#thisMazeWasNotMeantForYouContent
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:119
actions
• actions: Map<string, PaginatedMessageAction>
The actions which are to be used.
Inherited from
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:145
collector
• collector: null | InteractionCollector<MessageComponentInteraction<CacheType>> = null
The collector used for handling component interactions.
Inherited from
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:135
constructor
• constructor: typeof PaginatedMessage
Inherited from
PaginatedMessage.constructor
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:1523
embedFooterSeparator
• embedFooterSeparator: string = PaginatedMessage.embedFooterSeparator
Custom separator to show after the page index in the embed footer.
PaginatedMessage will automatically add a space ( ) after the given text. You do not have to add it yourself.
default PaginatedMessage.embedFooterSeparator (static property)
Inherited from
PaginatedMessage.embedFooterSeparator
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:177
embedTemplate
• Private embedTemplate: MessageEmbed
Defined in
emitPartialDMChannelWarning
• emitPartialDMChannelWarning: boolean = PaginatedMessage.emitPartialDMChannelWarning
Whether to emit the warning about running a PaginatedMessage in a DM channel without the client having the 'CHANNEL' partial.
remark When using message based commands (as opposed to Application Commands) then you will also need to specify the DIRECT_MESSAGE intent for PaginatedMessage to work.
default PaginatedMessage.emitPartialDMChannelWarning (static property)
Inherited from
PaginatedMessage.emitPartialDMChannelWarning
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:191
hasEmittedMaxPageWarning
• Protected hasEmittedMaxPageWarning: boolean = false
Tracks whether a warning was already emitted for this PaginatedMessage concerning the maximum amount of pages in the {@link SelectMenu}.
Inherited from
PaginatedMessage.hasEmittedMaxPageWarning
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:207
hasEmittedPartialDMChannelWarning
• Protected hasEmittedPartialDMChannelWarning: boolean = false
Tracks whether a warning was already emitted for this PaginatedMessage
concerning the PaginatedMessage being called in a DMChannel
without the client having the 'Channel' partial.
remark When using message based commands (as opposed to Application Commands) then you will also need to specify the DIRECT_MESSAGE intent for PaginatedMessage to work.
Inherited from
PaginatedMessage.hasEmittedPartialDMChannelWarning
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:216
idle
• idle: number
The amount of milliseconds to idle before the paginator is closed.
default 14.5 minutes
remark This is to ensure it is a bit before interactions expire.
Inherited from
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:157
index
• index: number = 0
The handler's current page/message index.
Inherited from
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:150
items
• Private items: EmbedFieldData[] = []
Defined in
itemsPerPage
• Private itemsPerPage: number = 10
Defined in
messages
• messages: (null | PaginatedMessagePage)[] = []
The pages which were converted from PaginatedMessage.pages
Inherited from
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:140
pageIndexPrefix
• pageIndexPrefix: string = PaginatedMessage.pageIndexPrefix
Custom text to show in front of the page index in the embed footer.
PaginatedMessage will automatically add a space ( ) after the given text. You do not have to add it yourself.
default PaginatedMessage.pageIndexPrefix (static property)
Inherited from
PaginatedMessage.pageIndexPrefix
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:170
pages
• pages: PaginatedMessagePage[]
The pages to be converted to PaginatedMessage.messages
Inherited from
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:125
paginatedMessageData
• Protected paginatedMessageData: null | Omit<PaginatedMessageMessageOptionsUnion, "components"> = null
Inherited from
PaginatedMessage.paginatedMessageData
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:195
response
• response: null | Message<boolean> | APIMessage | CommandInteraction<CacheType> | ContextMenuInteraction<CacheType> | SelectMenuInteraction<CacheType> | ButtonInteraction<CacheType> = null
The response message used to edit on page changes.
Inherited from
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:130
selectMenuOptions
• Protected selectMenuOptions: PaginatedMessageSelectMenuOptionsFunction = PaginatedMessage.selectMenuOptions
Inherited from
PaginatedMessage.selectMenuOptions
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:197
selectMenuPlaceholder
• Protected selectMenuPlaceholder: undefined | string = undefined
Inherited from
PaginatedMessage.selectMenuPlaceholder
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:199
stopPaginatedMessageCustomIds
• stopPaginatedMessageCustomIds: string[] = PaginatedMessage.stopPaginatedMessageCustomIds
A list of customId that are bound to actions that will stop the PaginatedMessage
default PaginatedMessage.stopPaginatedMessageCustomIds (static property)
Inherited from
PaginatedMessage.stopPaginatedMessageCustomIds
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:183
template
• template: PaginatedMessageMessageOptionsUnion
The template for this PaginatedMessage. You can use templates to set defaults that will apply to each and every page in the PaginatedMessage
Inherited from
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:163
totalPages
• Private totalPages: number = 0
Defined in
wrongUserInteractionReply
• Protected wrongUserInteractionReply: PaginatedMessageWrongUserInteractionReplyFunction = PaginatedMessage.wrongUserInteractionReply
Inherited from
PaginatedMessage.wrongUserInteractionReply
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:201
defaultActions
▪ Static defaultActions: PaginatedMessageAction[]
The default actions of this handler.
Inherited from
PaginatedMessage.defaultActions
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:1299
deletionStopReasons
▪ Static deletionStopReasons: string[]
The reasons sent by InteractionCollector#end event when the message (or its owner) has been deleted.
Inherited from
PaginatedMessage.deletionStopReasons
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:1384
embedFooterSeparator
▪ Static embedFooterSeparator: string = '•'
Custom separator for the page index in the embed footer.
default "•"
remark To overwrite this property change it somewhere in a "setup" file, i.e. where you also call client.login() for your client.
Alternatively, you can also customize it on a per-PaginatedMessage basis by passing embedFooterSeparator in the options of the constructor.
example
import { PaginatedMessage } from '@sapphire/discord.js-utilities';
PaginatedMessage.embedFooterSeparator = '|';
// This will make the separator of the embed footer something like "Page 1/2 | Today at 4:20"
Inherited from
PaginatedMessage.embedFooterSeparator
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:1414
emitPartialDMChannelWarning
▪ Static emitPartialDMChannelWarning: boolean = true
Whether to emit the warning about running a PaginatedMessage in a DM channel without the client the 'CHANNEL' partial.
remark When using message based commands (as opposed to Application Commands) then you will also need to specify the DIRECT_MESSAGE intent for PaginatedMessage to work.
remark To overwrite this property change it somewhere in a "setup" file, i.e. where you also call client.login() for your client.
Alternatively, you can also customize it on a per-PaginatedMessage basis by using paginatedMessageInstance.setEmitPartialDMChannelWarning(newBoolean)
default true
Inherited from
PaginatedMessage.emitPartialDMChannelWarning
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:1364
handlers
▪ Static Readonly handlers: Map<string, PaginatedMessage>
The current {@link InteractionCollector} handlers that are active. The key is the ID of of the author who sent the message that triggered this PaginatedMessage
This is to ensure that any given author can only trigger 1 PaginatedMessage. This is important for performance reasons, and users should not have more than 1 PaginatedMessage open at once.
Inherited from
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:1432
messages
▪ Static Readonly messages: Map<string, PaginatedMessage>
The messages that are currently being handled by a PaginatedMessage The key is the ID of the message that triggered this PaginatedMessage
This is to ensure that only 1 PaginatedMessage can run on a specified message at once. This is important when having an editable commands solution.
Inherited from
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:1423
pageIndexPrefix
▪ Static pageIndexPrefix: string = ''
Custom text to show in front of the page index in the embed footer.
PaginatedMessage will automatically add a space ( ) after the given text. You do not have to add it yourself.
default ""
remark To overwrite this property change it somewhere in a "setup" file, i.e. where you also call client.login() for your client.
example
import { PaginatedMessage } from '@sapphire/discord.js-utilities';
PaginatedMessage.pageIndexPrefix = 'Page';
// This will make the footer of the embed something like "Page 1/2"
Inherited from
PaginatedMessage.pageIndexPrefix
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:1399
selectMenuOptions
▪ Static selectMenuOptions: PaginatedMessageSelectMenuOptionsFunction
A generator for {@link MessageSelectOption} that will be used to generate the options for the {@link MessageSelectMenu}. We do not allow overwriting the {@link MessageSelectOption#value} property with this, as it is vital to how we handle select menu interactions.
param The index of the page to add to the {@link MessageSelectMenu}. We will add 1 to this number because our pages are 0 based,
so this will represent the pages as seen by the user.
default
{
label: `Page ${pageIndex}`
}
remark To overwrite this property change it in a "setup" file prior to calling client.login() for your client.
example
import { PaginatedMessage } from '@sapphire/discord.js-utilities';
PaginatedMessage.selectMenuOptions = (pageIndex) => ({
label: `Go to page: ${pageIndex}`,
description: 'This is a description'
});
Inherited from
PaginatedMessage.selectMenuOptions
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:1459
stopPaginatedMessageCustomIds
▪ Static stopPaginatedMessageCustomIds: string[]
A list of customId that are bound to actions that will stop the PaginatedMessage
default ['@sapphire/paginated-messages.stop']
remark To overwrite this property change it somewhere in a "setup" file, i.e. where you also call client.login() for your client.
Alternatively, you can also customize it on a per-PaginatedMessage basis by using paginatedMessageInstance.setStopPaginatedMessageCustomIds(customIds)
example
import { PaginatedMessage } from '@sapphire/discord.js-utilities';
PaginatedMessage.stopPaginatedMessageCustomIds = ['my-custom-stop-custom-id'];
Inherited from
PaginatedMessage.stopPaginatedMessageCustomIds
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:1378
wrongUserInteractionReply
▪ Static wrongUserInteractionReply: PaginatedMessageWrongUserInteractionReplyFunction
A generator for {@link MessageComponentInteraction#reply} that will be called and sent whenever an untargeted user interacts with one of the buttons.
When modifying this it is recommended that the message is set to be ephemeral so only the user that is pressing the buttons can see them.
Furthermore, we also recommend setting allowedMentions: { users: [], roles: [] }, so you don't have to worry about accidentally pinging anyone.
When setting just a string, we will add { ephemeral: true, allowedMentions: { users: [], roles: [] } } for you.
param The {@link User} this PaginatedMessage was intended for.
param The {@link User} that actually clicked the button.
default
{
content: `Please stop interacting with the components on this message. They are only for ${Formatters.userMention(targetUser.id)}.`,
ephemeral: true,
allowedMentions: { users: [], roles: [] }
}
remark To overwrite this property change it in a "setup" file prior to calling client.login() for your client.
example
import { PaginatedMessage } from '@sapphire/discord.js-utilities';
// We will add ephemeral and no allowed mention for string only overwrites
PaginatedMessage.wrongUserInteractionReply = (targetUser) =>
`These buttons are only for ${Formatters.userMention(targetUser.id)}. Press them as much as you want, but I won't do anything with your clicks.`;
example
import { PaginatedMessage } from '@sapphire/discord.js-utilities';
import { Formatters } from 'discord.js';
PaginatedMessage.wrongUserInteractionReply = (targetUser) => ({
content: `These buttons are only for ${Formatters.userMention(
targetUser.id
)}. Press them as much as you want, but I won't do anything with your clicks.`,
ephemeral: true,
allowedMentions: { users: [], roles: [] }
});
Inherited from
PaginatedMessage.wrongUserInteractionReply
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:1503
Methods
addAction
▸ addAction(action): PaginatedMessageEmbedFields
Adds an action to the existing ones. This will be added as the last action.
see PaginatedMessage.setActions for examples on how to structure the action.
Parameters
| Name | Type | Description |
|---|---|---|
action | PaginatedMessageAction | The action to add. |
Returns
Inherited from
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:415
addActions
▸ addActions(actions): PaginatedMessageEmbedFields
Adds actions to the existing ones. The order given is the order they will be used.
see PaginatedMessage.setActions for examples on how to structure the actions.
Parameters
| Name | Type | Description |
|---|---|---|
actions | PaginatedMessageAction[] | The actions to add. |
Returns
Inherited from
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:405
addAsyncPageBuilder
▸ addAsyncPageBuilder(builder): PaginatedMessageEmbedFields
Adds a page to the existing ones asynchronously using a MessageBuilder. This wil be added as the last page.
example
const { PaginatedMessage } = require('@sapphire/discord.js-utilities');
const { MessageEmbed } = require('discord.js');
const paginatedMessage = new PaginatedMessage()
.addAsyncPageBuilder(async (builder) => {
const someRemoteData = await fetch('https://contoso.com/api/users');
const embed = new MessageEmbed()
.setColor('#FF0000')
.setDescription(someRemoteData.data);
return builder
.setContent('example content')
.setEmbeds([embed]);
});
Parameters
| Name | Type | Description |
|---|---|---|
builder | MessageBuilder | (builder: MessageBuilder) => Promise<MessageBuilder> | Either a callback whose first parameter is new MessageBuilder(), or an already constructed MessageBuilder |
Returns
Inherited from
PaginatedMessage.addAsyncPageBuilder
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:542
addAsyncPageEmbed
▸ addAsyncPageEmbed(embed): PaginatedMessageEmbedFields
Adds a page to the existing ones asynchronously using a {@link MessageEmbed}. This wil be added as the last page.
example
const { PaginatedMessage } = require('@sapphire/discord.js-utilities');
const paginatedMessage = new PaginatedMessage()
.addAsyncPageEmbed(async (embed) => {
const someRemoteData = await fetch('https://contoso.com/api/users');
embed
.setColor('#FF0000')
.setDescription(someRemoteData.data);
return embed;
});
Parameters
| Name | Type | Description |
|---|---|---|
embed | MessageEmbed | (builder: MessageEmbed) => Promise<MessageEmbed> | Either a callback whose first parameter is new MessageEmbed(), or an already constructed {@link MessageEmbed} |
Returns
Inherited from
PaginatedMessage.addAsyncPageEmbed
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:612
addAsyncPageEmbeds
▸ addAsyncPageEmbeds(embeds): PaginatedMessageEmbedFields
Adds a page to the existing ones using multiple {@link MessageEmbed}'s. This wil be added as the last page.
remark When using this with a callback this will construct 10 {@link MessageEmbed}'s in the callback parameters, regardless of how many are actually used.
If this a performance impact you do not want to cope with then it is recommended to use PaginatedMessage.addPageBuilder instead, which will let you add
as many embeds as you want, albeit manually
example
const { PaginatedMessage } = require('@sapphire/discord.js-utilities');
const paginatedMessage = new PaginatedMessage().addAsyncPageEmbeds(async (embed0, embed1, embed2) => {
const someRemoteData = (await fetch('https://contoso.com/api/users')) as any;
for (const [index, user] of Object.entries(someRemoteData.users.slice(0, 10)) as [`${0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10}`, any][]) {
switch (index) {
case '0': {
embed0.setColor('#FF0000').setDescription('example description 1').setAuthor(user.name);
break;
}
case '1': {
embed1.setColor('#00FF00').setDescription('example description 2').setAuthor(user.name);
break;
}
case '2': {
embed2.setColor('#0000FF').setDescription('example description 3').setAuthor(user.name);
break;
}
}
}
return [embed0, embed1, embed2];
});
example
const { PaginatedMessage } = require('@sapphire/discord.js-utilities');
const embed1 = new MessageEmbed()
.setColor('#FF0000')
.setDescription('example description 1');
const embed2 = new MessageEmbed()
.setColor('#00FF00')
.setDescription('example description 2');
const embed3 = new MessageEmbed()
.setColor('#0000FF')
.setDescription('example description 3');
const paginatedMessage = new PaginatedMessage()
.addAsyncPageEmbeds([embed1, embed2, embed3]); // You can add up to 10 embeds
Parameters
| Name | Type | Description |
|---|---|---|
embeds | MessageEmbed[] | (embed1: MessageEmbed, embed2: MessageEmbed, embed3: MessageEmbed, embed4: MessageEmbed, embed5: MessageEmbed, embed6: MessageEmbed, embed7: MessageEmbed, embed8: MessageEmbed, embed9: MessageEmbed, embed10: MessageEmbed) => Promise<MessageEmbed[]> | Either a callback which receives 10 parameters of new MessageEmbed(), or an array of already constructed {@link MessageEmbed}'s |
Returns
Inherited from
PaginatedMessage.addAsyncPageEmbeds
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:754
addPage
▸ addPage(page): PaginatedMessageEmbedFields
Adds a page to the existing ones. This will be added as the last page.
remark While you can use this method you should first check out
PaginatedMessage.addPageBuilder,
PaginatedMessage.addPageContent and
PaginatedMessage.addPageEmbed as
these are easier functional methods of adding pages and will likely already suffice for your needs.
Parameters
| Name | Type | Description |
|---|---|---|
page | PaginatedMessagePage | The page to add. |
Returns
Inherited from
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:457
addPageBuilder
▸ addPageBuilder(builder): PaginatedMessageEmbedFields
Adds a page to the existing ones using a MessageBuilder. This will be added as the last page.
example
const { PaginatedMessage } = require('@sapphire/discord.js-utilities');
const { MessageEmbed } = require('discord.js');
const paginatedMessage = new PaginatedMessage()
.addPageBuilder((builder) => {
const embed = new MessageEmbed()
.setColor('#FF0000')
.setDescription('example description');
return builder
.setContent('example content')
.setEmbeds([embed]);
});
example
const { MessageEmbed } = require('discord.js');
const { MessageBuilder, PaginatedMessage } = require('@sapphire/discord.js-utilities');
const embed = new MessageEmbed()
.setColor('#FF0000')
.setDescription('example description');
const builder = new MessageBuilder()
.setContent('example content')
.setEmbeds([embed]);
const paginatedMessage = new PaginatedMessage()
.addPageBuilder(builder);
Parameters
| Name | Type | Description |
|---|---|---|
builder | MessageBuilder | (builder: MessageBuilder) => MessageBuilder | Either a callback whose first parameter is new MessageBuilder(), or an already constructed MessageBuilder |
Returns
Inherited from
PaginatedMessage.addPageBuilder
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:516
addPageContent
▸ addPageContent(content): PaginatedMessageEmbedFields
Adds a page to the existing ones using simple message content. This will be added as the last page.
example
const { PaginatedMessage } = require('@sapphire/discord.js-utilities');
const paginatedMessage = new PaginatedMessage()
.addPageContent('example content');
Parameters
| Name | Type | Description |
|---|---|---|
content | string | The content to set. |
Returns
Inherited from
PaginatedMessage.addPageContent
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:557
addPageEmbed
▸ addPageEmbed(embed): PaginatedMessageEmbedFields
Adds a page to the existing ones using a {@link MessageEmbed}. This wil be added as the last page.
example
const { PaginatedMessage } = require('@sapphire/discord.js-utilities');
const paginatedMessage = new PaginatedMessage()
.addPageEmbed((embed) => {
embed
.setColor('#FF0000')
.setDescription('example description');
return embed;
});
example
const { PaginatedMessage } = require('@sapphire/discord.js-utilities');
const embed = new MessageEmbed()
.setColor('#FF0000')
.setDescription('example description');
const paginatedMessage = new PaginatedMessage()
.addPageEmbed(embed);
Parameters
| Name | Type | Description |
|---|---|---|
embed | MessageEmbed | (embed: MessageEmbed) => MessageEmbed | Either a callback whose first parameter is new MessageEmbed(), or an already constructed {@link MessageEmbed} |
Returns
Inherited from
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:589
addPageEmbeds
▸ addPageEmbeds(embeds): PaginatedMessageEmbedFields
Adds a page to the existing ones asynchronously using multiple {@link MessageEmbed}'s. This wil be added as the last page.
remark When using this with a callback this will construct 10 {@link MessageEmbed}'s in the callback parameters, regardless of how many are actually used.
If this a performance impact you do not want to cope with then it is recommended to use PaginatedMessage.addPageBuilder instead, which will let you add
as many embeds as you want, albeit manually
example
const { PaginatedMessage } = require('@sapphire/discord.js-utilities');
const paginatedMessage = new PaginatedMessage()
.addPageEmbeds((embed1, embed2, embed3) => { // You can add up to 10 embeds
embed1
.setColor('#FF0000')
.setDescription('example description 1');
embed2
.setColor('#00FF00')
.setDescription('example description 2');
embed3
.setColor('#0000FF')
.setDescription('example description 3');
return [embed1, embed2, embed3];
});
example
const { PaginatedMessage } = require('@sapphire/discord.js-utilities');
const embed1 = new MessageEmbed()
.setColor('#FF0000')
.setDescription('example description 1');
const embed2 = new MessageEmbed()
.setColor('#00FF00')
.setDescription('example description 2');
const embed3 = new MessageEmbed()
.setColor('#0000FF')
.setDescription('example description 3');
const paginatedMessage = new PaginatedMessage()
.addPageEmbeds([embed1, embed2, embed3]); // You can add up to 10 embeds
Parameters
| Name | Type | Description |
|---|---|---|
embeds | MessageEmbed[] | (embed1: MessageEmbed, embed2: MessageEmbed, embed3: MessageEmbed, embed4: MessageEmbed, embed5: MessageEmbed, embed6: MessageEmbed, embed7: MessageEmbed, embed8: MessageEmbed, embed9: MessageEmbed, embed10: MessageEmbed) => MessageEmbed[] | Either a callback which receives 10 parameters of new MessageEmbed(), or an array of already constructed {@link MessageEmbed}'s |
Returns
Inherited from
PaginatedMessage.addPageEmbeds
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:663
addPages
▸ addPages(pages): PaginatedMessageEmbedFields
Add pages to the existing ones. The order given is the order they will be used.
Parameters
| Name | Type | Description |
|---|---|---|
pages | PaginatedMessagePage[] | The pages to add. |
Returns
Inherited from
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:798
applyFooter
▸ Protected applyFooter(message, index): PaginatedMessageMessageOptionsUnion
Applies footer to the last embed of the page
Parameters
| Name | Type | Description |
|---|---|---|
message | PaginatedMessageMessageOptionsUnion | The message options |
index | number | The current index |
Returns
PaginatedMessageMessageOptionsUnion
The message options with the footer applied
Inherited from
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:1175
clone
▸ clone(): PaginatedMessage
Clones the current handler into a new instance.
Returns
Inherited from
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:960
generatePages
▸ Private generatePages(): void
Returns
void
Defined in
handleCollect
▸ Protected handleCollect(targetUser, channel, interaction): Promise<void>
Handles the collect event from the collector.
Parameters
| Name | Type | Description |
|---|---|---|
targetUser | User | The user the handler is for. |
channel | DMChannel | PartialDMChannel | NewsChannel | TextChannel | ThreadChannel | The channel the handler is running at. |
interaction | SelectMenuInteraction<CacheType> | ButtonInteraction<CacheType> | The button interaction that was received. |
Returns
Promise<void>
Inherited from
PaginatedMessage.handleCollect
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:1097
handleEnd
▸ Protected handleEnd(_, reason): void
Handles the end event from the collector.
Parameters
| Name | Type | Description |
|---|---|---|
_ | Collection<string, SelectMenuInteraction<CacheType> | ButtonInteraction<CacheType>> | - |
reason | string | The reason for which the collector was ended. |
Returns
void
Inherited from
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:1152
handlePageLoad
▸ Protected handlePageLoad(page, index): Promise<PaginatedMessageMessageOptionsUnion>
Handles the load of a page.
Parameters
| Name | Type | Description |
|---|---|---|
page | PaginatedMessagePage | The page to be loaded. |
index | number | The index of the current page. |
Returns
Promise<PaginatedMessageMessageOptionsUnion>
Inherited from
PaginatedMessage.handlePageLoad
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:1077
hasPage
▸ hasPage(index): boolean
Checks whether or not the handler has a specific page.
Parameters
| Name | Type | Description |
|---|---|---|
index | number | The index to check. |
Returns
boolean
Inherited from
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:432
make
▸ make(): PaginatedMessageEmbedFields
Build the pages of the given array.
You must call the PaginatedMessageEmbedFields.make and PaginatedMessageEmbedFields.run methods last, in that order, for the pagination to work.
example
import { PaginatedMessageEmbedFields } from '@sapphire/discord.js-utilities';
new PaginatedMessageEmbedFields()
.setItems([
{ name: 'Sapphire Framework', value: 'discord.js Framework' },
{ name: 'Sapphire Framework 2', value: 'discord.js Framework 2' },
{ name: 'Sapphire Framework 3', value: 'discord.js Framework 3' }
])
.setItemsPerPage(3)
.make()
.run(message);
Returns
Defined in
paginateArray
▸ Private paginateArray(items, currentPage, perPageItems): EmbedFieldData[]
Parameters
| Name | Type |
|---|---|
items | EmbedFieldData[] |
currentPage | number |
perPageItems | number |
Returns
Defined in
resolvePage
▸ resolvePage(index): Promise<PaginatedMessagePage>
Executed whenever an action is triggered and resolved.
Parameters
| Name | Type | Description |
|---|---|---|
index | number | The index to resolve. |
Returns
Inherited from
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:943
resolvePagesOnRun
▸ resolvePagesOnRun(): Promise<void>
Executed whenever PaginatedMessage.run is called.
Returns
Promise<void>
Inherited from
PaginatedMessage.resolvePagesOnRun
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:933
resolvePaginatedMessageInternationalizationContext
▸ Protected resolvePaginatedMessageInternationalizationContext(messageOrInteraction, targetUser): PaginatedMessageInternationalizationContext
Constructs a PaginatedMessageInternationalizationContext including a deprecation notice for PaginatedMessageInternationalizationContext.author
Parameters
| Name | Type | Description |
|---|---|---|
messageOrInteraction | Message<boolean> | CommandInteraction<CacheType> | ContextMenuInteraction<CacheType> | SelectMenuInteraction<CacheType> | ButtonInteraction<CacheType> | The message or interaction for which the PaginatedMessageInternationalizationContext should be resolved. |
targetUser | User | The target user for whom this interaction is |
Returns
PaginatedMessageInternationalizationContext
A constructed PaginatedMessageInternationalizationContext
Inherited from
PaginatedMessage.resolvePaginatedMessageInternationalizationContext
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:1200
resolveTemplate
▸ Private resolveTemplate(template): MessageEmbed
Parameters
| Name | Type |
|---|---|
template | MessageEmbed | MessageEmbedOptions | (embed: MessageEmbed) => MessageEmbed |
Returns
Defined in
run
▸ run(messageOrInteraction, target?): Promise<PaginatedMessageEmbedFields>
Executes the PaginatedMessage and sends the pages corresponding with PaginatedMessage.index. The handler will start collecting message component interactions.
remark Please note that for PaginatedMessage to work in DMs to your client, you need to add the 'CHANNEL' partial to your client.options.partials.
Message based commands can always be used in DMs, whereas Chat Input interactions can only be used in DMs when they are registered globally.
Parameters
| Name | Type | Description |
|---|---|---|
messageOrInteraction | Message<boolean> | CommandInteraction<CacheType> | ContextMenuInteraction<CacheType> | SelectMenuInteraction<CacheType> | ButtonInteraction<CacheType> | The message or interaction that triggered this PaginatedMessage. Generally this will be the command message or an interaction (either a {@link CommandInteraction}, a {@link ContextMenuInteraction}, a {@link SelectMenuInteraction} or a {@link ButtonInteraction}), but it can also be another message from your client, i.e. to indicate a loading state. |
target? | User | The user who will be able to interact with the buttons of this PaginatedMessage. If messageOrInteraction is an instance of {@link Message} then this defaults to {@link Message.author messageOrInteraction.author}, and if it is an instance of {@link CommandInteraction} then it defaults to {@link CommandInteraction.user messageOrInteraction.user}. |
Returns
Promise<PaginatedMessageEmbedFields>
Inherited from
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:821
setActions
▸ setActions(actions, includeDefaultActions?): PaginatedMessageEmbedFields
Clears all current actions and sets them. The order given is the order they will be used.
remark You can retrieve the default actions for the regular pagination
example
const display = new PaginatedMessage();
display.setActions([
...PaginatedMessage.defaultActions,
])
remark You can add custom Message Buttons by providing style, customId, type, run and at least one of label or emoji.
example
const display = new PaginatedMessage();
display.setActions([
{
style: 'PRIMARY',
label: 'My Button',
customId: 'custom_button',
type: Constants.MessageComponentTypes.BUTTON,
run: (context) => console.log(context)
}
], true);
remark You can add custom Message Link Buttons by providing style, url, type, and at least one of label or emoji.
example
const display = new PaginatedMessage();
display.setActions([
{
style: 'LINK',
label: 'Sapphire Website',
emoji: '🔷',
url: 'https://sapphirejs.dev',
type: Constants.MessageComponentTypes.BUTTON
}
], true);
remark You can add custom Select Menus by providing customId, type, and run.
example
const display = new PaginatedMessage();
display.setActions([
{
customId: 'custom_menu',
type: Constants.MessageComponentTypes.SELECT_MENU,
run: (context) => console.log(context) // Do something here
}
], true);
Parameters
| Name | Type | Default value | Description |
|---|---|---|---|
actions | PaginatedMessageAction[] | undefined | The actions to set. This can be either a Button, Link Button, or Select Menu. |
includeDefaultActions | boolean | false | Whether to merge in the PaginatedMessage.defaultActions when setting the actions. If you set this to true then you do not need to manually add ...PaginatedMessage.defaultActions as seen in the first example. The default value is false for backwards compatibility within the current major version. |
Returns
Inherited from
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:395
setEmitPartialDMChannelWarning
▸ setEmitPartialDMChannelWarning(emitPartialDMChannelWarning): PaginatedMessageEmbedFields
Sets the PaginatedMessage.emitPartialDMChannelWarning for this instance of PaginatedMessage. This will only apply to this one instance and no others.
Parameters
| Name | Type | Description |
|---|---|---|
emitPartialDMChannelWarning | boolean | The new emitPartialDMChannelWarning to set |
Returns
The current instance of PaginatedMessage
Inherited from
PaginatedMessage.setEmitPartialDMChannelWarning
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:306
setIdle
▸ setIdle(idle): PaginatedMessageEmbedFields
Sets the amount of time to idle before the paginator is closed.
Parameters
| Name | Type | Description |
|---|---|---|
idle | number | The number to set the idle to. |
Returns
Inherited from
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:324
setIndex
▸ setIndex(index): PaginatedMessageEmbedFields
Sets the handler's current page/message index.
Parameters
| Name | Type | Description |
|---|---|---|
index | number | The number to set the index to. |
Returns
Inherited from
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:315
setItems
▸ setItems(items): PaginatedMessageEmbedFields
Set the items to paginate.
Parameters
| Name | Type | Description |
|---|---|---|
items | EmbedFieldData[] | The pages to set |
Returns
Defined in
setItemsPerPage
▸ setItemsPerPage(itemsPerPage): PaginatedMessageEmbedFields
Sets the amount of items that should be shown per page.
Parameters
| Name | Type | Description |
|---|---|---|
itemsPerPage | number | The number of items |
Returns
Defined in
setPages
▸ setPages(pages): PaginatedMessageEmbedFields
Clears all current pages and messages and sets them. The order given is the order they will be used.
Parameters
| Name | Type | Description |
|---|---|---|
pages | PaginatedMessagePage[] | The pages to set. |
Returns
Inherited from
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:440
setSelectMenuOptions
▸ setSelectMenuOptions(newOptions): PaginatedMessageEmbedFields
Sets the PaginatedMessage.selectMenuOptions for this instance of PaginatedMessage. This will only apply to this one instance and no others.
Parameters
| Name | Type | Description |
|---|---|---|
newOptions | PaginatedMessageSelectMenuOptionsFunction | The new options generator to set |
Returns
The current instance of PaginatedMessage
Inherited from
PaginatedMessage.setSelectMenuOptions
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:262
setSelectMenuPlaceholder
▸ setSelectMenuPlaceholder(placeholder): PaginatedMessageEmbedFields
Sets the PaginatedMessage.selectMenuPlaceholder for this instance of PaginatedMessage. This will only apply to this one instance and no others.
Parameters
| Name | Type | Description |
|---|---|---|
placeholder | undefined | string | The new placeholder to set |
Returns
The current instance of PaginatedMessage
Inherited from
PaginatedMessage.setSelectMenuPlaceholder
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:273
setStopPaginatedMessageCustomIds
▸ setStopPaginatedMessageCustomIds(stopPaginatedMessageCustomIds): PaginatedMessageEmbedFields
Sets the PaginatedMessage.stopPaginatedMessageCustomIds for this instance of PaginatedMessage. This will only apply to this one instance and no others.
Parameters
| Name | Type | Description |
|---|---|---|
stopPaginatedMessageCustomIds | string[] | The new stopPaginatedMessageCustomIds to set |
Returns
The current instance of PaginatedMessage
Inherited from
PaginatedMessage.setStopPaginatedMessageCustomIds
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:295
setTemplate
▸ setTemplate(template): PaginatedMessageEmbedFields
Sets the template to be used to display the embed fields as pages. This template can either be set from a template {@link MessageEmbed} instance or an object with embed options. All fields in the given template will be overwritten when calling PaginatedMessageEmbedFields.make.
example
import { PaginatedMessageEmbedFields } from '@sapphire/discord.js-utilities';
import { MessageEmbed } from 'discord.js';
new PaginatedMessageEmbedFields()
.setTemplate(new MessageEmbed().setColor('#006080').setTitle('Test pager embed'))
.setItems([{ name: 'My field', value: 'The field\'s value' }])
.make()
.run(message);
example
import { PaginatedMessageEmbedFields } from '@sapphire/discord.js-utilities';
import { MessageEmbed } from 'discord.js';
new PaginatedMessageEmbedFields()
.setTemplate({ title: 'Test pager embed', color: '#006080' })
.setItems([{ name: 'My field', value: 'The field\'s value' }])
.make()
.run(message);
Parameters
| Name | Type | Description |
|---|---|---|
template | MessageEmbed | MessageEmbedOptions | (embed: MessageEmbed) => MessageEmbed | MessageEmbed |
Returns
Defined in
setUpCollector
▸ Protected setUpCollector(channel, targetUser): void
Sets up the message's collector.
Parameters
| Name | Type | Description |
|---|---|---|
channel | TextBasedChannel | The channel the handler is running at. |
targetUser | User | The user the handler is for. |
Returns
void
Inherited from
PaginatedMessage.setUpCollector
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:1044
setUpMessage
▸ Protected setUpMessage(messageOrInteraction, targetUser): Promise<void>
Sets up the message.
Parameters
| Name | Type | Description |
|---|---|---|
messageOrInteraction | Message<boolean> | CommandInteraction<CacheType> | ContextMenuInteraction<CacheType> | SelectMenuInteraction<CacheType> | ButtonInteraction<CacheType> | The message or interaction that triggered this PaginatedMessage. Generally this will be the command message or an interaction (either a {@link CommandInteraction}, a {@link ContextMenuInteraction}, a {@link SelectMenuInteraction} or a {@link ButtonInteraction}), but it can also be another message from your client, i.e. to indicate a loading state. |
targetUser | User | - |
Returns
Promise<void>
Inherited from
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:978
setWrongUserInteractionReply
▸ setWrongUserInteractionReply(wrongUserInteractionReply): PaginatedMessageEmbedFields
Sets the PaginatedMessage.wrongUserInteractionReply for this instance of PaginatedMessage. This will only apply to this one instance and no others.
Parameters
| Name | Type | Description |
|---|---|---|
wrongUserInteractionReply | PaginatedMessageWrongUserInteractionReplyFunction | The new wrongUserInteractionReply to set |
Returns
The current instance of PaginatedMessage
Inherited from
PaginatedMessage.setWrongUserInteractionReply
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:284