Helper support for ActionMailer

git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@1446 5ecf4fe2-1ee6-0310-87b1-e25e094e27de

9 files changed, 260 insertions, 3 deletions

diff --git a/actionmailer/lib/action_mailer.rb b/actionmailer/lib/action_mailer.rb
index bc0a7a6ec4..9b9b514dad 100755
--- a/actionmailer/lib/action_mailer.rb
+++ b/actionmailer/lib/action_mailer.rb
@@ -35,13 +35,18 @@ end
 $:.unshift(File.dirname(__FILE__) + "/action_mailer/vendor/")
 
 require 'action_mailer/base'
+require 'action_mailer/helpers'
 require 'action_mailer/mail_helper'
 require 'action_mailer/quoting'
 require 'action_mailer/vendor/tmail'
 require 'net/smtp'
 
-ActionView::Base.class_eval { include MailHelper }
-ActionMailer::Base.class_eval { include ActionMailer::Quoting }
+ActionMailer::Base.class_eval do
+  include ActionMailer::Quoting
+  include ActionMailer::Helpers
+
+  helper MailHelper
+end
 
 old_verbose, $VERBOSE = $VERBOSE, nil
 TMail::Encoder.const_set("MAX_LINE_LEN", 200)
diff --git a/actionmailer/lib/action_mailer/base.rb b/actionmailer/lib/action_mailer/base.rb
index 4a935de5d6..20911513d0 100644
--- a/actionmailer/lib/action_mailer/base.rb
+++ b/actionmailer/lib/action_mailer/base.rb
@@ -240,13 +240,17 @@ module ActionMailer #:nodoc:
 
     private
       def render_message(method_name, body)
-        ActionView::Base.new(template_path, body).render_file(method_name)
+        initialize_template_class(body).render_file(method_name)
       end
         
       def template_path
         template_root + "/" + Inflector.underscore(self.class.name)
       end
 
+      def initialize_template_class(assigns)
+        ActionView::Base.new(template_path, assigns, self)
+      end
+
       def create_mail
         m = TMail::Mail.new
 
@@ -305,6 +309,8 @@ module ActionMailer #:nodoc:
         case method_symbol.id2name
           when /^create_([_a-z]\w*)/  then new($1, *parameters).mail
           when /^deliver_([_a-z]\w*)/ then new($1, *parameters).deliver!
+          when "new" then nil
+          else super
         end
       end
 
diff --git a/actionmailer/lib/action_mailer/helpers.rb b/actionmailer/lib/action_mailer/helpers.rb
new file mode 100644
index 0000000000..c0e02edfb1
--- /dev/null
+++ b/actionmailer/lib/action_mailer/helpers.rb
@@ -0,0 +1,136 @@
+module ActionMailer #:nodoc:
+  module Helpers #:nodoc:
+    def self.append_features(base)
+      super
+
+      # Initialize the base module to aggregate its helpers.
+      base.class_inheritable_accessor :master_helper_module
+      base.master_helper_module = Module.new
+
+      # Extend base with class methods to declare helpers.
+      base.extend(ClassMethods)
+
+      base.class_eval do
+        # Wrap inherited to create a new master helper module for subclasses.
+        class << self
+          alias_method :inherited_without_helper, :inherited
+          alias_method :inherited, :inherited_with_helper
+        end
+
+        # Wrap initialize_template_class to extend new template class
+        # instances with the master helper module.
+        alias_method :initialize_template_class_without_helper, :initialize_template_class
+        alias_method :initialize_template_class, :initialize_template_class_with_helper
+      end
+    end
+
+    # The template helpers serves to relieve the templates from including the same inline code again and again. It's a
+    # set of standardized methods for working with forms (FormHelper), dates (DateHelper), texts (TextHelper), and 
+    # Active Records (ActiveRecordHelper) that's available to all templates by default.
+    #
+    # It's also really easy to make your own helpers and it's much encouraged to keep the template files free
+    # from complicated logic. It's even encouraged to bundle common compositions of methods from other helpers 
+    # (often the common helpers) as they're used by the specific application.
+    # 
+    #   module MyHelper
+    #     def hello_world() "hello world" end
+    #   end
+    # 
+    # MyHelper can now be included in a controller, like this:
+    # 
+    #   class MyController < ActionController::Base
+    #     helper :my_helper
+    #   end
+    # 
+    # ...and, same as above, used in any template rendered from MyController, like this:
+    # 
+    # Let's hear what the helper has to say: <tt><%= hello_world %></tt>
+    module ClassMethods
+      # Makes all the (instance) methods in the helper module available to templates rendered through this controller.
+      # See ActionView::Helpers (link:classes/ActionView/Helpers.html) for more about making your own helper modules 
+      # available to the templates.
+      def add_template_helper(helper_module) #:nodoc:
+        master_helper_module.module_eval "include #{helper_module}"
+      end
+
+      # Declare a helper:
+      #   helper :foo
+      # requires 'foo_helper' and includes FooHelper in the template class.
+      #   helper FooHelper
+      # includes FooHelper in the template class.
+      #   helper { def foo() "#{bar} is the very best" end }
+      # evaluates the block in the template class, adding method #foo.
+      #   helper(:three, BlindHelper) { def mice() 'mice' end }
+      # does all three.
+      def helper(*args, &block)
+        args.flatten.each do |arg|
+          case arg
+            when Module
+              add_template_helper(arg)
+            when String, Symbol
+              file_name  = arg.to_s.underscore + '_helper'
+              class_name = file_name.camelize
+                
+              begin
+                require_dependency(file_name)
+              rescue LoadError => load_error
+                requiree = / -- (.*?)(\.rb)?$/.match(load_error).to_a[1]
+                msg = (requiree == file_name) ? "Missing helper file helpers/#{file_name}.rb" : "Can't load file: #{requiree}"
+                raise LoadError.new(msg).copy_blame!(load_error)
+              end
+
+              add_template_helper(class_name.constantize)
+            else
+              raise ArgumentError, 'helper expects String, Symbol, or Module argument'
+          end
+        end
+
+        # Evaluate block in template class if given.
+        master_helper_module.module_eval(&block) if block_given?
+      end
+
+      # Declare a controller method as a helper.  For example,
+      #   helper_method :link_to
+      #   def link_to(name, options) ... end
+      # makes the link_to controller method available in the view.
+      def helper_method(*methods)
+        methods.flatten.each do |method|
+          master_helper_module.module_eval <<-end_eval
+            def #{method}(*args, &block)
+              controller.send(%(#{method}), *args, &block)
+            end
+          end_eval
+        end
+      end
+
+      # Declare a controller attribute as a helper.  For example,
+      #   helper_attr :name
+      #   attr_accessor :name
+      # makes the name and name= controller methods available in the view.
+      # The is a convenience wrapper for helper_method.
+      def helper_attr(*attrs)
+        attrs.flatten.each { |attr| helper_method(attr, "#{attr}=") }
+      end
+
+      private 
+        def inherited_with_helper(child)
+          inherited_without_helper(child)
+          begin
+            child.master_helper_module = Module.new
+            child.master_helper_module.send :include, master_helper_module
+            child.helper child.name.underscore
+          rescue MissingSourceFile => e
+            raise unless e.is_missing?("helpers/#{child.name.underscore}_helper")
+          end
+        end        
+    end
+
+    private
+      # Extend the template class instance with our controller's helper module.
+      def initialize_template_class_with_helper(assigns)
+        returning(template = initialize_template_class_without_helper(assigns)) do
+          template.extend self.class.master_helper_module
+        end
+      end
+  end
+end
diff --git a/actionmailer/test/fixtures/helper_mailer/use_helper.rhtml b/actionmailer/test/fixtures/helper_mailer/use_helper.rhtml
new file mode 100644
index 0000000000..378777f8bb
--- /dev/null
+++ b/actionmailer/test/fixtures/helper_mailer/use_helper.rhtml
@@ -0,0 +1 @@
+Hello, <%= person_name %>. Thanks for registering!
diff --git a/actionmailer/test/fixtures/helper_mailer/use_helper_method.rhtml b/actionmailer/test/fixtures/helper_mailer/use_helper_method.rhtml
new file mode 100644
index 0000000000..d5b8b285e7
--- /dev/null
+++ b/actionmailer/test/fixtures/helper_mailer/use_helper_method.rhtml
@@ -0,0 +1 @@
+This message brought to you by <%= name_of_the_mailer_class %>.
diff --git a/actionmailer/test/fixtures/helper_mailer/use_mail_helper.rhtml b/actionmailer/test/fixtures/helper_mailer/use_mail_helper.rhtml
new file mode 100644
index 0000000000..96ec49d18a
--- /dev/null
+++ b/actionmailer/test/fixtures/helper_mailer/use_mail_helper.rhtml
@@ -0,0 +1,5 @@
+From "Romeo and Juliet":
+
+<%= block_format @text %>
+
+Good ol' Shakespeare.
diff --git a/actionmailer/test/fixtures/helper_mailer/use_test_helper.rhtml b/actionmailer/test/fixtures/helper_mailer/use_test_helper.rhtml
new file mode 100644
index 0000000000..52ea9aa413
--- /dev/null
+++ b/actionmailer/test/fixtures/helper_mailer/use_test_helper.rhtml
@@ -0,0 +1 @@
+So, <%= test_format(@text) %>
diff --git a/actionmailer/test/fixtures/helpers/test_helper.rb b/actionmailer/test/fixtures/helpers/test_helper.rb
new file mode 100644
index 0000000000..f479820c96
--- /dev/null
+++ b/actionmailer/test/fixtures/helpers/test_helper.rb
@@ -0,0 +1,5 @@
+module TestHelper
+  def test_format(text)
+    "<em><strong><small>#{text}</small></strong></em>"
+  end
+end
diff --git a/actionmailer/test/mail_helper_test.rb b/actionmailer/test/mail_helper_test.rb
new file mode 100644
index 0000000000..bf5bf7f3ac
--- /dev/null
+++ b/actionmailer/test/mail_helper_test.rb
@@ -0,0 +1,97 @@
+$:.unshift(File.dirname(__FILE__) + "/../lib/")
+$:.unshift File.dirname(__FILE__) + "/fixtures/helpers"
+
+require 'test/unit'
+require 'action_mailer'
+
+module MailerHelper
+  def person_name
+    "Mr. Joe Person"
+  end
+end
+
+class HelperMailer < ActionMailer::Base
+  helper MailerHelper
+  helper :test
+
+  def use_helper(recipient)
+    recipients recipient
+    subject    "using helpers"
+    from       "tester@example.com"
+  end
+
+  def use_test_helper(recipient)
+    recipients recipient
+    subject    "using helpers"
+    from       "tester@example.com"
+    self.body = { :text => "emphasize me!" }
+  end
+
+  def use_mail_helper(recipient)
+    recipients recipient
+    subject    "using mailing helpers"
+    from       "tester@example.com"
+    self.body = { :text => 
+      "But soft! What light through yonder window breaks? It is the east, " +
+      "and Juliet is the sun. Arise, fair sun, and kill the envious moon, " +
+      "which is sick and pale with grief that thou, her maid, art far more " +
+      "fair than she. Be not her maid, for she is envious! Her vestal " +
+      "livery is but sick and green, and none but fools do wear it. Cast " +
+      "it off!"
+    }
+  end
+
+  def use_helper_method(recipient)
+    recipients recipient
+    subject    "using helpers"
+    from       "tester@example.com"
+    self.body = { :text => "emphasize me!" }
+  end
+
+  private
+
+    def name_of_the_mailer_class
+      self.class.name
+    end
+    helper_method :name_of_the_mailer_class
+end
+
+HelperMailer.template_root = File.dirname(__FILE__) + "/fixtures"
+
+class MailerHelperTest < Test::Unit::TestCase
+  def new_mail( charset="utf-8" )
+    mail = TMail::Mail.new
+    mail.set_content_type "text", "plain", { "charset" => charset } if charset
+    mail
+  end
+
+  def setup
+    ActionMailer::Base.delivery_method = :test
+    ActionMailer::Base.perform_deliveries = true
+    ActionMailer::Base.deliveries = []
+
+    @recipient = 'test@localhost'
+  end
+
+  def test_use_helper
+    mail = HelperMailer.create_use_helper(@recipient)
+    assert_match %r{Mr. Joe Person}, mail.encoded
+  end
+
+  def test_use_test_helper
+    mail = HelperMailer.create_use_test_helper(@recipient)
+    assert_match %r{<em><strong><small>emphasize me!}, mail.encoded
+  end
+
+  def test_use_helper_method
+    mail = HelperMailer.create_use_helper_method(@recipient)
+    assert_match %r{HelperMailer}, mail.encoded
+  end
+
+  def test_use_mail_helper
+    mail = HelperMailer.create_use_mail_helper(@recipient)
+    assert_match %r{  But soft!}, mail.encoded
+    assert_match %r{east, and\n  Juliet}, mail.encoded
+  end
+end
+