Class: LazyPaginatedMessage
This is a LazyPaginatedMessage. Instead of resolving all pages that are functions on PaginatedMessage.run will resolve when requested.
Extends
Constructors
new LazyPaginatedMessage()
new LazyPaginatedMessage(
__namedParameters
:PaginatedMessageOptions
):LazyPaginatedMessage
The constructor
field represents the constructor of the PaginatedMessage
interface.
It is of type typeof PaginatedMessage
, which means it refers to the type of the PaginatedMessage
interface itself.
Parameters
Parameter | Type | Description |
---|---|---|
__namedParameters | PaginatedMessageOptions | The PaginatedMessageOptions for this instance of the PaginatedMessage class |
Returns
Inherited from
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:517
Properties
#thisMazeWasNotMeantForYouContent
private
readonly
#thisMazeWasNotMeantForYouContent:object
The response we send when someone gets into an invalid flow
content
content:
string
="This maze wasn't meant for you...what did you do."
Inherited from
PaginatedMessage
.#thisMazeWasNotMeantForYouContent
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:510
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:402
collector
collector:
null
|InteractionCollector
<PaginatedMessageInteractionUnion
> =null
The collector used for handling component interactions.
Inherited from
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:392
constructor
constructor: typeof
PaginatedMessage
The constructor
field represents the constructor of the PaginatedMessage
interface.
It is of type typeof PaginatedMessage
, which means it refers to the type of the PaginatedMessage
interface itself.
Inherited from
PaginatedMessage.constructor
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:1844
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:439
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:453
hasEmittedMaxPageWarning
protected
hasEmittedMaxPageWarning:boolean
=false
Tracks whether a warning was already emitted for this PaginatedMessage concerning the maximum amount of pages in the SelectMenu.
Default
false
Inherited from
PaginatedMessage
.hasEmittedMaxPageWarning
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:473
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.
Default
false
Inherited from
PaginatedMessage
.hasEmittedPartialDMChannelWarning
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:483
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:419
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:412
messages
messages: (
null
|PaginatedMessageResolvedPage
)[] =[]
The pages which were converted from PaginatedMessage.pages
Inherited from
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:397
pageActions
pageActions: (
null
|Map
<string
,PaginatedMessageAction
>)[] =[]
The page-specific actions which are to be used.
Inherited from
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:407
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:432
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:382
paginatedMessageData
protected
paginatedMessageData:null
|Omit
<PaginatedMessageMessageOptionsUnion
,"components"
> =null
Data for the paginated message.
Inherited from
PaginatedMessage
.paginatedMessageData
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:460
response
response:
null
|Message
<boolean
> |AnyInteractableInteraction
=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:387
selectMenuOptions
protected
selectMenuOptions:PaginatedMessageSelectMenuOptionsFunction
=PaginatedMessage.selectMenuOptions
Function that returns the select menu options for the paginated message.
Param
The paginated message.
Returns
The select menu options.
Inherited from
PaginatedMessage
.selectMenuOptions
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:500
selectMenuPlaceholder
protected
selectMenuPlaceholder:undefined
|string
=undefined
The placeholder for the select menu.
Inherited from
PaginatedMessage
.selectMenuPlaceholder
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:465
shouldAddFooterToEmbeds
protected
shouldAddFooterToEmbeds:boolean
=true
Determines whether the default footer that shows the current page number should be added to the embeds.
Note
If this is set to false, i.e.e through setShouldAddFooterToEmbeds, then embedFooterSeparator is never applied.
Default
true
Inherited from
PaginatedMessage
.shouldAddFooterToEmbeds
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:493
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:445
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:425
wrongUserInteractionReply
protected
wrongUserInteractionReply:PaginatedMessageWrongUserInteractionReplyFunction
=PaginatedMessage.wrongUserInteractionReply
Function that handles the reply when a user interacts with the paginated message incorrectly.
Inherited from
PaginatedMessage
.wrongUserInteractionReply
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:505
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:143
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:229
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:259
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:209
handlers
readonly
static
handlers:Map
<string
,PaginatedMessage
>
The current 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:277
messages
readonly
static
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:268
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:244
selectMenuOptions
static
selectMenuOptions:PaginatedMessageSelectMenuOptionsFunction
A generator for MessageSelectOption that will be used to generate the options for the StringSelectMenuBuilder. We do not allow overwriting the 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 StringSelectMenuBuilder. 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:304
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:223
wrongUserInteractionReply
static
wrongUserInteractionReply:PaginatedMessageWrongUserInteractionReplyFunction
A generator for 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 User this PaginatedMessage was intended for.
Param
The User that actually clicked the button.
Default
import { userMention } from 'discord.js';
{
content: `Please stop interacting with the components on this message. They are only for ${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.
Examples
import { PaginatedMessage } from '@sapphire/discord.js-utilities';
import { userMention } from 'discord.js';
// We will add ephemeral and no allowed mention for string only overwrites
PaginatedMessage.wrongUserInteractionReply = (targetUser) =>
`These buttons are only for ${userMention(targetUser.id)}. Press them as much as you want, but I won't do anything with your clicks.`;
import { PaginatedMessage } from '@sapphire/discord.js-utilities';
import { userMention } from 'discord.js';
PaginatedMessage.wrongUserInteractionReply = (targetUser) => ({
content: `These buttons are only for ${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:351
Methods
addAction()
addAction(
action
:PaginatedMessageAction
):this
Adds an action to the existing ones. This will be added as the last action.
Parameters
Parameter | Type | Description |
---|---|---|
action | PaginatedMessageAction | The action to add. |
Returns
this
See
PaginatedMessage.setActions for examples on how to structure the action.
Inherited from
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:708
addActions()
addActions(
actions
:PaginatedMessageAction
[]):this
Adds actions to the existing ones. The order given is the order they will be used.
Parameters
Parameter | Type | Description |
---|---|---|
actions | PaginatedMessageAction [] | The actions to add. |
Returns
this
See
PaginatedMessage.setActions for examples on how to structure the actions.
Inherited from
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:698
addAsyncPageBuilder()
addAsyncPageBuilder(
builder
:MessageBuilder
| (builder
:MessageBuilder
) =>Promise
<MessageBuilder
>):this
Adds a page to the existing ones asynchronously using a MessageBuilder. This wil be added as the last page.
Parameters
Parameter | Type | Description |
---|---|---|
builder | MessageBuilder | (builder : MessageBuilder ) => Promise <MessageBuilder > | Either a callback whose first parameter is new MessageBuilder() , or an already constructed MessageBuilder |
Returns
this
Example
const { PaginatedMessage } = require('@sapphire/discord.js-utilities');
const { EmbedBuilder } = require('discord.js');
const paginatedMessage = new PaginatedMessage()
.addAsyncPageBuilder(async (builder) => {
const someRemoteData = await fetch('https://contoso.com/api/users');
const embed = new EmbedBuilder()
.setColor('#FF0000')
.setDescription(someRemoteData.data);
return builder
.setContent('example content')
.setEmbeds([embed]);
});
Inherited from
PaginatedMessage
.addAsyncPageBuilder
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:858
addAsyncPageEmbed()
addAsyncPageEmbed(
embed
:EmbedResolvable
| (builder
:EmbedBuilder
) =>Awaitable
<EmbedResolvable
>):this
Adds a page to the existing ones asynchronously using a EmbedBuilder. This wil be added as the last page.
Parameters
Parameter | Type | Description |
---|---|---|
embed | EmbedResolvable | (builder : EmbedBuilder ) => Awaitable <EmbedResolvable > | Either a callback whose first parameter is new EmbedBuilder() , or an already constructed EmbedBuilder |
Returns
this
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;
});
Inherited from
PaginatedMessage
.addAsyncPageEmbed
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:928
addAsyncPageEmbeds()
addAsyncPageEmbeds(
embeds
:EmbedResolvable
[] | (embed1
:EmbedBuilder
,embed2
:EmbedBuilder
,embed3
:EmbedBuilder
,embed4
:EmbedBuilder
,embed5
:EmbedBuilder
,embed6
:EmbedBuilder
,embed7
:EmbedBuilder
,embed8
:EmbedBuilder
,embed9
:EmbedBuilder
,embed10
:EmbedBuilder
) =>Awaitable
<EmbedResolvable
[]>):this
Adds a page to the existing ones using multiple EmbedBuilder's. This wil be added as the last page.
Parameters
Parameter | Type | Description |
---|---|---|
embeds | EmbedResolvable [] | (embed1 : EmbedBuilder , embed2 : EmbedBuilder , embed3 : EmbedBuilder , embed4 : EmbedBuilder , embed5 : EmbedBuilder , embed6 : EmbedBuilder , embed7 : EmbedBuilder , embed8 : EmbedBuilder , embed9 : EmbedBuilder , embed10 : EmbedBuilder ) => Awaitable <EmbedResolvable []> | Either a callback which receives 10 parameters of new EmbedBuilder() , or an array of already constructed EmbedBuilder's |
Returns
this
Remark
When using this with a callback this will construct 10 EmbedBuilder'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
Examples
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];
});
const { PaginatedMessage } = require('@sapphire/discord.js-utilities');
const embed1 = new EmbedBuilder()
.setColor('#FF0000')
.setDescription('example description 1');
const embed2 = new EmbedBuilder()
.setColor('#00FF00')
.setDescription('example description 2');
const embed3 = new EmbedBuilder()
.setColor('#0000FF')
.setDescription('example description 3');
const paginatedMessage = new PaginatedMessage()
.addAsyncPageEmbeds([embed1, embed2, embed3]); // You can add up to 10 embeds
Inherited from
PaginatedMessage
.addAsyncPageEmbeds
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:1070
addPage()
addPage(
page
:PaginatedMessagePage
):this
Adds a page to the existing ones. This will be added as the last page.
Parameters
Parameter | Type | Description |
---|---|---|
page | PaginatedMessagePage | The page to add. |
Returns
this
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.
Inherited from
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:749
addPageAction()
addPageAction(
action
:PaginatedMessageAction
,index
:number
):this
Add the provided action to a page.
Parameters
Parameter | Type | Description |
---|---|---|
action | PaginatedMessageAction | The action to add. |
index | number | The index of the page to add the action to. |
Returns
this
See
PaginatedMessage.setActions for examples on how to structure the action.
Remark
Internally we check if the provided index exists. This means that calling this function before calling any of the methods below this will not work as the amount of pages will always be 0, thus the index will always be out of bounds. That said, make sure you first define your pages and then define your actions for those pages.
- PaginatedMessage.addAsyncPageEmbed
- PaginatedMessage.addPageBuilder
- PaginatedMessage.addPageContent
- PaginatedMessage.addPageEmbed
- PaginatedMessage.addPageEmbeds
- PaginatedMessage.addPages
- PaginatedMessage.setPages
Inherited from
PaginatedMessage
.addPageAction
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:1202
addPageActions()
addPageActions(
actions
:PaginatedMessageAction
[],index
:number
):this
Add the provided actions to a page.
Parameters
Parameter | Type | Description |
---|---|---|
actions | PaginatedMessageAction [] | The actions to add. |
index | number | The index of the page to add the actions to. |
Returns
this
See
PaginatedMessage.setActions for examples on how to structure the actions.
Remark
Internally we check if the provided index exists. This means that calling this function before calling any of the methods below this will not work as the amount of pages will always be 0, thus the index will always be out of bounds. That said, make sure you first define your pages and then define your actions for those pages.
- PaginatedMessage.addAsyncPageEmbed
- PaginatedMessage.addPageBuilder
- PaginatedMessage.addPageContent
- PaginatedMessage.addPageEmbed
- PaginatedMessage.addPageEmbeds
- PaginatedMessage.addPages
- PaginatedMessage.setPages
Inherited from
PaginatedMessage
.addPageActions
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:1175
addPageBuilder()
addPageBuilder(
builder
:MessageBuilder
| (builder
:MessageBuilder
) =>MessageBuilder
):this
Adds a page to the existing ones using a MessageBuilder. This will be added as the last page.
Parameters
Parameter | Type | Description |
---|---|---|
builder | MessageBuilder | (builder : MessageBuilder ) => MessageBuilder | Either a callback whose first parameter is new MessageBuilder() , or an already constructed MessageBuilder |
Returns
this
Examples
const { PaginatedMessage } = require('@sapphire/discord.js-utilities');
const { EmbedBuilder } = require('discord.js');
const paginatedMessage = new PaginatedMessage()
.addPageBuilder((builder) => {
const embed = new EmbedBuilder()
.setColor('#FF0000')
.setDescription('example description');
return builder
.setContent('example content')
.setEmbeds([embed]);
});
const { EmbedBuilder } = require('discord.js');
const { MessageBuilder, PaginatedMessage } = require('@sapphire/discord.js-utilities');
const embed = new EmbedBuilder()
.setColor('#FF0000')
.setDescription('example description');
const builder = new MessageBuilder()
.setContent('example content')
.setEmbeds([embed]);
const paginatedMessage = new PaginatedMessage()
.addPageBuilder(builder);
Overrides
PaginatedMessage
.addPageBuilder
Defined in
addPageContent()
addPageContent(
content
:string
):this
Adds a page to the existing ones using simple message content. This will be added as the last page.
Parameters
Parameter | Type | Description |
---|---|---|
content | string | The content to set. |
Returns
this
Example
const { PaginatedMessage } = require('@sapphire/discord.js-utilities');
const paginatedMessage = new PaginatedMessage()
.addPageContent('example content');
Overrides
PaginatedMessage
.addPageContent
Defined in
addPageEmbed()
addPageEmbed(
embed
:EmbedResolvable
| (builder
:EmbedBuilder
) =>EmbedResolvable
):this
Adds a page to the existing ones using a EmbedBuilder. This wil be added as the last page.
Parameters
Parameter | Type | Description |
---|---|---|
embed | EmbedResolvable | (builder : EmbedBuilder ) => EmbedResolvable | Either a callback whose first parameter is new EmbedBuilder() , or an already constructed EmbedBuilder |
Returns
this
Examples
const { PaginatedMessage } = require('@sapphire/discord.js-utilities');
const paginatedMessage = new PaginatedMessage()
.addPageEmbed((embed) => {
embed
.setColor('#FF0000')
.setDescription('example description');
return embed;
});
const { PaginatedMessage } = require('@sapphire/discord.js-utilities');
const embed = new EmbedBuilder()
.setColor('#FF0000')
.setDescription('example description');
const paginatedMessage = new PaginatedMessage()
.addPageEmbed(embed);
Overrides
Defined in
addPageEmbeds()
addPageEmbeds(
embeds
:EmbedResolvable
[] | (embed1
:EmbedBuilder
,embed2
:EmbedBuilder
,embed3
:EmbedBuilder
,embed4
:EmbedBuilder
,embed5
:EmbedBuilder
,embed6
:EmbedBuilder
,embed7
:EmbedBuilder
,embed8
:EmbedBuilder
,embed9
:EmbedBuilder
,embed10
:EmbedBuilder
) =>EmbedResolvable
[]):this
Adds a page to the existing ones asynchronously using multiple EmbedBuilder's. This wil be added as the last page.
Parameters
Parameter | Type | Description |
---|---|---|
embeds | EmbedResolvable [] | (embed1 : EmbedBuilder , embed2 : EmbedBuilder , embed3 : EmbedBuilder , embed4 : EmbedBuilder , embed5 : EmbedBuilder , embed6 : EmbedBuilder , embed7 : EmbedBuilder , embed8 : EmbedBuilder , embed9 : EmbedBuilder , embed10 : EmbedBuilder ) => EmbedResolvable [] | Either a callback which receives 10 parameters of new EmbedBuilder() , or an array of already constructed EmbedBuilder's |
Returns
this
Remark
When using this with a callback this will construct 10 EmbedBuilder'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
Examples
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];
});
const { PaginatedMessage } = require('@sapphire/discord.js-utilities');
const embed1 = new EmbedBuilder()
.setColor('#FF0000')
.setDescription('example description 1');
const embed2 = new EmbedBuilder()
.setColor('#00FF00')
.setDescription('example description 2');
const embed3 = new EmbedBuilder()
.setColor('#0000FF')
.setDescription('example description 3');
const paginatedMessage = new PaginatedMessage()
.addPageEmbeds([embed1, embed2, embed3]); // You can add up to 10 embeds
Overrides
PaginatedMessage
.addPageEmbeds
Defined in
addPages()
addPages(
pages
:PaginatedMessagePage
[]):this
Add pages to the existing ones. The order given is the order they will be used.
Parameters
Parameter | Type | Description |
---|---|---|
pages | PaginatedMessagePage [] | The pages to add. |
Returns
this
Inherited from
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:1114
applyFooter()
protected
applyFooter(message
:PaginatedMessageMessageOptionsUnion
,index
:number
):PaginatedMessageMessageOptionsUnion
Applies footer to the last embed of the page
Parameters
Parameter | 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:1672
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:1399
getPageOptions()
getPageOptions(
index
:number
):Promise
<undefined
|PaginatedMessageMessageOptionsUnion
>
Get the options of a page.
Parameters
Parameter | Type | Description |
---|---|---|
index | number | The index of the page. |
Returns
Promise
<undefined
| PaginatedMessageMessageOptionsUnion
>
Inherited from
PaginatedMessage
.getPageOptions
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:1412
handleActionLoad()
protected
handleActionLoad(actions
:PaginatedMessageAction
[],messageOrInteraction
:Message
<boolean
> |AnyInteractableInteraction
,targetUser
:User
):Promise
<MessageActionRowComponentBuilder
[]>
Handles the loading of actions.
Parameters
Parameter | Type | Description |
---|---|---|
actions | PaginatedMessageAction [] | The actions to be loaded. |
messageOrInteraction | Message <boolean > | AnyInteractableInteraction | The message or interaction that triggered this PaginatedMessage. |
targetUser | User | The user the handler is for. |
Returns
Promise
<MessageActionRowComponentBuilder
[]>
Inherited from
PaginatedMessage
.handleActionLoad
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:1526
handleCollect()
protected
handleCollect(targetUser
:User
,channel
:DMChannel
|PartialDMChannel
|PartialGroupDMChannel
|NewsChannel
|StageChannel
|TextChannel
|PublicThreadChannel
<boolean
> |PrivateThreadChannel
|VoiceChannel
,interaction
:PaginatedMessageInteractionUnion
):Promise
<void
>
Handles the collect
event from the collector.
Parameters
Parameter | Type | Description |
---|---|---|
targetUser | User | The user the handler is for. |
channel | DMChannel | PartialDMChannel | PartialGroupDMChannel | NewsChannel | StageChannel | TextChannel | PublicThreadChannel <boolean > | PrivateThreadChannel | VoiceChannel | The channel the handler is running at. |
interaction | PaginatedMessageInteractionUnion | 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:1586
handleEnd()
protected
handleEnd(_
:Collection
<string
,PaginatedMessageInteractionUnion
>,reason
:PaginatedMessageStopReasons
):Promise
<void
>
Handles the end
event from the collector.
Parameters
Parameter | Type | Description |
---|---|---|
_ | Collection <string , PaginatedMessageInteractionUnion > | - |
reason | PaginatedMessageStopReasons | The reason for which the collector was ended. |
Returns
Promise
<void
>
Inherited from
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:1639
handlePageLoad()
protected
handlePageLoad(page
:PaginatedMessagePage
,index
:number
):Promise
<PaginatedMessageMessageOptionsUnion
>
Handles the load of a page.
Parameters
Parameter | 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:1506
hasPage()
hasPage(
index
:number
):boolean
Checks whether or not the handler has a specific page.
Parameters
Parameter | 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:724
resolvePage()
resolvePage(
messageOrInteraction
:Message
<boolean
> |AnyInteractableInteraction
,target
:User
,index
:number
):Promise
<PaginatedMessageResolvedPage
>
Resolves the page corresponding with the given index. This also resolves the index's before and after the given index.
Parameters
Parameter | Type | Description |
---|---|---|
messageOrInteraction | Message <boolean > | AnyInteractableInteraction | The message or interaction that triggered this LazyPaginatedMessage. |
target | User | The user who will be able to interact with the buttons of this LazyPaginatedMessage. |
index | number | The index to resolve. Defaults to handler's current index. |
Returns
Promise
<PaginatedMessageResolvedPage
>
Overrides
Defined in
resolvePagesOnRun()
resolvePagesOnRun(
messageOrInteraction
:Message
<boolean
> |AnyInteractableInteraction
,target
:User
):Promise
<void
>
Only resolves the page corresponding with the handler's current index.
Parameters
Parameter | Type |
---|---|
messageOrInteraction | Message <boolean > | AnyInteractableInteraction |
target | User |
Returns
Promise
<void
>
Overrides
PaginatedMessage
.resolvePagesOnRun
Defined in
resolvePaginatedMessageInternationalizationContext()
protected
resolvePaginatedMessageInternationalizationContext(messageOrInteraction
:Message
<boolean
> |AnyInteractableInteraction
,targetUser
:User
):PaginatedMessageInternationalizationContext
Constructs a PaginatedMessageInternationalizationContext
Parameters
Parameter | Type | Description |
---|---|---|
messageOrInteraction | Message <boolean > | AnyInteractableInteraction | 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:1708
run()
run(
messageOrInteraction
:Message
<boolean
> |AnyInteractableInteraction
,target
?:User
):Promise
<LazyPaginatedMessage
>
Executes the PaginatedMessage and sends the pages corresponding with PaginatedMessage.index. The handler will start collecting message component interactions.
Parameters
Parameter | Type | Description |
---|---|---|
messageOrInteraction | Message <boolean > | AnyInteractableInteraction | The message or interaction that triggered this PaginatedMessage. Generally this will be the command message or an interaction (either a CommandInteraction, ContextMenuInteraction, or an interaction from PaginatedMessageInteractionUnion), 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 Message then this defaults to Message.author messageOrInteraction.author, and if it is an instance of CommandInteraction then it defaults to CommandInteraction.user messageOrInteraction.user. |
Returns
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.
Inherited from
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:1235
setActions()
setActions(
actions
:PaginatedMessageAction
[],includeDefaultActions
:boolean
):this
Clears all current actions and sets them. The order given is the order they will be used.
Parameters
Parameter | 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
this
Remark
You can retrieve the default actions for the regular pagination
Examples
const display = new PaginatedMessage();
display.setActions([
...PaginatedMessage.defaultActions,
])
const display = new PaginatedMessage();
display.setActions([
{
style: 'PRIMARY',
label: 'My Button',
customId: 'custom_button',
type: ComponentType.Button,
run: (context) => console.log(context)
}
], true);
const display = new PaginatedMessage();
display.setActions([
{
style: 'LINK',
label: 'Sapphire Website',
emoji: '🔷',
url: 'https://sapphirejs.dev',
type: ComponentType.Button
}
], true);
const display = new PaginatedMessage();
display.setActions([
{
customId: 'custom_menu',
type: ComponentType.StringSelect,
run: (context) => console.log(context) // Do something here
}
], true);
Remark
You can add custom Message Buttons by providing style
, customId
, type
, run
and at least one of label
or emoji
.
Remark
You can add custom Message Link Buttons by providing style
, url
, type
, and at least one of label
or emoji
.
Remark
You can add custom Select Menus by providing customId
, type
, and run
.
Inherited from
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:688
setEmitPartialDMChannelWarning()
setEmitPartialDMChannelWarning(
emitPartialDMChannelWarning
:boolean
):this
Sets the PaginatedMessage.emitPartialDMChannelWarning for this instance of PaginatedMessage. This will only apply to this one instance and no others.
Parameters
Parameter | Type | Description |
---|---|---|
emitPartialDMChannelWarning | boolean | The new emitPartialDMChannelWarning to set |
Returns
this
The current instance of PaginatedMessage
Inherited from
PaginatedMessage
.setEmitPartialDMChannelWarning
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:590
setIdle()
setIdle(
idle
:number
):this
Sets the amount of time to idle before the paginator is closed.
Parameters
Parameter | Type | Description |
---|---|---|
idle | number | The number to set the idle to. |
Returns
this
Inherited from
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:608
setIndex()
setIndex(
index
:number
):this
Sets the handler's current page/message index.
Parameters
Parameter | Type | Description |
---|---|---|
index | number | The number to set the index to. |
Returns
this
Inherited from
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:599
setPageActions()
setPageActions(
actions
:PaginatedMessageAction
[],index
:number
):this
Clear all actions for a page and set the new ones.
Parameters
Parameter | Type | Description |
---|---|---|
actions | PaginatedMessageAction [] | The actions to set. |
index | number | The index of the page to set the actions to. This is 0-based. |
Returns
this
Remark
Internally we check if the provided index exists. This means that calling this function before calling any of the methods below this will not work as the amount of pages will always be 0, thus the index will always be out of bounds. That said, make sure you first define your pages and then define your actions for those pages.
- PaginatedMessage.addAsyncPageEmbed
- PaginatedMessage.addPageBuilder
- PaginatedMessage.addPageContent
- PaginatedMessage.addPageEmbed
- PaginatedMessage.addPageEmbeds
- PaginatedMessage.addPages
- PaginatedMessage.setPages
Remark
Add a select menu to the first page, while preserving all default actions:
Example
const display = new PaginatedMessage();
display.setPageActions([
{
customId: 'custom_menu',
type: ComponentType.StringSelect,
run: (context) => console.log(context) // Do something here
}
], 0);
See
PaginatedMessage.setActions for more examples on how to structure the action.
Inherited from
PaginatedMessage
.setPageActions
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:1150
setPages()
setPages(
pages
:PaginatedMessagePage
[]):LazyPaginatedMessage
Clears all current pages and messages and sets them. The order given is the order they will be used.
Parameters
Parameter | Type | Description |
---|---|---|
pages | PaginatedMessagePage [] | The pages to set. |
Returns
Inherited from
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:732
setSelectMenuOptions()
setSelectMenuOptions(
newOptions
:PaginatedMessageSelectMenuOptionsFunction
):this
Sets the PaginatedMessage.selectMenuOptions for this instance of PaginatedMessage. This will only apply to this one instance and no others.
Parameters
Parameter | Type | Description |
---|---|---|
newOptions | PaginatedMessageSelectMenuOptionsFunction | The new options generator to set |
Returns
this
The current instance of PaginatedMessage
Inherited from
PaginatedMessage
.setSelectMenuOptions
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:542
setSelectMenuPlaceholder()
setSelectMenuPlaceholder(
placeholder
:undefined
|string
):this
Sets the PaginatedMessage.selectMenuPlaceholder for this instance of PaginatedMessage.
This applies only to the string select menu from the PaginatedMessage.defaultActions that offers "go to page" (we internally check the customId for this)
This will only apply to this one instance and no others.
Parameters
Parameter | Type | Description |
---|---|---|
placeholder | undefined | string | The new placeholder to set |
Returns
this
The current instance of PaginatedMessage
Inherited from
PaginatedMessage
.setSelectMenuPlaceholder
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:557
setShouldAddFooterToEmbeds()
setShouldAddFooterToEmbeds(
newValue
:boolean
):this
Sets the value of shouldAddFooterToEmbeds property and returns the instance of the class.
Parameters
Parameter | Type | Description |
---|---|---|
newValue | boolean | The new value for shouldAddFooterToEmbeds. |
Returns
this
The instance of the class with the updated shouldAddFooterToEmbeds value.
Inherited from
PaginatedMessage
.setShouldAddFooterToEmbeds
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:618
setStopPaginatedMessageCustomIds()
setStopPaginatedMessageCustomIds(
stopPaginatedMessageCustomIds
:string
[]):this
Sets the PaginatedMessage.stopPaginatedMessageCustomIds for this instance of PaginatedMessage. This will only apply to this one instance and no others.
Parameters
Parameter | Type | Description |
---|---|---|
stopPaginatedMessageCustomIds | string [] | The new stopPaginatedMessageCustomIds to set |
Returns
this
The current instance of PaginatedMessage
Inherited from
PaginatedMessage
.setStopPaginatedMessageCustomIds
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:579
setUpCollector()
protected
setUpCollector(messageOrInteraction
:Message
<boolean
> |AnyInteractableInteraction
,targetUser
:User
):void
Sets up the message's collector.
Parameters
Parameter | Type | Description |
---|---|---|
messageOrInteraction | Message <boolean > | AnyInteractableInteraction | The message or interaction that triggered this PaginatedMessage. |
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:1464
setUpMessage()
protected
setUpMessage(messageOrInteraction
:Message
<boolean
> |AnyInteractableInteraction
):Promise
<void
>
Sets up the message.
Parameters
Parameter | Type | Description |
---|---|---|
messageOrInteraction | Message <boolean > | AnyInteractableInteraction | The message or interaction that triggered this PaginatedMessage. Generally this will be the command message or an interaction (either a CommandInteraction, ContextMenuInteraction, or an interaction from PaginatedMessageInteractionUnion), but it can also be another message from your client, i.e. to indicate a loading state. |
Returns
Promise
<void
>
Inherited from
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:1425
setWrongUserInteractionReply()
setWrongUserInteractionReply(
wrongUserInteractionReply
:PaginatedMessageWrongUserInteractionReplyFunction
):this
Sets the PaginatedMessage.wrongUserInteractionReply for this instance of PaginatedMessage. This will only apply to this one instance and no others.
Parameters
Parameter | Type | Description |
---|---|---|
wrongUserInteractionReply | PaginatedMessageWrongUserInteractionReplyFunction | The new wrongUserInteractionReply to set |
Returns
this
The current instance of PaginatedMessage
Inherited from
PaginatedMessage
.setWrongUserInteractionReply
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:568
updateCurrentPage()
updateCurrentPage(
page
:PaginatedMessagePage
):Promise
<LazyPaginatedMessage
>
Update the current page.
Parameters
Parameter | Type | Description |
---|---|---|
page | PaginatedMessagePage | The content to update the page with. |
Returns
Remark
This method can only be used after PaginatedMessage.run has been used.
Inherited from
PaginatedMessage
.updateCurrentPage
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:778