paginator

README

dgo-paginator

dgo-paginator is a paginator working with buttons. It can be used with interactions and normal messages.

Getting Started

Installing

go get github.com/topi314/dgo-paginator

Paginator Usage

// create new dgo session
dg, err := discordgo.New("Bot " + token)

// create a new pagination manager
manager := paginator.NewManager()

// register the pagination handler
dg.AddHandler(manager.OnInteractionCreate)

// add a message create handler to spawn a paginator
dg.AddHandler(func(s *discordgo.Session, m *discordgo.MessageCreate) {
  if m.Author.ID == s.State.User.ID || m.Content != "!test" {
    return
  }

  // your pages can be anything
  pages := []string{
    "page1",
    "page2",
    "page3",
  }
  
  err := manager.CreateMessage(s, m.ChannelID, &paginator.Paginator{
    // the PageFunc is called when a new page is requested put your data per page in here
    PageFunc: func(page int, embed *discordgo.MessageEmbed) {
      embed.Description = pages[page]
    },
    // the max pages this paginator has
    MaxPages:        len(pages),
    // expire after last usage or when created?
    ExpiryLastUsage: true,
  })
  if err != nil {
    fmt.Println(err)
  }
})

// open the session
if err = dg.Open(); err != nil {
  fmt.Println("error opening connection: ", err)
  return
}

// keep the session open
s := make(chan os.Signal, 1)
signal.Notify(s, syscall.SIGINT, syscall.SIGTERM, os.Interrupt)
<-s

EventCollector Usage

Create a new collector by passing it the discordgo.Session & a filter function. The filter function will be called for every event. If the filter function returns true, the event will be collected and passed through the channel. If the filter function returns false, the event will be ignored. If you are done collecting don't forget to close the collector.

eventChannel, stopCollector := event_collector.NewEventCollector(ssession, func(s *discordgo.Session, e *discordgo.MessageCreate) bool {
    return // filter your events here
})

Examples

You can find examples under _examples

Contributing

Contributions are welcomed but for bigger changes please create a discussion.

License

Distributed under the . See LICENSE for more information.

Documentation

Index

• Variables
• func NewEventCollector[E any](session *discordgo.Session, filterFunc func(s *discordgo.Session, e E) bool) (<-chan E, func())
• func WaitForEvent[E any](session *discordgo.Session, ctx context.Context, ...)
• type ButtonsConfig
• type ComponentOptions
• type Config
  • func (c *Config) Apply(opts []ConfigOpt)
• type ConfigOpt
  • func WithButtonsConfig(buttonsConfig ButtonsConfig) ConfigOpt
  • func WithCustomIDPrefix(prefix string) ConfigOpt
  • func WithEmbedColor(color int) ConfigOpt
  • func WithNotYourPaginatorMessage(message string) ConfigOpt
• type Manager
  • func NewManager(opts ...ConfigOpt) *Manager
  • func (m *Manager) CreateInteraction(s *discordgo.Session, interaction *discordgo.Interaction, paginator *Paginator, ...) error
  • func (m *Manager) CreateMessage(s *discordgo.Session, channelID string, paginator *Paginator) error
  • func (m *Manager) OnInteractionCreate(s *discordgo.Session, interaction *discordgo.InteractionCreate)
• type Paginator

Variables

var DefaultConfig = Config{
	ButtonsConfig: ButtonsConfig{
		First: &ComponentOptions{
			Emoji: discordgo.ComponentEmoji{
				Name: "⏮",
			},
			Style: discordgo.PrimaryButton,
		},
		Back: &ComponentOptions{
			Emoji: discordgo.ComponentEmoji{
				Name: "◀",
			},
			Style: discordgo.PrimaryButton,
		},
		Stop: &ComponentOptions{
			Emoji: discordgo.ComponentEmoji{
				Name: "🗑",
			},
			Style: discordgo.DangerButton,
		},
		Next: &ComponentOptions{
			Emoji: discordgo.ComponentEmoji{
				Name: "▶",
			},
			Style: discordgo.PrimaryButton,
		},
		Last: &ComponentOptions{
			Emoji: discordgo.ComponentEmoji{
				Name: "⏩",
			},
			Style: discordgo.PrimaryButton,
		},
	},
	NotYourPaginatorMessage: "You can't interact with this paginator because it's not yours.",
	CustomIDPrefix:          "paginator",
	EmbedColor:              0x4c50c1,
}

Functions

func NewEventCollector

func NewEventCollector[E any](session *discordgo.Session, filterFunc func(s *discordgo.Session, e E) bool) (<-chan E, func())

NewEventCollector returns a channel in which the events of type T gets sent which pass the passed filter and a function which can be used to stop the event collector. The close function needs to be called to stop the event collector.

func WaitForEvent

func WaitForEvent[E any](session *discordgo.Session, ctx context.Context, filterFunc func(s *discordgo.Session, e E) bool, actionFunc func(s *discordgo.Session, e E), cancelFunc func())

WaitForEvent waits for an event passing the filterFunc and then calls the actionFunc. You can cancel this function with the passed context.Context and the cancelFunc gets called then.

Types

type ButtonsConfig

type ButtonsConfig struct {
	First *ComponentOptions
	Back  *ComponentOptions
	Stop  *ComponentOptions
	Next  *ComponentOptions
	Last  *ComponentOptions
}

type ComponentOptions

type ComponentOptions struct {
	Emoji discordgo.ComponentEmoji
	Label string
	Style discordgo.ButtonStyle
}

type Config

type Config struct {
	ButtonsConfig           ButtonsConfig
	NotYourPaginatorMessage string
	CustomIDPrefix          string
	EmbedColor              int
}

func (*Config) Apply

func (c *Config) Apply(opts []ConfigOpt)

Apply applies the given RequestOpt(s) to the RequestConfig & sets the context if none is set

type ConfigOpt

type ConfigOpt func(config *Config)

func WithButtonsConfig

func WithButtonsConfig(buttonsConfig ButtonsConfig) ConfigOpt

func WithCustomIDPrefix

func WithCustomIDPrefix(prefix string) ConfigOpt

func WithEmbedColor

func WithEmbedColor(color int) ConfigOpt

func WithNotYourPaginatorMessage

func WithNotYourPaginatorMessage(message string) ConfigOpt

type Manager

type Manager struct {
	Config Config
	// contains filtered or unexported fields
}

func NewManager

func NewManager(opts ...ConfigOpt) *Manager

func (*Manager) CreateInteraction

func (m *Manager) CreateInteraction(s *discordgo.Session, interaction *discordgo.Interaction, paginator *Paginator, acknowledged bool) error

func (*Manager) CreateMessage

func (m *Manager) CreateMessage(s *discordgo.Session, channelID string, paginator *Paginator) error

func (*Manager) OnInteractionCreate

func (m *Manager) OnInteractionCreate(s *discordgo.Session, interaction *discordgo.InteractionCreate)

type Paginator

type Paginator struct {
	PageFunc        func(page int, embed *discordgo.MessageEmbed)
	MaxPages        int
	CurrentPage     int
	Creator         string
	Expiry          time.Time
	ExpiryLastUsage bool
	ID              string
}