How To Use The Mailer Extension

The Mailer Extension has some documentation: the README, the topics on the mailing list, and this wiki are the ones available.

Installation

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

 cd vendor/extensions
 sudo svn co http://svn.radiantcms.org/radiant/tags/rel_0-6-4/extensions/mailer/

This example checks out a copy of the REL-0.6.4 tag from the repository. Other installation techniques are possible. See Extensions for further information on installing extensions.

(The rake db:migrate:extensions command is not necessary for the Mailer extension because it doesn’t have anything to add to the database. Note from current page editor – I’m not sure this parenthetical statement is true; each extension does get registered in the extension_meta table.)

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

Configuration

The Mailer Extension is built upon the 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 environments.

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 “ActionMailer::Base Configuration Options”!http://api.rubyonrails.org/classes/ActionMailer/Base.html.

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.

Using Mailer

1. Create a new page;
2. On the page created, select “Mailer” from the page type dropdown list;
3. Create three new page parts “config”, “body”, and “email” (you may use “email_html” instead, in order to send html e-mails).

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 actually 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!

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:

 <r:mailer:form name="contact">
     Name:<br />
     <r:mailer:text name="name" /><br />
     E-mail:<br />
     <r:mailer:text name="email" /><br />
     Subject:<br />
     <r:mailer:text name="subject" /><br />
     Message:<br />
     <r:mailer:textarea name="body" /><br />
    <r:mailer:submit value="Send" />
 </r:mailer:form>

As you can see, there is a subject field. The text entered on this field will replace the one on the config part. Many variations are possible; most of the normal input tag attributes can be included in the mailer tags.

The tags available for building the form are listed on the Mailer Extension README.

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: <r:mailer:get name="name"/>
 E-mail: <r:mailer:get name="email"/>
 Subject: <r:mailer:get name="subject"/>
 Message: <r:mailer:get name="body"/>

The <r:mailer:get name="fieldname" /> is used to get the values entered by the user on the Mailer form.