Add mailer previews feature based on mail_view gem

5 files changed, 101 insertions, 0 deletions

diff --git a/actionmailer/CHANGELOG.md b/actionmailer/CHANGELOG.md
index 857cde399a..fc9aefd416 100644
--- a/actionmailer/CHANGELOG.md
+++ b/actionmailer/CHANGELOG.md
@@ -1,3 +1,7 @@
+*   Add mailer previews feature based on 37 Signals mail_view gem
+
+    *Andrew White*
+
 *   Calling `mail()` without arguments serves as getter for the current mail
     message and keeps previously set headers.
 
diff --git a/actionmailer/lib/action_mailer.rb b/actionmailer/lib/action_mailer.rb
index 5b6960c8fc..557eec4728 100644
--- a/actionmailer/lib/action_mailer.rb
+++ b/actionmailer/lib/action_mailer.rb
@@ -41,6 +41,8 @@ module ActionMailer
   autoload :Base
   autoload :DeliveryMethods
   autoload :MailHelper
+  autoload :Preview
+  autoload :Previews, 'action_mailer/preview'
   autoload :TestCase
   autoload :TestHelper
 end
diff --git a/actionmailer/lib/action_mailer/base.rb b/actionmailer/lib/action_mailer/base.rb
index 5723b2cc1b..e1f3fd03e2 100644
--- a/actionmailer/lib/action_mailer/base.rb
+++ b/actionmailer/lib/action_mailer/base.rb
@@ -308,6 +308,25 @@ module ActionMailer
   # Note that unless you have a specific reason to do so, you should prefer using before_action
   # rather than after_action in your ActionMailer classes so that headers are parsed properly.
   #
+  # = Previewing emails
+  #
+  # You can preview your email templates visually by adding a mailer preview file to the
+  # <tt>ActionMailer::Base.preview_path</tt>. Since most emails do something interesting
+  # with database data, you'll need to write some scenarios to load messages with fake data:
+  #
+  #   class NotifierPreview < ActionMailer::Preview
+  #     def welcome
+  #       Notifier.welcome(User.first)
+  #     end
+  #   end
+  #
+  # Methods must return a Mail::Message object which can be generated by calling the mailer
+  # method without the additional <tt>deliver</tt>. The location of the mailer previews
+  # directory can be configured using the <tt>preview_path</tt> option which has a default
+  # of <tt>test/mailers/previews</tt>:
+  #
+  #     config.action_mailer.preview_path = "#{Rails.root}/lib/mailer_previews"
+  #
   # = Configuration options
   #
   # These options are specified on the class level, like
@@ -362,6 +381,7 @@ module ActionMailer
   #   <tt>delivery_method :test</tt>. Most useful for unit and functional testing.
   class Base < AbstractController::Base
     include DeliveryMethods
+    include Previews
 
     abstract!
 
diff --git a/actionmailer/lib/action_mailer/preview.rb b/actionmailer/lib/action_mailer/preview.rb
new file mode 100644
index 0000000000..43d9ec4bb5
--- /dev/null
+++ b/actionmailer/lib/action_mailer/preview.rb
@@ -0,0 +1,67 @@
+require 'active_support/descendants_tracker'
+
+module ActionMailer
+  module Previews #:nodoc:
+    extend ActiveSupport::Concern
+
+    included do
+      # Set the location of mailer previews through app configuration:
+      #
+      #     config.action_mailer.preview_path = "#{Rails.root}/lib/mailer_previews"
+      #
+      class_attribute :preview_path, instance_writer: false
+    end
+  end
+
+  class Preview
+    extend ActiveSupport::DescendantsTracker
+
+    class << self
+      # Returns all mailer preview classes
+      def all
+        load_previews if descendants.empty?
+        descendants
+      end
+
+      # Returns the mail object for the given email name
+      def call(email)
+        preview = self.new
+        preview.public_send(email)
+      end
+
+      # Returns all of the available email previews
+      def emails
+        public_instance_methods(false).map(&:to_s).sort
+      end
+
+      # Returns true if the email exists
+      def email_exists?(email)
+        emails.include?(email)
+      end
+
+      # Returns true if the preview exists
+      def exists?(preview)
+        all.any?{ |p| p.preview_name == preview }
+      end
+
+      # Find a mailer preview by its underscored class name
+      def find(preview)
+        all.find{ |p| p.preview_name == preview }
+      end
+
+      # Returns the underscored name of the mailer preview without the suffix
+      def preview_name
+        name.sub(/Preview$/, '').underscore
+      end
+
+      protected
+        def load_previews #:nodoc:
+          Dir["#{preview_path}/**/*_preview.rb"].each{ |file| require_dependency file }
+        end
+
+        def preview_path #:nodoc:
+          Base.preview_path
+        end
+    end
+  end
+end
diff --git a/actionmailer/lib/action_mailer/railtie.rb b/actionmailer/lib/action_mailer/railtie.rb
index 7677ff3a7c..af8009ba97 100644
--- a/actionmailer/lib/action_mailer/railtie.rb
+++ b/actionmailer/lib/action_mailer/railtie.rb
@@ -40,5 +40,13 @@ module ActionMailer
         config.compile_methods! if config.respond_to?(:compile_methods!)
       end
     end
+
+    initializer "action_mailer.configure_mailer_previews", before: :set_autoload_paths do |app|
+      if Rails.env.development?
+        options = app.config.action_mailer
+        options.preview_path ||= defined?(Rails.root) ? "#{Rails.root}/test/mailers/previews" : nil
+        app.config.autoload_paths << options.preview_path
+      end
+    end
   end
 end