## MailForm
[![Build Status](https://secure.travis-ci.org/plataformatec/mail_form.png)](http://travis-ci.org/plataformatec/mail_form)

### Rails 3

This gem was built on top of `ActiveModel` to showcase how you can pull in validations, naming
and `i18n` from Rails to your models without the need to implement it all by yourself.

In other words, this README refers to the **MailForm** gem to be used in Rails 3. For instructions
on how to use MailForm in Rails 2.x, please check the v1.0 branch:

http://github.com/plataformatec/mail_form/tree/v1.0

### Description

**MailForm** allows you to send an e-mail straight from a form. For instance,
if you want to make a contact form just the following lines are needed (including the e-mail):

```ruby
class ContactForm < MailForm::Base
  attribute :name,      :validate => true
  attribute :email,     :validate => /\A([\w\.%\+\-]+)@([\w\-]+\.)+([\w]{2,})\z/i
  attribute :file,      :attachment => true

  attribute :message
  attribute :nickname,  :captcha  => true

  # Declare the e-mail headers. It accepts anything the mail method
  # in ActionMailer accepts.
  def headers
    {
      :subject => "My Contact Form",
      :to => "your.email@your.domain.com",
      :from => %("#{name}" <#{email}>)
    }
  end
end
```

Then you start a console with `rails console` and type:

```ruby
>> c = ContactForm.new(:name => 'José', :email => 'jose@email.com', :message => 'Cool!')
>> c.deliver
```

Check your inbox and the e-mail will be there, with the sent fields (assuming that
you configured your mailer delivery method properly).

### MailForm::Base

When you inherit from `MailForm::Base`, it pulls down a set of stuff from `ActiveModel`,
as `ActiveModel::Validation`, `ActiveModel::Translation` and `ActiveModel::Naming`.

This bring `I18n`, error messages, validations and attributes handling like in
`ActiveRecord` to **MailForm**, so **MailForm** can be used in your controllers and form builders without extra tweaks. This also means that instead of the following:

```ruby
attribute :email, :validate => /\A([\w\.%\+\-]+)@([\w\-]+\.)+([\w]{2,})\z/i
```

You could actually do this:

```ruby
attribute :email
validates_format_of :email, :with => /\A([\w\.%\+\-]+)@([\w\-]+\.)+([\w]{2,})\z/i
```

Choose the one which pleases you the most. For more information on the API, please
continue reading below.

### Playing together ORMs

**MailForm** plays nice with ORMs as well. You just need to include `MailForm::Delivery`
in your model and declare which attributes should be sent:

```ruby
class User < ActiveRecord::Base
  include MailForm::Delivery

  append :remote_ip, :user_agent, :session
  attributes :name, :email, :created_at

  def headers
    {
      :to => "your.email@your.domain.com",
      :subject => "User created an account"
    }
  end
end
```

The delivery will be triggered in an `after_create` hook.

## Installation

Install **MailForm** is very easy. Just edit your Gemfile adding the following:

```ruby
gem 'mail_form'
```
Then run `bundle install` to install **MailForm**.

If you want it as plugin, just do:

`script/plugin install git://github.com/plataformatec/mail_form.git`

## API Overview

### attributes(*attributes)

Declare your form attributes. All attributes declared here will be appended
to the e-mail, except the ones :captcha is true.

Options:

* :validate - A hook to validates_*_of. When true is given, validates the
  presence of the attribute. When a regexp, validates format. When array,
  validates the inclusion of the attribute in the array.

  Whenever :validate is given, the presence is automatically checked. Give
  :allow_blank => true to override.

  Finally, when :validate is a symbol, the method given as symbol will be
  called. Then you can add validations as you do in ActiveRecord (errors.add).

* :attachment - When given, expects a file to be sent and attaches
  it to the e-mail. Don't forget to set your form to multitype.

* :captcha - When true, validates the attributes must be blank.
  This is a simple way to avoid spam and the input should be hidden with CSS.

Examples:

```ruby
class ContactForm < MailForm::Base
  attributes :name,  :validate => true
  attributes :email, :validate => /\A([\w\.%\+\-]+)@([\w\-]+\.)+([\w]{2,})\z/i
  attributes :type,  :validate => ["General", "Interface bug"]
  attributes :message
  attributes :screenshot, :attachment => true, :validate => :interface_bug?
  attributes :nickname,   :captcha => true

  def interface_bug?
    if type == 'Interface bug' && screenshot.nil?
      self.errors.add(:screenshot, "can't be blank on interface bugs")
    end
  end
end

c = ContactForm.new(:nickname => 'not_blank', :email => 'your@email.com', :name => 'José')
c.valid?  #=> true
c.spam?   #=> true  (raises an error in development, to remember you to hide it)
c.deliver  #=> false (just delivers if is not a spam and is valid, raises an error in development)

c = ContactForm.new(:email => 'invalid')
c.valid?               #=> false
c.errors.inspect       #=> { :name => :blank, :email => :invalid }
c.errors.full_messages #=> [ "Name can't be blank", "Email is invalid" ]

c = ContactForm.new(:name => 'José', :email => 'your@email.com')
c.deliver
```

### append(*methods)

**MailForm** also makes easy to append request information from client to the sent
mail. You just have to do:

```ruby
class ContactForm < MailForm::Base
  append :remote_ip, :user_agent, :session
  # ...
end
```

And in your controller:

```ruby
@contact_form = ContactForm.new(params[:contact_form])
@contact_form.request = request
```

The remote ip, user agent and session will be sent in the e-mail in a
request information session. You can give to append any method that the
request object responds to.

## I18n

I18n in **MailForm** works like in ActiveRecord, so all models, attributes and messages
can be used with localized. Below is an I18n file example file:

```ruby
mail_form:
  models:
    contact_form: "Your site contact form"
  attributes:
    contact_form:
      email: "E-mail"
      telephone: "Telephone number"
      message: "Sent message"
  request:
    title: "Technical information about the user"
    remote_ip: "IP Address"
    user_agent: "Browser"
```

## Custom e-mail template

To customize the e-mail template that is used create a file called contact.erb in app/views/mail_form.
Take a look at lib/mail_form/views/mail_form/contact.erb in this repo to see how the default template works.

## Maintainers

* José Valim - http://github.com/josevalim
* Carlos Antonio - http://github.com/carlosantoniodasilva

## Contributors

* Andrew Timberlake - http://github.com/andrewtimberlake

## Bugs and Feedback

If you discover any bug, please use github issues tracker.

Copyright (c) 2009-2012 Plataformatec http://plataformatec.com.br/