Comparing version 3 and version 2

h1. Using Mailer Extension

The Mailer Extension is responsible for an enormous amount of traffic on the Radiant mailing list. People ask questions from installation to usage,  
from not being able to configure it properly to not being able to send e-mails.

The source of all evil is the lack of documentation of the Mailer Extension, being the README and the topics on the mailing list the only ones available.  
But, searching the mailing list and reading all the topics related to the Mailer Extension to find the answers you want can be very tiresome  
(believe me, I've done this). So, I thought I could help the community and put together the most common information about the Mailer Extension.

h2. Installation

The way to get the Mailer Extension is by subversion. So, from the Radiant root directory do as follow:follows:

 cd vendor/extensions
 sudo svn co http://dev.radiantcms.org/svn/radiant/branches/mental/extensions/mailer


(The 
rake db:migrate:extensions
 command is not necessary for the Mailer extension because it doesn't have anything to add to the database.)

The Mailer Extension is installed, now it's time to make it work.

h2. Configuration

The Mailer Extension is built upon the [http://wiki.rubyonrails.org/rails/pages/ActionMailer ActionMailer framework], so we need to configure Radiant to use it. 

This can be done in the 
config/environment.rb
 file in the 
config/environments/
 directory. I prefer doing so in the 
config/environment.rb
 file, so  
I can use it from production, test or development environmets.

Edit the 
config/environmemt.rb
 and find the line that reads

 # Skip frameworks you're not going to use
 config.frameworks -= [ :action_web_service, :action_mailer ]  


remove 
:action_mailer
 from the list

 # Skip frameworks you're not going to use
 config.frameworks -= [ :action_web_service ]


now, add the following configuration parameters (I put it at the end of the file, just before the line that reads 
require "status"

 # Configure ActionMailer for Mailer extension
 ActionMailer::Base.smtp_settings = {
   :address => "your.smtp.server",
   :port => 25,
   :domain => "your.domain"
}


the code above is based on my own configuration. For a complete list of parameters have a look at the [http://api.rubyonrails.org/classes/ActionMailer/Base.html ActionMailer::Base Configuration Options].

That would be enough to make the Mailer Extension work, but after configuring the 
ActionMailer::Base
 as above, for some strange reason, it was still not sending e-mails. Everything was fine, the Mailer Extension was working, no errors, but no e-mails. So I thought I could figure out what was happening adding another line of configuration to the 
ActionMailer::Base
 on the 
config/environment.rb
 file

 ActionMailer::Base.raise_delivery_errors = true


After I put down this line, e-mails started to be sent (I really don't know why, any clue?), but as it has made the Mailer Extension work I'll keep it.

Now, restart your server and let's create our mailer form.

h2. Using Mailer

 # Create a new page;
 # On the page created, select "Mailer" from the page type dropdown list;
 # Create two new page parts "config" and "email" (you may use "email_html" instead, in order to send hml e-mails).

h3. The config page part

The config page part is where the Mailer configuration parameters are set, for example:

 mailers:
   contact:
     subject: my subject
     from: myemail@mydomain
     redirect_to: /where/you/want/visitors/to/go/after/sending/the/email
     recipients: 
       - recipient#1@domain
       - recipient#2@domain


On the second line, 
contact
 is actualy the name of your Mailer form (more to come), whatever you name your Mailer form, substitute 
contact
 by it. This is because you can have many Mailer forms on the same page, so the Mailer Extension needs to know which one you're talking about.

The next lines are self explanatory, I think :)

*Warning*: config is a YAML formated file, so *INDENTATION MATTERS*!

h3. The body page part

The boby page part is where we code our Mailer form. The example below is based on a test form I was doing:

 
     Name:

     

     E-mail:

     

     Subject:

     

     Message:

     

    
 


As you can see, there is a subject field. The text entered on this field will replace the one on the 
config
 part. I'll let other experimentations to you ;)

The tags available for building the form are listed on the Mailer Extension [http://dev.radiantcms.org/svn/radiant/branches/mental/extensions/mailer/README README].

h3. The email page part

The email page part is where we build our e-mail template. For example, based on the previous Mailer form, we could have an e-mail template like this:

 Name: 
 E-mail: 
 Subject: 
 Message: 


The 
 is used the get the values entered by the user on the Mailer form.

h2. The End

This is not an extensive tutorial about using the Mailer Extension, but I think it covers the basics. I hope this may help someone in anyway.

Back to Page