spanner

README

Spanner for Slack

Spanner is a Go framework for building interactive Slack applications.

The framework adopts a model inspired by Streamlit with a single event handling loop to construct your UI and to respond to user input - so you can iterate faster and focus on your business logic!

Getting Started

Create a Slack app

In order to develop an app, you'll need to create one in your Slack workspace. You can find instructions for creating a Socket mode app at: https://api.slack.com/apis/connections/socket#creating

Setup

Import the framework into your project with `go get``:

go get github.com/theothertomelliott/spanner

Then import the API and Slack application package into your app:

import (
  "github.com/theothertomelliott/spanner"
  "github.com/theothertomelliott/spanner/slack"
)

Your application

Now you can define an application and run it:

app, err := slack.NewApp(
    slack.AppConfig{
        BotToken: botToken,
        AppToken: appToken,
    },
)
if err != nil {
    log.Fatal(err)
}

err = app.Run(func(ev Event) error {
    // TODO: Handle events here
    return nil
})
if err != nil {
    log.Fatal(err)
}

Where botToken and appToken are the tokens you created for your Slack application.

Handling Events

The function passed in to app.Run is your event handling function, and will be called every time Slack sends an event to your app. In the example above, our app will ignore every event, so let's do something with messages coming in.

err = app.Run(func(ev spanner.Event) error {
    if msg := ev.ReceiveMessage(); msg != nil && msg.Text() == "hello" {
        reply := msg.SendMessage()
        reply.Text(fmt.Sprintf("Hello to you too: %v", msg.User()))
    }
    return nil
})

The code above will listen for messages in any channel your bot is in, and if the text of a messge is exactly "hello", will respond with a greeting.

UI Elements

You can also easily add UI elements to your messages. Let's add a dropdown to our message and do something with the option the user chooses.

err = app.Run(func(ev spanner.Event) error {
    if msg := ev.ReceiveMessage(); msg != nil && msg.Text() == "hello" {

        reply := ev.SendMessage()
        reply.Text(fmt.Sprintf("Hello to you too: %v", msg.User()))

        letter := reply.Select("Pick a letter", spanner.SelectOptions("a", "b", "c"))
        if letter != "" {
            ev.SendMessage().Text(fmt.Sprintf("You chose %q", letter))
        }
    }
    return nil
})

Examples

A set of examples can be found in the examples directory.

Documentation

Index

• type App
• type BlockUI
• type Channel
• type CustomEvent
• type Event
• type Message
• type Metadata
• type Modal
• type ModalCreator
• type ModalSubmission
• type Option
  • func Options(options ...string) []Option
• type ReceivedMessage
• type SlashCommand
• type User

Types

type App

type App interface {
	Run(func(ev Event) error) error
	SendCustom(CustomEvent) error
}

App is the top level for a chat application. Call Run with an event handling function to start the application.

type BlockUI

type BlockUI interface {
	Header(message string)
	PlainText(text string)
	Markdown(text string)
	TextInput(label string, hint string, placeholder string) string
	MultilineTextInput(label string, hint string, placeholder string) string
	Divider()
	Select(title string, options []Option) string
	MultipleSelect(title string, options []Option) []string
	Button(label string) bool
}

BlockUI allows the creation of Slack blocks in a message or modal.

type Channel

type Channel interface {
	ID() string
	Name() string
}

type CustomEvent

type CustomEvent interface {
	Body() map[string]interface{}
}

type Event

type Event interface {
	Connected() bool
	Custom() CustomEvent
	ReceiveMessage() ReceivedMessage
	SlashCommand(command string) SlashCommand

	JoinChannel(channelID string)
	SendMessage(channelID string) Message
}

Event represents an event received from the Slack platform. It provides functions representing each type of event that can be received. For example, ReceivedMessage will return a message that may have been received in this event. Functions will return nil if the current event does not match the type of event.

type Message

type Message interface {
	BlockUI

	Channel(channelID string)
}

Message represents a message that can be sent to Slack. Messages are constructed using BlockUI commands.

type Metadata

type Metadata interface {
	User() User
	Channel() Channel
}

Metadata provides information common to all events.

type Modal

type Modal interface {
	BlockUI
	Submit(title string) ModalSubmission
	Close(title string) bool
}

Modal represents a Slack modal view. It can be used to create blocks and handle submission or closing of the modal.

type ModalCreator

type ModalCreator interface {
	Modal(title string) Modal
}

ModalCreator is an interface that can be used to create Slack modal views.

type ModalSubmission

type ModalSubmission interface {
	Push(title string) Modal
}

ModalSubmission handles a modal being submitted. It can be used to send a response message or push a new modal onto the stack.

type Option

type Option struct {
	Label       string
	Description string
	Value       string
}

Option defines an option for select or checkbox blocks.

func Options

func Options(options ...string) []Option

Options is a convenience function to create a set of options from a list of strings. The strings are used as both the label and value. The descriptions are left empty.

type ReceivedMessage

type ReceivedMessage interface {
	Metadata
	Text() string
}

ReceivedMessage represents a message received from Slack.

type SlashCommand

type SlashCommand interface {
	Metadata
	ModalCreator
}

SlashCommand represents a received slash command. Messages and modal views may be created in response to the command.

type User

type User interface {
	ID() string
	Name() string
	RealName() string
	Email() string
}