slack_message 2.4.0 → 3.0.2

data/docs/03_message_dsl.md

@@ -0,0 +1,387 @@
+## 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.
+
+### Explicitly Declared 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 an `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. But, you may have troubles when you start adding
+more complicated elements to your messages.
+
+### 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 style specifically named default, but in my
+experience, a colorful button is way more common.
+
+You can override 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
+```
+
+### Images and Accessory Images
+
+There are two main types of images in Slack: the
+[image](https://imgur.com/XEUap1r) and the [accessory
+image](https://imgur.com/zuhjBDq). In short, `accessory_image` is part of a
+section itself and is shown alongside an existing block, while `image` is shown
+as its own top-level element.
+
+Accordingly, an accessory image should be used within a section. An accessory
+image can accept alt-text, which is also a best practice, for usability
+reasons.
+
+```ruby
+SlackMessage.build do
+  section do
+    text 'Looks like the coffee machine is empty.'
+    accessory_image 'https://your.com/empty_coffee_logo.jpg', alt_text: 'logo of a forlorn coffee cup'
+  end
+end
+```
+
+Only one accessory image can be used per section, and declaring more will issue
+a warning and simply override the previous accessory image.
+
+By contrast, `image` can be used many times, and will create a new top-level
+section for each call. Image accepts alt-text, but also a title, which will
+be displayed above the image (along with an icon to collapse the image).
+
+```ruby
+SlackMessage.build do
+  section do
+    text 'Most Recent Tiny Pig Images'
+  end
+
+  image 'https://your.com/employee_pets/best/pig_1.jpg', alt_text: 'a tiny pig eating ice cream', title: 'Spider Pig'
+  image 'https://your.com/employee_pets/best/pig_2.jpg', alt_text: 'a tiny pig smiling mischeviously', title: 'Porkeypine'
+  image 'https://your.com/employee_pets/best/pig_3.jpg', alt_text: 'a tiny pig with wellies and an umbrella', title: 'Albert Sweinstein'
+end
+```
+
+Sectionless messages can also use `accessory_image`, but this can get confusing
+since they could potentially be interspersed with top-level images, so I
+wouldn't recommend it.
+
+```ruby
+# the difference between these two image styles is confusing, and the call
+# to `image` closed the current section and started a new one.
+SlackMessage.build do
+  text 'Looks like the coffee machine is empty.'
+  accessory_image 'https://your.com/empty_coffee_logo.jpg'
+
+  text '*Most Recent Coffee Maker Surveillance Photo*'
+  image 'https://your.com/surveillance/coffee/current.jpg'
+end
+```
+
+### 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 only one can be added to your entire
+slack message. Specifying another `context` will issue a warning and overwrite
+any previous call.
+
+### 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 change to the message payload from these calls, use `debug` mode.
+
+The `bot_icon` can be specified as either an emoji (`:shipit:`), 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.  Only one custom notification is allowed, so further calls will issue a
+warning and replace the previous notification text.
+
+---
+
+Next: [Editing Messages](https://jmmastey.github.io/slack_message/04_editing_messages)

data/docs/04_editing_messages.md

@@ -0,0 +1,87 @@
+## 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 long after you post the original message, you
+may want to persist a reference to the message 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.
+
+```ruby
+message = SlackMessage.post_to('#general') do
+  text "Testing: #{SLACK_SECRET_KEY}"
+end
+```
+
+Then you can simply call the `delete` method to make up for your mistakes.
+
+```ruby
+SlackMessage.delete(message)
+```
+
+*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.*
+
+As with editing a message, it's possible to persist messages to redis / your
+database to be removed at a later date.
+
+```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,53 @@
+* [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.
+
+---
+
+Next: [Get Started](https://jmmastey.github.io/slack_message/01_configuration)