* Remove default_url_options from mailer generator

* Improve mailer documentation regarding generating URLs
* Add no_match to mailer generator to warn contributors about default_url_options
Signed-off-by: Joshua Peek <josh@joshpeek.com>

3 files changed, 30 insertions, 17 deletions

diff --git a/actionmailer/lib/action_mailer/base.rb b/actionmailer/lib/action_mailer/base.rb
index 8a4f34447c..3dfe828b06 100644
--- a/actionmailer/lib/action_mailer/base.rb
+++ b/actionmailer/lib/action_mailer/base.rb
@@ -73,21 +73,36 @@ module ActionMailer #:nodoc:
   #   <%= truncate(note.body, 25) %>
   # 
   #
-  # = Generating URLs for mailer views
+  # = Generating URLs
+  # 
+  # URLs can be generated in mailer views using <tt>url_for</tt> or named routes.
+  # Unlike controllers from Action Pack, the mailer instance doesn't have any context about the incoming request, 
+  # so you'll need to provide all of the details needed to generate a URL. 
   #
-  # If your view includes URLs from the application, you need to use url_for in the mailing method instead of the view.
-  # Unlike controllers from Action Pack, the mailer instance doesn't have any context about the incoming request. That's
-  # why you need to jump this little hoop and supply all the details needed for the URL. Example:
+  # When using <tt>url_for</tt> you'll need to provide the <tt>:host</tt>, <tt>:controller</tt>, and <tt>:action</tt>:
+  # 
+  #   <%= url_for(:host => "example.com", :controller => "welcome", :action => "greeting") %>
   #
-  #    def signup_notification(recipient)
-  #      recipients recipient.email_address_with_name
-  #      from       "system@example.com"
-  #      subject    "New account information"
-  #      body       :account => recipient,
-  #                 :home_page => url_for(:host => "example.com", :controller => "welcome", :action => "greeting")
-  #    end
+  # When using named routes you only need to supply the <tt>:host</tt>:
+  # 
+  #   <%= users_url(:host => "example.com") %>
+  #
+  # You will want to avoid using the <tt>name_of_route_path</tt> form of named routes because it doesn't make sense to
+  # generate relative URLs in email messages.
+  #
+  # It is also possible to set a default host that will be used in all mailers by setting the <tt>:host</tt> option in 
+  # the <tt>ActionMailer::Base.default_url_options</tt> hash as follows:
+  #
+  #   ActionMailer::Base.default_url_options[:host] = "example.com"
+  # 
+  # This can also be set as a configuration option in <tt>environment.rb</tt>:
+  #
+  #   config.action_mailer.default_url_options = { :host => "example.com" }
   #
-  # You can now access @home_page in the template and get http://example.com/welcome/greeting.
+  # If you do decide to set a default <tt>:host</tt> for your mailers you will want to use the
+  # <tt>:only_path => false</tt> option when using <tt>url_for</tt>. This will ensure that absolute URLs are generated because
+  # the <tt>url_for</tt> view helper will, by default, generate relative URLs when a <tt>:host</tt> option isn't 
+  # explicitly provided.
   #
   # = Sending mail
   #
diff --git a/railties/lib/rails_generator/generators/components/mailer/templates/mailer.rb b/railties/lib/rails_generator/generators/components/mailer/templates/mailer.rb
index 0c7e6bebaf..ce15ae9de9 100644
--- a/railties/lib/rails_generator/generators/components/mailer/templates/mailer.rb
+++ b/railties/lib/rails_generator/generators/components/mailer/templates/mailer.rb
@@ -1,7 +1,5 @@
 class <%= class_name %> < ActionMailer::Base
   
-  # change to your domain name
-  default_url_options[:host] = 'example.com'
 <% for action in actions -%>
 
   def <%= action %>(sent_at = Time.now)
diff --git a/railties/test/generators/rails_mailer_generator_test.rb b/railties/test/generators/rails_mailer_generator_test.rb
index 03170c3b61..de61e6736d 100644
--- a/railties/test/generators/rails_mailer_generator_test.rb
+++ b/railties/test/generators/rails_mailer_generator_test.rb
@@ -17,9 +17,9 @@ class RailsMailerGeneratorTest < GeneratorTestCase
           ],
           body.split("\n").map{|line| line.sub(' '*4, '') }
       end
-
-      assert_match /^  default_url_options\[:host\] = 'example.com'$/m, model,
-        'model should include default_url_options :host declaration'
+      
+      assert_no_match /(self.default_url_options =|default_url_options\[.*\] =)/, model,
+        'individual mailer models should not set default_url_options because the options are shared by all mailers'
     end
     
     assert_generated_views_for :notifier, 'reset_password.erb'