Skip to content

Latest commit

 

History

History
237 lines (157 loc) · 7.5 KB

README.rdoc

File metadata and controls

237 lines (157 loc) · 7.5 KB
Raw

MailForm ↑

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):

class ContactForm < MailForm::Resource
  subject "My Contact Form"
  recipients "your.email@your.domain.com"
  sender{|c| %{"#{c.name}" <#{c.email}>} }

  attribute :name,      :validate => true
  attribute :email,     :validate => /[^@]+@[^\.]+\.[\w\.\-]+/
  attribute :file,      :attachment => true

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

Then you start a script/console and type:

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

The delivery will be triggered in an after_create callback. So check your inbox and the e-mail will be there, with the sent fields (assuming that you configured your mailer delivery method properly).

MailForm::Resource ↑

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

This bring I18n, error message and attributes handling like in ActiveRecord to MailForm, so MailForm can be used in your controllers and form builders without extra tweaks.

Playing with other ORMs ↑

MailForm plays nice with other ORMs as well. You just need to include MailForm::Delivery in your model and an e-mail with the attributes will be sent:

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

  append :remote_ip, :user_agent, :session
  subject "New user created"
  recipients "your.email@your.domain.com"
end

Installation ↑

Install MailForm is very easy. It is stored in Gemcutter, so just run the following:

sudo gem install mail_form

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 - When true, validates the attributes can’t be blank. When a regexp is given, check if the attribute matches is not blank and then if it matches the regexp.

    Whenever :validate is a symbol, the method given as symbol will be called. You can then 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:

class ContactForm < MailForm::Resource
  attributes :name,  :validate => true
  attributes :email, :validate => /[^@]+@[^\.]+\.[\w\.\-]+/
  attributes :message
  attributes :screenshot, :attachment => true, :validate => :screenshot_required?
  attributes :nickname,   :captcha => true

  def screenshot_required?
    # ...
  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)

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 #=> true

subject(string_or_symbol_or_block) ↑

Declares the subject of the contact email. It can be a string or a proc or a symbol.

When a symbol is given, it will call a method on the form object with the same name as the symbol. As a proc, it receives a mail form instance. It defaults to the class human name.

subject "My Contact Form"
subject { |c| "Contacted by #{c.name}" }

sender(string_or_symbol_or_block) ↑

Declares contact email sender. It can be a string or a proc or a symbol.

When a symbol is given, it will call a method on the form object with the same name as the symbol. As a proc, it receives a mail form instance. By default is:

sender { |c| c.email }

This requires that your MailForm object have an email attribute.

recipients(string_or_array_or_symbol_or_block) ↑

Who will receive the e-mail. Can be a string or array or a symbol or a proc.

When a symbol is given, it will call a method on the form object with the same name as the symbol. As a proc, it receives a mail form instance.

Both the proc and the symbol must return a string or an array. By default is nil.

append(*methods) ↑

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

class ContactForm < MailForm::Resource
  append :remote_ip, :user_agent, :session
  # ...
end

And in your controller:

@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.

validations ↑

MailForm supports validations through the attribute method as seen above:

attribute :email, :validate => /[^@]+@[^\.]+\.[\w\.\-]+/

But this is actually a DSL to ActiveModel validations, so you could actually do this:

attribute :email
validates_format_of :email, :with => /[^@]+@[^\.]+\.[\w\.\-]+/

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

template(string_or_symbol_or_proc) ↑

Allow you to set the template that is going to rendered. This allows you to have several MailForm instances, using different templates.

headers(hash) ↑

Configure additional headers to your e-mail.

MailForm.template_root ↑

MailForm by default is configured to use the template which comes with the gem. If you want to use another, you just need to configure MailForm template root to point to your application:

MailForm.template_root = File.join(Rails.root, "app", "views")

I18n ↑

I18n in MailForm works like in ActiveRecord, so all models, attributes and messages can be used with localized. However, in order to DRY up your yml files, mail_form requires on I18n >= 0.2.0 since it uses the ability to symlink translations. Below is an I18n example file:

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

Maintainers ↑

Contributors ↑

Bugs and Feedback ↑

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

Copyright © 2009 Plataforma Tec blog.plataformatec.com.br/