slack_message 2.3.0 → 3.0.1

data/docs/03_message_dsl.md

@@ -0,0 +1,326 @@
+### The Message DSL
+
+A pretty good number of the elements available in BlockKit are usable in SlackMessage. There are also a few elements that haven't been implemented in the official API, but are too useful to be missing.
+
+#### Basic Text
+
+While BlockKit officially requires that any elements are contained within a section element, that requirement is relaxed in SlackMessage. If you don't specify a section, one will silently be created to encapsulate your code. That's the secret behind the most basic messages in these docs.
+
+```ruby
+SlackMessage.build do
+  text "couldn't be easier"
+end
+
+# => [{:type=>"section",
+#  :text=>{:type=>"mrkdwn", :text=>"couldn't be easier"}
+# }]
+```
+
+This is equivalent to the more verbose version with a declared section.
+
+```ruby
+SlackMessage.build do
+  section do
+    text "could be easier"
+  end
+end
+
+# => [{:type=>"section",
+#  :text=>{:type=>"mrkdwn", :text=>"could be easier"}
+# }]
+```
+
+Text elements are the most basic type of element. Adding multiple text calls
+will add a newline between text calls, which will cause a line break
+appropriately.
+
+```ruby
+SlackMessage.build do
+  text "one fish, two fish"
+  text "red fish, blue fish"
+end
+
+# => [{:type=>"section",
+#  :text=>{:type=>"mrkdwn", :text=>"one fish, two fish\nred fish, blue fish"}
+# }]
+```
+
+Slack uses a [faux-markdown syntax called
+mrkdwn](https://api.slack.com/reference/surfaces/formatting#basics), which you
+may be familiar with by typing in the Slack app itself. The API will
+automatically render mrkdwn appropriately.
+
+```ruby
+SlackMessage.build do
+  text "*Favorite Colors*"
+  text "_John_: ~red~ actually blue."
+end
+
+# => [{:type=>"section",
+# :text=>{:type=>"mrkdwn", :text=>"*Favorite Colors*\n_John_: ~red~ actually blue."}}]
+```
+
+Rendering emoji in messages is possible using either a) real unicode emoji in
+your message, or b) using the `:emojiname:` syntax, which supports any emoji
+that would work in your Slack app itself, including custom emoji.
+
+```ruby
+SlackMessage.build do
+  text ":shipit_squirrel:🚀 time to gooo :tada:"
+end
+
+# => [{:type=>"section",
+#   :text=>{:type=>"mrkdwn", :text=>":shipit_squirrel:🚀 time to gooo :tada:"}
+# }]
+```
+
+To add a link using Slack's non-markdown link syntax, use the `link` helper
+method interpolated into a text element. Using the `link` helper as its own
+element won't work, as the method simply returns a string that has to be
+included into a text element specifically.
+
+```ruby
+SlackMessage.build do
+  text "Your #{link('build', 'https://google.com')} is ready."
+end
+
+# => [{:type=>"section",
+#  :text=>{:type=>"mrkdwn", :text=>"Your <https://google.com|build> is ready."}
+# }]
+```
+
+While the API squishes whitespace (much in the same way HTML does), it may
+sometimes be useful to add a blank line between text _without_ adding a new
+section to your message. To do so, use the pseudo-element `blank_line`.
+
+```ruby
+SlackMessage.build do
+  text "don't let this line"
+  blank_line
+  text "touch this line."
+end
+
+# => => [{:type=>"section",
+#  :text=>{:type=>"mrkdwn", :text=>"don't let this line\n \ntouch this line."}
+# }]
+```
+
+Note that between the two newlines in the above example is a unicode emspace,
+which the API will respect as a line worth rendering.
+
+#### Buttons
+
+BlockKit allows you to specify a button to the right of a section / block. That
+button will be aligned outside the normal space for a section, and is meant to
+link out of the app. To create one of these, use the `link_button` helper.
+
+```ruby
+SlackMessage.build do
+  text "Your daily stats are ready @here"
+  link_button "Stats Dashboard", stats_dashboard_url
+end
+
+# => [{:type=>"section",
+# :text=>{:type=>"mrkdwn", :text=>"Your daily stats are ready @here"},
+# :accessory=>
+#  {:type=>"button",
+#   :url=>"http://yoursite.com/stats_dashboard",
+#   :text=>{:type=>"plain_text", :text=>"Stats Dashboard", :emoji=>true},
+#   :style=>:primary}}]
+```
+
+Slack allows three styles for buttons: `default`, `primary`, and `danger`.
+These correspond to gray, green and red buttons respectively. If not specified,
+SlackMessage will use the `primary` style for buttons. I get that this could be
+confusing when there is a default style, but in my experience, a colorful button
+is way more common.
+
+You can override the button style by specifying the style with your link button.
+
+```ruby
+SlackMessage.build do
+  text "A job has failed catastrophically!"
+  link_button "Sidekiq Dashboard", sidekiq_dashboard_url, style: :danger
+end
+
+# => [{:type=>"section",
+# :text=>{:type=>"mrkdwn", :text=>"A job has failed catastrophically!"},
+# :accessory=>
+#  {:type=>"button",
+#   :url=>"https://yoursite.com/sidekiq",
+#   :text=>{:type=>"plain_text", :text=>"Sidekiq Dashboard", :emoji=>true},
+#   :style=>:danger}}]
+```
+
+#### Ordered and Unordered Lists
+
+The Slack API doesn't have native support for HTML-style ordered and unordered
+lists, but there are convenience methods in SlackMessage to render a close
+approximation.
+
+```ruby
+SlackMessage.build do
+  section do
+    text '*Pet Goodness Tiers*'
+
+    ol([
+      'tiny pigs',
+      'reptiles',
+      'dogs',
+      'cats',
+    ])
+  end
+
+  section do
+    text '_voted by_'
+    ul(['Joe', 'Emily', 'Sophia', 'Matt'])
+  end
+end
+```
+
+Because Slack automatically collapses leading whitespace, indention of lists is
+handled using unicode emspaces. Bullets for unordered lists are also unicode
+characters to avoid being read as markdown.
+
+#### List Items (e.g. HTML dt & dd)
+
+When trying to represent title / value lists, you can use the "list item" block
+type to pass a set of values. Slack does not allow you to customize how many
+items are shown per line, so you'll just have to work with it.
+
+```ruby
+SlackMessage.build do
+  text 'Import results are available!'
+
+  list_item 'Import Date', Date.today.to_s
+  list_item 'Items Imported', 55_000
+  list_item 'Errors', 23
+  list_item 'Bad Values', errors.map(&:to_s)
+end
+```
+
+#### Including Multiple Sections
+
+Adding more sections is trivial. Simply declare each section and it will be
+separated in the rendered message. This can often occur when looping.
+
+```ruby
+SlackMessage.build do
+  pet_types.each do |type, breeds|
+    section do
+      text "*#{type}:* #{breeds.join(", ")}"
+    end
+  end
+end
+```
+
+It can also be useful to add a visual divider (similar to a `hr` in HTML)
+between sections. To add one of these, use the `divider` helper. You can also
+add a divider at the end of all the sections, but it often looks silly.
+
+```ruby
+SlackMessage.build do
+  section do
+    text "*Topsiders:* Emily, Elsie, Derick"
+  end
+
+  divider
+
+  section do
+    text "*Undergrounders:* Kristina, Lauren, Different Emily"
+  end
+end
+
+# => [
+#  {:type=>"section", :text=>{:type=>"mrkdwn", :text=>"*Topsiders:* Emily, Elsie, Derick"}},
+#  {:type=>"divider"},
+#  {:type=>"section", :text=>{:type=>"mrkdwn", :text=>"*Undergrounders:* Kristina, Lauren, Different Emily"}}
+# ]
+```
+
+Note that a divider can only occur between sections, not within a single
+section. Because of how implicit sections are built, it may look like this works
+for simple messages. You may have troubles when you start adding more
+complicated elements to your messages.
+
+#### Images
+TODO: image, accessory_image
+
+#### Footers (Context)
+
+Slack allows you to add a small additional piece of text to your message, which
+will be rendered in italics and small text. It can support both links and emoji,
+and is useful for providing minor details for your message.
+
+```ruby
+SlackMessage.build do
+  text "New coffee complaints have been added."
+  context "this complaint added by #{link('Joe Mastey', 'hello@joemastey.com')}."
+end
+
+# => [{:type=>"section",
+#      :text=>{:type=>"mrkdwn", :text=>"New coffee complaints have been added."}
+#     },
+#     {:type=>"context", :elements=>
+#       [{:type=>"mrkdwn",
+#         :text=>"this complaint added by <hello@joemastey.com|Joe Mastey>."
+#     }]
+# }]
+```
+
+Context does not belong to a section, and is per-message, not per-section.
+Specifying more than one context will simply overwrite previous calls.
+
+#### Bot Customization
+
+By default - and with scheduled messages - Slack will use the name and icon of
+the Slack app whose API key you configured. As seen before, it's
+possible to override those default names and icons in configuration. However, it
+can also be customized per-message.
+
+```ruby
+SlackMessage.build do
+  bot_icon ":sad_robot:"
+  bot_name "BadNewsBuildBot"
+
+  text "The build is broken. @here"
+end
+
+# => [{:type=>"section", :text=>{:type=>"mrkdwn", :text=>"The build is broken. @here"}}]
+```
+
+Notice that the bot details aren't shown in the output of the `build` command.
+To view the changes these methods cause, use `debug` mode.
+
+The `bot_icon` can be specified as either an emoji (`:example:`), or a URL
+pointing to an image (`http://mysite.com/shipit.png`). Any other value seems to
+cause an error.
+
+#### Custom Notification Text
+
+For users who have notifications turned on, Slack will provide a small message
+preview when you send them a message. By default, this preview will take the
+first several words from your message.
+
+However, you can specify some custom notification text to be shown to the user.
+This text supports basic emoji and formatting, but nothing complicated.
+
+```ruby
+SlackMessage.build do
+  notification_text "Having issues with the build. :ohnoes:"
+
+  text "The build is broken. The error message was 'undefined method round for NilClass'"
+
+# => [{:type=>"section",
+# :text=>
+#  {:type=>"mrkdwn",
+#   :text=>"The build is broken. The error message was 'undefined method round for NilClass'"}}]
+end
+```
+
+Again notice that notification text is not set within the blocks themselves, so
+you will need to enable debugging to see how it changes what is sent to the API.
+
+---
+
+Next: [Editing Messages](https://jmmastey.github.io/slack_message/04_editing_messages)

data/docs/04_editing_messages.md

@@ -0,0 +1,88 @@
+### Updating a Previous Message
+
+After you've posted a message, you may want to edit it later. Interactive bots,
+for instance, may want to repeatedly update a message.
+
+Posting will always return an object representing your posted message.
+
+```ruby
+message = SlackMessage.post_to('#general') do
+  text "Getting ready..."
+end
+```
+
+Then, you can use that response object to go back and rewrite the message a
+little or a lot.
+
+```ruby
+SlackMessage.update(message) do
+  text "Done!"
+end
+```
+
+The new message contents will be built and updated via the API. To give an
+example, you could alert slack to a job status by updating your original
+message.
+
+
+```ruby
+class SomeWorker < ApplicationWorker
+  def perform
+    post_started_status
+
+    # ... perform work here
+
+    post_finished_status
+  end
+
+  private
+
+  def post_started_status
+    @message = SlackMessage.post_as(:job_worker) do
+      text "Beginning upload."
+    end
+  end
+
+  def post_finished_status
+    SlackMessage.update(@message) do
+      text "Finished upload! @here come and get it."
+      link_button "See Results", uploaded_data_url
+    end
+  end
+end
+```
+
+#### Storing Response Objects for Later
+
+Since updates are likely to occur after you've long since finished posting the
+original message, you'll need to persist the message response somehow until you
+need to update it later. As one option, you could serialize the response object
+for later.
+
+```ruby
+# initially
+message = SlackMessage.post_to('#general') do
+  text "Starting..."
+end
+redis_connection.set(self.message_cache_key, Marshal.dump(message))
+
+
+# later
+message = Marshal.load(redis_connection.get(self.message_cache_key))
+SlackMessage.update(message) do
+  text "Finished!"
+end
+```
+
+#### Updating Scheduled Messages
+
+Sadly, there's currently no way to edit a scheduled message. You'll receive an
+error if you attempt to call `update` on a scheduled message.
+
+See the [API documentation for
+chat.update](https://api.slack.com/methods/chat.update) for more information on
+updating messages.
+
+---
+
+Next: [Deleting Messages](https://jmmastey.github.io/slack_message/05_deleting_messages)

data/docs/05_deleting_messages.md

@@ -0,0 +1,45 @@
+### Deleting Messages
+
+Deleting a message is much like editing a message, only simpler. Just like when
+you edit a message, you'll need a reference to the message you posted.
+
+*Important Note: It's not possible to delete a message sent directly to a user.
+It's also not possible to delete a scheduled message once it's already posted.
+Don't send anything you don't want your boss to read.*
+
+```ruby
+message = SlackMessage.post_to('#general') do
+  text "Testing: #{SLACK_SECRET_KEY}"
+end
+```
+
+Now you can simply call the `delete` method to make up for your mistakes.
+
+```ruby
+SlackMessage.delete(message)
+```
+
+As with editing a message, it's possible to persist messages to redis / your
+database and remove them using the timestamp and channel of your message.
+
+```ruby
+# initially
+message = SlackMessage.post_to('#general') do
+  text "Testing: #{SLACK_SECRET_KEY}"
+end
+redis_connection.set(self.message_cache_key, Marshal.dump(message))
+
+
+# later
+message = Marshal.load(redis_connection.get(self.message_cache_key))
+SlackMessage.delete(message)
+```
+
+See the [API documentation for
+chat.delete](https://api.slack.com/methods/chat.delete) or
+[chat.deleteScheduledMessage](https://api.slack.com/methods/chat.deleteScheduledMessage)
+for more information on deleting messages.
+
+---
+
+Next: [Mentions / Notifying Users](https://jmmastey.github.io/slack_message/06_notifying_users)

data/docs/06_notifying_users.md

@@ -0,0 +1,62 @@
+## Mentions / Notifying Users
+
+There are several supported ways to tag and notify users. As mentioned
+initially, it's possible to DM a user by their account email.
+
+```ruby
+SlackMessage.post_to('hello@joemastey.com') do
+  text "Hi there!"
+end
+```
+
+You can also mention a user by email within a channel by wrapping their name in
+tags.
+
+```ruby
+SlackMessage.post_to('#general') do
+  bot_name "CoffeeBot"
+  bot_icon ":coffee:"
+
+  text ":coffee: It's your turn to make coffee <hello@joemastey.com>."
+end
+```
+
+Emails that are not wrapped in tags will be rendered as normal email addresses.
+Additionally, Slack will automatically convert a number of channel names and
+tags you're probably already used to.
+
+```ruby
+SlackMessage.post_to('#general') do
+  bot_name "CoffeeBot"
+  bot_icon ":coffee:"
+
+  text "@here There's no coffee left! Let #general know when you fix it."
+end
+```
+
+By default, the desktop notification for a message will be the text of the
+message itself. However, you can customize desktop notifications if you prefer.
+
+```ruby
+SlackMessage.post_to('hello@joemastey.com') do
+  bot_name "CoffeeBot"
+  bot_icon ":coffee:"
+
+  notification_text "It's a coffee emergency!"
+  text "There's no coffee left!"
+end
+```
+
+#### Using @channel or @here
+
+Not really a feature, but Slack will respect usage of `@here` and `@channel`.
+
+```ruby
+SlackMessage.post_to('#general') do
+  text "Hey @channel, don't forget to submit your drink requests."
+end
+```
+
+---
+
+Next: [Testing](https://jmmastey.github.io/slack_message/07_testing)

data/docs/07_testing.md

@@ -0,0 +1,49 @@
+## Testing
+
+You can do some basic testing against SlackMessage, at least if you use RSpec!
+You'll need to require and include the testing behavior in your spec_helper
+file.
+
+```ruby
+require 'slack_message/rspec'
+
+RSpec.configure do |config|
+  include SlackMessage::RSpec
+
+  # your other spec_helper config
+end
+```
+
+This will prevent API calls from leaking in your tests, and will allow you
+access to some custom matchers.
+
+```ruby
+expect {
+  SlackMessage.post_to('#general') { text "foo" }
+}.to post_slack_message_to('#general').with_content_matching(/foo/)
+
+expect {
+  SlackMessage.post_as(:schmoebot) { text "foo" }
+}.to post_slack_message_as(:schmoebot)
+
+expect {
+  SlackMessage.post_as(:schmoebot) { text "foo" }
+}.to post_slack_message_as('Schmoe Bot')
+
+expect {
+  SlackMessage.post_as(:schmoebot) { text "foo" }
+}.to post_slack_message_with_icon(':schmoebot:')
+
+expect {
+  SlackMessage.post_as(:schmoebot) { text "foo" }
+}.to post_slack_message_with_icon_matching(/gravatar/)
+
+expect {
+  SlackMessage.post_to('#general') { text "foo" }
+}.to post_to_slack
+```
+
+Be forewarned, I'm frankly not that great at more complicated RSpec matchers,
+so I'm guessing there are some bugs. Also, because the content of a message
+gets turned into a complex JSON object, matching against content isn't capable
+of very complicated regexes.

data/docs/_config.yml

@@ -0,0 +1,6 @@
+plugins:
+  - jekyll-relative-links
+relative_links:
+  enabled: true
+  collections: true
+theme: jekyll-theme-midnight

data/docs/index.md

@@ -0,0 +1,49 @@
+* [Getting Started / Configuration](https://jmmastey.github.io/slack_message/01_configuration)
+* [Posting a Message](https://jmmastey.github.io/slack_message/02_posting_a_message)
+* [The SlackMessage DSL](https://jmmastey.github.io/slack_message/03_message_dsl)
+* [Editing Messages](https://jmmastey.github.io/slack_message/04_editing_messages)
+* [Deleting Messages](https://jmmastey.github.io/slack_message/05_deleting_messages)
+* [Mentions / Notifying Users](https://jmmastey.github.io/slack_message/06_notifying_users)
+* [Testing](https://jmmastey.github.io/slack_message/07_testing)
+
+SlackMessage is a gem that makes it easy to send messages to Slack from your
+application. _Really_ easy.
+
+```ruby
+SlackMessage.post_to('#general') do
+  text "We did it @here! :thumbsup:"
+end
+```
+
+And not just simple messages. You can compose complicated messages quickly in a
+DSL that's focused on usability and maintainability. It can be tough to
+maintain code in other similar gems, but not here.
+
+```ruby
+SlackMessage.post_to('hello@joemastey.com') do
+  section do
+    text "A job has generated some output for you to review."
+    text 'And More' * 10
+    link_button "See Results", "https://google.com"
+  end
+
+  section do
+    text ":unlock-new: New Data Summary"
+
+    list_item "Date", "09/05/2021"
+    list_item "Total Imported", 45_004
+    list_item "Total Errors", 5
+  end
+
+  divider
+
+  section do
+    text "See more here: #{link('result', 'https://google.com')}"
+  end
+
+  context "Kicked off by <hello@joemastey.com> at **9:05am**"
+end
+```
+
+It has no dependencies and minimal configuration needs, so you can get up and
+running quickly.