spacemacs/layers/+chat/slack/README.org

#+TITLE: Slack layer

#+TAGS: chat|layer

[[file:img/slack.png]]

* Table of Contents                     :TOC_5_gh:noexport:
- [[#description][Description]]
  - [[#features][Features:]]
- [[#install][Install]]
- [[#configuration][Configuration]]
  - [[#spacemacs-layout-integration][Spacemacs layout integration]]
- [[#key-bindings][Key bindings]]

* Description
This layer provides an interface to the Slack chat service via the emacs-slack
package. Where possible, this layer aims to reuse key bindings from the IRC
packages in Spacemacs.

** Features:
- Real time messaging with [[https://github.com/ahyatt/emacs-websocket][emacs-websocket]]
- Connect to multiple slack instances
- Notifications with [[https://github.com/jwiegley/alert][alert.el]]

* Install
To use this configuration layer, add it to your =~/.spacemacs=. You will need to
add =slack= to the existing =dotspacemacs-configuration-layers= list in this
file.

* Configuration
Follow the instructions in the [[https://github.com/yuya373/emacs-slack/blob/master/README.md][emacs-slack]] package for obtaining your client ID,
client secret, and token.

To test that everything is alright put the following snippet in your
=dotspacemacs/user-config()= replacing =client-id=, =client-secret= and =token=
with your info.

*Important* Do not keep private data in your dotfile. You can put your private
stuff elsewhere (like Dropbox for instance) and load the file in your dotfile.

#+BEGIN_SRC emacs-lisp
  (slack-register-team
    :name "emacs-slack"
    :default t
    :client-id "my@email.address"
    :client-secret "mypassword"
    :token "token"
    :subscribed-channels '(general slackbot))
#+END_SRC

** Spacemacs layout integration
A [[https://github.com/syl20bnr/spacemacs/blob/develop/doc/DOCUMENTATION.org#layouts-and-workspaces][Spacemacs custom layout]] is defined by the layer. The name and the key binding
for it can be customized with the following layer variables:
- =slack-spacemacs-layout-name= for the layout name,
- =slack-spacemacs-layout-binding= for the key binding.

By default the values are:

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers '(
    (slack :variables slack-spacemacs-layout-name "@Slack"
                      slack-spacemacs-layout-binding "s")))
#+END_SRC

* Key bindings

| Key binding   | Description                              |
|---------------+------------------------------------------|
| ~SPC a c s T~ | Show all threads followed in a workspace |
| ~SPC a c s d~ | Direct message someone                   |
| ~SPC a c s g~ | Join a group (private channel)           |
| ~SPC a c s j~ | Join a channel                           |
| ~SPC a c s q~ | Close connection                         |
| ~SPC a c s r~ | Join a channel, group, or direct messge  |
| ~SPC a c s s~ | (Re)connects to Slack                    |
| ~SPC a c s u~ | Show all unread in a workspace           |
| ~SPC m (~     | Remove reaction (emoji) to a message     |
| ~SPC m )~     | Add reaction (emoji) to a message        |
| ~SPC m c~     | Embed mention of channel                 |
| ~SPC m d~     | Direct message someone                   |
| ~SPC m e~     | Edit message at point                    |
| ~SPC m j~     | Join a channel                           |
| ~SPC m m~     | Embed mention of user                    |
| ~SPC m p~     | Load previous messages                   |
| ~SPC m q~     | Quit Slack                               |
| ~SPC m t~     | Show or create thread                    |

The following bindings are provided to mimic bindings in the official Slack
client.

| Key binding | Description              |
|-------------+--------------------------|
| ~SPC m #~   | Embed mention of channel |
| ~SPC m )~   | Add a rection            |
| ~SPC m :~   | Embed emoji              |
| ~SPC m @~   | Embed mention of user    |
| ~SPC m k~   | Join a channel           |

In insert state, one can also use ~:~, ~@~, and ~#~ directly without the leader
key prefix.