pushpop-slack 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 88e7bfe71d848db00fcea152b73da9cd401e7463
-  data.tar.gz: 58dcb70eb30b0829c005765e39083138a29eaef9
+  metadata.gz: 8e09451bfe1d62cf7aad3d1cda7579f1f7fe95d1
+  data.tar.gz: f091b0e336e72347cbe3456ce84ffceafca57fe0
 SHA512:
-  metadata.gz: a6316f2ba699f0e903e70e08542d42778b51e2cf4366b6b9ddc7a2209e5979cfe3b579f82ad1ad721ad7d555550b4a6087eb5976d2db0bc3896d93425de46b1e
-  data.tar.gz: e1e60d5482a8853fe9b9053d7d4a0d859b63bfaf4e4bb1dcc57d83b8e299bd2c2bc228fa09b3b477c8f4246a390f9360b0df230066b81bfc4c22809fbcf262e2
+  metadata.gz: 499e1b5cda4338e1f1992e5529c04a812da51919e85f66c9878ca5441aae4d351866bfdb94776ca8c8f6ee8736c1b294c9368b750d073338f695b855dbf56ed0
+  data.tar.gz: fca4e494f792234613818b929723196e9b81fff5efeb31d09fbf1ad839d1905f76f93e9995dc642effd13f75c1aed7f8dbd5f04887a2af0271db43de8b63bceb

data/README.md

@@ -1,32 +1,159 @@
 ## pushpop-plugin
 
-A template for creating [Pushpop](https://github.com/keenlabs/pushpop) plugins that can
-be published as gems and easily included in Pushpop projects.
+A [Pushpop](https://github.com/pushpop-project/pushpop) plugin for sending messages to Slack
 
-See [pushpop-github](https://github.com/pushpop-project/pushpop-github) for an example
-of a plugin/gem.
+### Installation
+
+Add `pushpop-slack` gem to your Gemfile
+
+```ruby
+gem 'pushpop-slack'
+```
+
+or install it as a gem
+
+```bash
+$ gem install pushpop-slack
+```
+
+You will also need to set an environment variable for your Slack Webhook. Here's how:
+
+1. Go to your Slack team site and [create an Incoming Webhooks integration](slack.com/services/new).
+2. Choose a default channel for pushpop messages. You can override this in the actual job.
+3. Copy the `Webhook URL`.
+4. Set that to `SLACK_WEBHOOK_URL` in your environment ([heroku](https://devcenter.heroku.com/articles/config-vars), [shell](https://www.digitalocean.com/community/tutorials/how-to-read-and-set-environmental-and-shell-variables-on-a-linux-vps))
 
 ### Usage
 
-Clone this repository, and rename it to pushpop-<plugin>, where plugin is the name of
-what you're building. Update files and references to reflect your plugin name, and add your code.
+`pushpop-slack` has a pretty easy DSL for sending messages to slack, and also handles all of the weird formatting that Slack requires. It copies much of the functionality of the [slack-notifier](https://github.com/stevenosloan/slack-notifier) gem, which is used internally.
+
+Here's a very basic example of sending a message to slack:
+
+```ruby
+job 'send "Hello, World!" to #general'
 
-For others to easily use your plugin, you'll want to create a Ruby gem. Once you have a Rubygems
-account and are authorized, you can publish the gem:
+	slack do
+		message 'Hello, World!'
+	end
 
-``` shell
-$ gem build pushpop-<plugin>.gemspec
-$ gem push pushpop-<plugin>-0.1.0.gem
+end
 ```
 
-Users will then be able to use your plugin by including it in their Gemfile:
+#### Links
+
+We use slack-notifier's [`LinkFormatter`](https://github.com/stevenosloan/slack-notifier#links) internally. That means you can either use HTML or Markdown format for your links
+
+```ruby
+job 'send "Hello, World!" to #general'
+
+	slack do
+		message 'Where [in the world](http://en.wikipedia.org/wiki/Carmen_Sandiego) is Carmen Sandiego?'
+		# or
+		message 'Have you seen this <a href="http://en.wikipedia.org/wiki/Carmen_Sandiego">in the world</a> is Carmen Sandiego?'
+	end
+
+end
+```
+
+#### Setting the channel
+
+Your webhook has a default channel that it sends to, but you can also choose a custom channel at runtime
+
+
+```ruby
+job 'send "Hello, World!" to #general'
+
+	slack do
+		message 'Hello, World!'
+		channel '#alerts'
+	end
+
+end
+```
+
+Slack expects the `#` before your channel name. However, if you forget it, pushpop-slack will insert it there for your convenience
+
+#### Username
+
+You can choose a custom username for your message to "come from". This can be a completely new username, or an existing one.
+
+```ruby
+job 'send "Hello, World!" to #general'
+
+	slack do
+		message 'Hello, World!'
+		username 'Carmen Sandiego'
+	end
+
+end
+```
+
+#### Icon
+
+You can also set the avatar/icon for the "user" sending the message. Paired with the [Username](#username), this can make your pushpop messages look like they're from a real user.
+
+You can use emoji icons, or just use an image anywhere on the internet. For emoji, use the slack formatting (ie: `:ghost:`). For an image on the internet, just enter a URL (must start with `http`).
+
+```ruby
+job 'send "Hello, World!" to #general'
+
+	slack do
+		message 'Hello, World!'
+		icon ':ghost:'
+		# or
+		icon 'https://upload.wikimedia.org/wikipedia/en/e/ed/Carmen_Sandiego.png'
+	end
+
+end
+```
+
+#### Unfurl
+
+By default, Slack does not [unfurl](https://api.slack.com/docs/unfurling) links from Webhooks (only media, like images). You can override that default by calling unfurl.
+
+Calling `unfurl` with no parameter will default to true, or you can pass it a boolean.
+
+```ruby
+job 'send "Hello, World!" to #general'
+
+	slack do
+		message 'Where [in the world](http://en.wikipedia.org/wiki/Carmen_Sandiego) is Carmen Sandiego?'
+		unfurl
+		# or
+		unfurl true
+	end
+
+end
+```
+
+#### Attachments
+
+You can send attachments over Slack as well. Attachments have a lot of options, so you have to pass in a pretty heavy configuration block. If you're going to use attachments, it's worth reading the slack-notifier [paramters docs](https://github.com/stevenosloan/slack-notifier#additional-parameters) and the Slack [Attachments Reference](https://api.slack.com/docs/attachments).
+
+```
+job do
+
+  slack do
+
+    first_attachment = {
+      fallback: 'This is the fallback',
+      pretext: 'Hey check out this attachment',
+      color: '#b0b0b0',
+      fields: [
+        {
+          title: 'Field Title',
+          value: 'This is the value of the first field!',
+          short: false
+        }
+      ]
+    }
 
-``` ruby
-gem 'pushpop'
-gem 'pushpop-<plugin>'
+    message 'Hello, World!'
+    attachment first_attachment
+  end
+end
 ```
 
 ### Contributing
 
-Code and documentation issues and pull requests are welcome. Help us make this template as
-useful as possible!
+Code and documentation issues and pull requests are welcome.

data/lib/pushpop-slack/version.rb

@@ -1,5 +1,5 @@
 module Pushpop
   class Slack
-    VERSION = '0.1.1'
+    VERSION = '0.2.0'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pushpop-slack
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Joe Wegner