README.md in pushpop-slack-0.1.1 vs README.md in pushpop-slack-0.2.0
- old
+ new
@@ -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.
-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:
+Here's a very basic example of sending a message to slack:
-``` shell
-$ gem build pushpop-<plugin>.gemspec
-$ gem push pushpop-<plugin>-0.1.0.gem
+```ruby
+job 'send "Hello, World!" to #general'
+
+ slack do
+ message 'Hello, World!'
+ end
+
+end
```
-Users will then be able to use your plugin by including it in their Gemfile:
+#### Links
-``` ruby
-gem 'pushpop'
-gem 'pushpop-<plugin>'
+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
+ }
+ ]
+ }
+
+ 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.
\ No newline at end of file