Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

Suggestions for README examples #30

Merged
merged 1 commit into from

2 participants

@nateberkopec

We use MailView extensively in our app, but our usage pattern is a little different than suggested by the README, and I thought it might be useful to pass along the way we use MailView.

First - the syntax as written in the current README gives me (in Ruby 1.9.3 and Rails 3.1) a warning on startup:

warning: toplevel constant MailPreview referenced by Notifier::MailPreview

Taking MailPreview out of an ActionMailer class entirely and putting it in its own file gives you two advantages:

  1. No more warnings that make you feel like you're a bad Rubyist and need to go take a shower
  2. It makes more sense if you start referring to other mailers (like I do in the README changes I've made)

Also, I've included how we use Structs in our MailViews to act like stub objects. It seems like the easiest way to do it if your mails are simple and not using a lot of attributes from the object, or you don't have existing DB fixtures you can pull from.

I also added Ruby syntax highlighting to the examples, just for some prettiness.

@packagethief

Thanks Nate. I wouldn't recommend creating the preview in an initializer, though. Feels like the wrong place. Stick it in lib or app/mailers (we use app/mailers).

If you can remove that suggestion, as well as the defined?(MailView) check, I'll happily merge.

I get that people might want to only load this in development mode, and thus check for the MailView constant, but I don't think's worth getting into in the README. Let's just show the simplest possible setup.

@nateberkopec

Cool!

I've updated as you asked and squashed my history, should be ready to merge.

@packagethief packagethief merged commit ee13d17 into from
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Nov 21, 2012
  1. @nateberkopec
This page is out of date. Refresh to see the latest.
Showing with 37 additions and 33 deletions.
  1. +37 −33 README.md
View
70 README.md
@@ -8,7 +8,9 @@ Install
Add the gem to your `Gemfile`:
- gem 'mail_view', :git => 'https://github.com/37signals/mail_view.git'
+```ruby
+ gem 'mail_view', :git => 'https://github.com/37signals/mail_view.git'
+```
And run `bundle install`.
@@ -17,34 +19,32 @@ Usage
Since most emails do something interesting with database data, you'll need to write some scenarios to load messages with fake data. Its similar to writing mailer unit tests but you see a visual representation of the output instead.
- class Notifier < ActionMailer::Base
- def invitation(inviter, invitee)
- # ...
- end
-
- def welcome(user)
- # ...
- end
-
- class Preview < MailView
- # Pull data from existing fixtures
- def invitation
- account = Account.first
- inviter, invitee = account.users[0, 2]
- Notifier.invitation(inviter, invitee)
- # ::Notifier.invitation(inviter, invitee) # May need to call with '::'
- end
-
- # Factory-like pattern
- def welcome
- user = User.create!
- mail = Notifier.welcome(user)
- user.destroy
- mail
- end
- end
+```ruby
+ # app/mailers/mail_preview.rb or lib/mail_preview.rb
+ class MailPreview < MailView
+ # Pull data from existing fixtures
+ def invitation
+ account = Account.first
+ inviter, invitee = account.users[0, 2]
+ Notifier.invitation(inviter, invitee)
end
+ # Factory-like pattern
+ def welcome
+ user = User.create!
+ mail = Notifier.welcome(user)
+ user.destroy
+ mail
+ end
+
+ # Stub-like
+ def forgot_password
+ user = Struct.new(:email, :name).new('name@example.com', 'Jill Smith')
+ mail = UserMailer.forgot_password(user)
+ end
+ end
+```
+
Methods must return a [Mail][1] or [TMail][2] object. Using ActionMailer, call `Notifier.create_action_name(args)` to return a compatible TMail object. Now on ActionMailer 3.x, `Notifier.action_name(args)` will return a Mail object.
Routing
@@ -52,15 +52,19 @@ Routing
A mini router middleware is bundled for Rails 2.x support.
- # config/environments/development.rb
- config.middleware.use MailView::Mapper, [Notifier::Preview]
+```ruby
+ # config/environments/development.rb
+ config.middleware.use MailView::Mapper, [MailPreview]
+```
For Rails³ you can map the app inline in your routes config.
- # config/routes.rb
- if Rails.env.development?
- mount Notifier::Preview => 'mail_view'
- end
+```ruby
+ # config/routes.rb
+ if Rails.env.development?
+ mount MailPreview => 'mail_view'
+ end
+```
Now just load up `http://localhost:3000/mail_view`.
Something went wrong with that request. Please try again.