README.rdoc in mandrill-rails-0.0.3 vs README.rdoc in mandrill-rails-0.0.4

- old
+ new

@@ -1,22 +1,24 @@ = Mandrill::Rails {<img src="https://secure.travis-ci.org/evendis/mandrill-rails.png" />}[http://travis-ci.org/evendis/mandrill-rails] -Mandrill::Rails extends the capabilities of the -{Mandrill}[https://github.com/tatemae-consultancy/mandrill] gem to provide tighter integration for Rails projects. - The primary goal of Mandrill::Rails is to make supporting Mandrill web hooks as easy and Rails-native as possible. As other opportunities for better Rails integration of the Mandrill API are discovered, these may be rolled in too. +Mandrill::Rails currently does not need or require any direct Mandrill API integration (such as provided by +various {Mandrill}[https://rubygems.org/search?utf8=%E2%9C%93&query=mandrill] +and {MailChimp}[https://rubygems.org/search?utf8=%E2%9C%93&query=mailchimp] gems). +If you need direct API integration in addition to Mandrill::Rails features, you can choose to add whichever best meets your needs. + FYI, {Mandrill}[http://mandrill.com/] is the transactional email service by the same folks who do MailChimp. == Requirements and Known Limitations -* Tested with MRI 1.8.7, 1.9.2, 1.9.3, Rubinius (1.8 and 1.9 mode), JRuby (1.8 and 1.9 mode) -* Requires Rails >= 3.0.3 (including 3.1 and 3.2) -* Includes {Mandrill}[https://github.com/tatemae-consultancy/mandrill] ~> 0.0.2 as a dependency +* Tested with MRI 1.8.7, 1.9.2, 1.9.3, Rubinius (1.9 mode), JRuby (1.8 and 1.9 mode). +* Rubinius 1.8 mode build temporarily removed since travis is having intermittent problems with this config. +* Requires Rails >= 3.0.3 (including 3.1 and 3.2). Food for thought (upcoming features maybe).. -* some generators may be handy to avoid the manual coding to hook up web hooks +* some generators may be handy to avoid the manual coding to wire up web hooks * I thought about implementing this as an engine, but the overhead did not seem appropriate. Maybe that view will change.. == The Mandrill::Rails Cookbook === How do I install it for normal use? @@ -33,12 +35,15 @@ $ gem install mandrill-rails === How do I install it for gem development? -If you want to work on enhancements of fix bugs in Mandrill::Rails, fork and clone the github repository. If you are using bundler (recommended), run <tt>bundle</tt> to install development dependencies. +If you want to work on enhancements or fix bugs in Mandrill::Rails, fork and clone the github repository. If you are using bundler (recommended), run <tt>bundle</tt> to install development dependencies. +Run tests using <tt>rake</tt> or <tt>rake spec</tt>, and note that guard is also included with the development dependencies so +you can kick-off continuous testing of changed files by running <tt>bundle exec guard</tt>. + See the section below on 'Contributing to Mandrill::Rails' for more information. === How do I configure my app for incoming Mandrill WebHooks? Say we have configured Mandrill to send requests to /inbox at our site (see the next recipes for how you do that). @@ -69,24 +74,24 @@ See {Mandrill WebHooks}[https://mandrillapp.com/settings/webhooks] * select the events you want to trigger on * set the "Post to URL" to point to your controller e.g. http://mydomain.com/inbox -=== How do I handle a specific Mandrill event payload in my app? +=== How do I handle specific Mandrill event payloads in my app? Once we have configured Mandrill and setup our routes and controllers, our app will successfully receive WebHook event notifications from Mandrill. But we are not doing anything with the payload yet. To handle specific Mandrill event payloads, we just need to implement a handler for each event type we are interested in. The list of available event types includes: inbound, send, hard_bounce, soft_bounce, open, click, spam, unsub, and reject. -In our controller, we simply write a method called `handle_<event-type>` and it will be called +In our controller, we simply write a method called <tt>handle_<event-type></tt> and it will be called for each event payload received. The event payload will be passed to this method -as an Mandrill::WebHook::EventDecorator - basically a Hash with some additional methods to +as a Mandrill::WebHook::EventDecorator - basically a Hash with some additional methods to help extract payload-specific elements. For example, to handle inbound email: class InboxController < ApplicationController @@ -107,11 +112,11 @@ And if you don't care to handle a specific payload type - then just don't implement the associated handler. === How do I pull apart the event_payload? -The `event_payload` object passed to our handler represents a single event and is packaged +The <tt>event_payload</tt> object passed to our handler represents a single event and is packaged as an Mandrill::WebHook::EventDecorator - basically a Hash with some additional methods to help extract payload-specific elements. You can use it as a Hash (with String keys) to access all of the native elements of the specific event, for example: @@ -125,14 +130,14 @@ If you would like examples of the actual data structures sent by Mandrill for different event types, some are included in the project source under spec/fixtures/webhook_examples. === What additional methods does event_payload provide to help extract payload-specific elements? -In addition to prividing full Hash-like access to the raw message, the `event_payload` object +In addition to prividing full Hash-like access to the raw message, the <tt>event_payload</tt> object (a Mandrill::WebHook::EventDecorator) provides a range of helper methods for some of the more obvious things you might need to do with the payload. Here are some examples (see -{Mandrill::WebHook::EventDecorator class documentation}[http://rubydoc.info/gems/mandrill-rails/0.0.2/Mandrill/WebHook/EventDecorator] +{Mandrill::WebHook::EventDecorator class documentation}[http://rubydoc.info/gems/mandrill-rails/Mandrill/WebHook/EventDecorator] for full details) event_payload.message_id # Returns the message_id. # Inbound events: references 'Message-Id' header. @@ -158,18 +163,18 @@ # Applicable events: inbound === How to extend Mandrill::WebHook::EventDecorator for application-specific payload handling? -It's quite likely you may benefit from adding more application-specific intelligence to the -`event_payload` object. +It's likely you may benefit from adding more application-specific intelligence to the +<tt>event_payload</tt> object. There are many ways to do this, but it is quite legitimate to reopen the EventDecorator class and add your own methods if you wish. -For example `event_payload.user_email` returns the subject user email address, but perhaps I will commonly want to -match that with a user record in my system. Or I similarly want to resolve `event_payload.recipient_emails` to user records. +For example <tt>event_payload.user_email</tt> returns the subject user email address, but perhaps I will commonly want to +match that with a user record in my system. Or I similarly want to resolve <tt>event_payload.recipient_emails</tt> to user records. In this case, I could extend EventDecorator in my app like this: # Extends Mandrill::WebHook::EventDecorator with app-specific event payload transformation class Mandrill::WebHook::EventDecorator @@ -185,11 +190,11 @@ end === How do I extract attachments from an inbound email? -The EventDecorator class provides an `attachments` method to access an array of attachments (if any). +The EventDecorator class provides an <tt>attachments</tt> method to access an array of attachments (if any). Each attachment is encapsulated in a class that describes the name, mime type, raw and decoded content. For example: def handle_inbound(event_payload) @@ -209,23 +214,26 @@ # e.g. '%PDF-1.3\n%\xC4\xE5 ... (etc)' end end -=== How do I use Mandrill gem features with Mandrill::Rails? +=== How do I use Mandrill API features with Mandrill::Rails? -{Mandrill}[https://github.com/tatemae-consultancy/mandrill] is included with Mandrill::Rails -and its behaviour is unchanged. You can use all the features of the Mandrill gem as normal. +Mandrill::Rails currently does not need or require any direct Mandrill API integration (such as provided by +various {Mandrill}[https://rubygems.org/search?utf8=%E2%9C%93&query=mandrill] +and {MailChimp}[https://rubygems.org/search?utf8=%E2%9C%93&query=mailchimp] gems). +If you need direct API integration in addition to Mandrill::Rails features, +you can choose to add whichever best meets your needs and use as normal. == Contributing to Mandrill::Rails * Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet * Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it * Fork the project * Start a feature/bugfix branch * Commit and push until you are happy with your contribution * Make sure to add tests for it. This is important so I don't break it in a future version unintentionally. -* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it. +* Please try not to mess with the gemspec, Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it. == Copyright Copyright (c) 2012 Paul Gallagher. See LICENSE for further details.