Unofficial discord-interactions multi page embed handler
Project description
dinteractions-Paginator
Unofficial discord-interactions multi-page embed handler
Table of Contents
(Only works in the GitHub for some reason)
Features
- Message per embed or persistent message
- Index select that can be turned on/off
- Select labels are generated based on embed's title
- Index button that can be turned on/off
- Ability to set the buttons to any emote, color or label
- Custom buttons
Join our Discord server!
- Try out all the possible combinations of the paginator with
/example1
and/example2
, - Ask some questions,
- And give us feedback and suggestions!
Wanna contribute?
- Make an issue to:
- say what feature you want to be added
- file a bug report
- Make a pull request and:
- describe what you added/removed
- why you added/removed it
- Make sure you use the issue/PR template!
Installation
pip install -U dinteractions-Paginator
Dependencies
- discord.py (version 1.7.3)
- discord-py-interactions (version 3.0.2)
Examples:
These simple examples show how to easily create interactive, multiple page embeds that anyone can interact with that automatically deactivate after 60 seconds of inactivity:
Example GIF:
Paginator with select:
Slash command:
import discord
from discord.ext import commands
from discord_slash import SlashCommand, SlashContext
from dinteractions_Paginator import Paginator
bot = commands.Bot(command_prefix="/")
slash = SlashCommand(bot, sync_commands=True)
@bot.event
async def on_ready():
print(f"Logged in as {bot.user}!")
@slash.slash(name="embeds")
async def embeds(ctx: SlashContext):
one = discord.Embed(title="1st Embed", description="General Kenobi!", color=discord.Color.red())
two = discord.Embed(title="2nd Embed", description="General Kenobi!", color=discord.Color.orange())
three = discord.Embed(title="3rd Embed", description="General Kenobi!", color=discord.Color.gold())
four = discord.Embed(title="4th Embed", description="General Kenobi!", color=discord.Color.green())
five = discord.Embed(title="5th Embed", description="General Kenobi!", color=discord.Color.blue())
pages = [one, two, three, four, five]
await Paginator(bot=bot, ctx=ctx, pages=pages, content=["1", "2", "3", "4", "5"], timeout=60).run()
bot.run("token")
Normal command:
import discord
from discord.ext import commands
from discord_slash import SlashCommand
from dinteractions_Paginator import Paginator
bot = commands.Bot(command_prefix="/")
slash = SlashCommand(bot)
@bot.event
async def on_ready():
print(f"Logged in as {bot.user}!")
@bot.command()
async def embeds(ctx):
one = discord.Embed(title="1st Embed", description="General Kenobi!", color=discord.Color.red())
two = discord.Embed(title="2nd Embed", description="General Kenobi!", color=discord.Color.orange())
three = discord.Embed(title="3rd Embed", description="General Kenobi!", color=discord.Color.gold())
four = discord.Embed(title="4th Embed", description="General Kenobi!", color=discord.Color.green())
five = discord.Embed(title="5th Embed", description="General Kenobi!", color=discord.Color.blue())
pages = [one, two, three, four, five]
await Paginator(bot=bot, ctx=ctx, pages=pages, content=["1", "2", "3", "4", "5"], timeout=60).run()
bot.run("token")
NOTE: slash = SlashCommand(bot)
required to override bot
class Paginator
Arguments
Required:
bot
-commands.Bot
: The bot variable,commands.Bot
is requiredctx
Union[SlashContext, commands.Context, ComponentContext, MenuContext, discord.channel.TextChannel, discord.User, discord.Member]
: The context of a command.
NOTE: if one of the latter 3 are used, there will always be aThis interaction failed
even though it was a success, due to no context to respond to
Optional:
pages
-Optional[List[discord.Embed]]
: the list of embeds to be paginated, defaults toNone
and paginatescontent
instead
NOTE:content
must be a list for paginating withoutpages
!content
-Optional[Union[str, List[str]]]
: the content of the message to send, defaults toNone
files
-Optional[Union[discord.File, List[discord.File]]]
: files to send, defaults toNone
hidden
-Optional[bool]
: if you want the paginator to be hidden, defaultFalse
authorOnly
-Optional[bool]
: if you want the paginator to work for the author only, default isFalse
onlyFor
-Optional[Union[discord.User, discord.Role, List[Union[discord.User, discord.Role]]]]
: components only for specified user(s) or role(s)dm
-Optional[bool]
: if you want the paginator to be DM'ed, defaultFalse
customActionRow
-Optional[List[Union[dict, Callable]]]
: a custom action row, see this for more info, defaults toNone
Time:
timeout
-Optional[int]
: deactivates paginator after inactivity if enabled, defaults toNone
(meaning no timeout)disableAfterTimeout
-Optional[bool]
: disable components aftertimeout
, defaultTrue
deleteAfterTimeout
-Opti onal[bool]
: delete components aftertimeout
, defaultFalse
What to use:
useButtons
-Optional[bool]
: uses buttons, default isTrue
useSelect
-Optional[bool]
: uses a select, default isTrue
useIndexButton
-Optional[bool]
: uses the index button, default isFalse
and staysFalse
ifuseButtons
is alsoFalse
useLinkButton
-Optional[bool]
: uses the link buttonuseQuitButton
-Optional[bool]
: quit button to end the paginator, defaultFalse
useFirstLast
-Optional[bool]
: uses the first and last buttons, defaultTrue
useOverflow
-Optional[bool]
: uses the overflow action row if there are too many buttons, defaultTrue
useNotYours
-Optional[bool]
: sends an ephemeral (hidden) message if the paginator is not yours (see authorOnly or onlyFor), defaultTrue
Labels:
firstLabel
-Optional[str]
: The label of the button used to go to the first page, defaults to""
prevLabel
-Optional[str]
: The label of the button used to go to the previous page, defaults to""
indexLabel
-Optional[str]
: The label of the index button, defaults to"Page"
nextLabel
-Optional[str]
: The label of the button used to go to the next page, defaults to""
lastLabel
-Optional[str]
: The label of the button used to go to the last page, defaults to""
linkLabel
-Optional[Union[str, List[str]]]
: The label for the link buttonlinkURL
-Optional[Union[str, List[str]]]
: The URL(s) for the link buttoncustomButtonLabel
-Optional[str]
: The label of a custom disabled button, defaultNone
quitButtonLabel
-Optional[str]
: The label of the quit button, default"Quit"
Emojis:
firstEmoji
-Optional[Union[discord.emoji.Emoji, discord.partial_emoji.PartialEmoji, dict, str]
: emoji of the button used to go to the first page, defaults to"⏮️"
prevEmoji
-Optional[Union[discord.emoji.Emoji, discord.partial_emoji.PartialEmoji, dict, str]
: emoji of the button used to go to the previous page, defaults to"◀"
nextEmoji
-Optional[Union[discord.emoji.Emoji, discord.partial_emoji.PartialEmoji, dict, str]
: emoji of the button used to go to the next page, defaults to"▶"
lastEmoji
-Optional[Union[discord.emoji.Emoji, discord.partial_emoji.PartialEmoji, dict, str]
: emoji of the button used to go to the last page, defaults to"⏭️"
customButtonEmoji
-Optional[Union[discord.emoji.Emoji, discord.partial_emoji.PartialEmoji, dict, str]
: emoji of the custom disabled button, defaults toNone
quitButtonEmoji
-Optional[Union[discord.emoji.Emoji, discord.partial_emoji.PartialEmoji, dict, str]
: emoji of the quit button, defaults toNone
Styles (the colo[u]r of the buttons):
firstStyle
-Optional[Union[ButtonStyle, int]]
: the style of button (ButtonStyle
orint
) for the first button, defaults to1
(ButtonStyle.blue
)prevStyle
-Optional[Union[ButtonStyle, int]]
: the style of button (ButtonStyle
orint
) for the previous button, defaults to1
(ButtonStyle.blue
)indexStyle
-Optional[Union[ButtonStyle, int]]
: the style of button (ButtonStyle
orint
) for the index button, defaults to3
(ButtonStyle.green
)nextStyle
-Optional[Union[ButtonStyle, int]]
: the style of button (ButtonStyle
orint
) for the next button, defaults to1
(ButtonStyle.blue
)lastStyle
-Optional[Union[ButtonStyle, int]]
: the style of button (ButtonStyle
orint
) for the last button, defaults to1
(ButtonStyle.blue
)customButtonStyle
-Optional[Union[ButtonStyle, int]]
: the style of button (ButtonStyle
orint
) for the custom disabled button, defaults to2
(ButtonStyle.gray
)quitButtonStyle
-Optional[Union[ButtonStyle, int]]
: the style of button (ButtonStyle
orint
) for the quit button, defaults to4
(ButtonStyle.red
)
Returns
More info on customActionRow
:
You can define your own custom action row, with its own code!
Example code:
@slash.slash(name="custom-action-row")
async def _custom_action_row(ctx: SlashContext):
# Embeds:
pages = [
discord.Embed(title="1"),
discord.Embed(title="2"),
discord.Embed(title="3"),
discord.Embed(title="4"),
discord.Embed(title="5"),
]
# Action row:
buttons = [
create_button(style=3, label="A Green Button"),
]
custom_action_row = create_actionrow(*buttons)
# Function:
async def custom_function(self, button_ctx):
await button_ctx.send("test", hidden=True)
await self.ctx.send("lol")
# Paginator:
await Paginator(
bot,
ctx,
pages,
timeout=60,
customActionRow=[
custom_action_row,
custom_function,
], # Note that custom_function is not called
).run()
The code above runs a normal paginator, with 1 extra action row at the bottom!
Example GIF:
You can access all of the attributes of class Paginator with self
, such as the original command's
context (self.ctx
), the bot variable (self.bot
), and other things that you passed into it!
Template:
# <-- Your decorator here
# ...
buttons = [
create_button(style=3, label="A Green Button"),
... # Your buttons
]
custom_action_row = create_actionrow(*buttons)
# Function:
async def custom_function(self, button_ctx):
pass # Your code for the action row here
# You could check for each button and decide
# what to do
await Paginator(..., customActionRow=[custom_action_row, custom_function]).run()
class TimedOut
Attributes
ctx
-Union[commands.Context, SlashContext]
: The original contextbuttonContext
-ComponentContext
: The context for the paginator's componentstimeTaken
-int
: How long in seconds that user(s) used the paginator before the timeoutlastContent
-str
: The last content that the paginator stopped at after timeoutlastEmbed
-discord.Embed
: The last embed that the paginator stopped at after timeoutsuccessfulUsers
-List[discord.User]
: Users that successfully used the paginator, the first user is the invokerfailedUsers
-List[discord.User]
: Users that failed to use the paginator
Credits
- Contributors of discord-interactions
- dpy-slash-button-paginator
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for dinteractions_Paginator-1.3.7.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | ba45f062a7e156809e59ce5b03e94290e4b3d94292454d408212e2e33a78e834 |
|
MD5 | 7470f42f3d3ca8cca044dc23d9067f6c |
|
BLAKE2b-256 | d96874d4c27e92c0705675e32a44d1285ddb50e29488a3e4c9aa9425f4a48a8b |
Hashes for dinteractions_Paginator-1.3.7-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 52ad985292138a7e18556a375989e0ee0c0e0866fb003e687cea01006d023233 |
|
MD5 | 07cc9c2dcc5c2b86ccfb03ac77dc130e |
|
BLAKE2b-256 | d6bb07e75074b284224757f62d5c9126ef63142bd81a38cdde4e52d450ffcdb9 |