mail_form 1.0.0

data/CHANGELOG

@@ -0,0 +1,21 @@
+* Version 1.0
+
+* Rename to mail_form and launch Rails 2.3 branch.
+
+* Version 0.4
+
+* Added support to template
+
+# Version 0.3
+
+* Added support to symbols on :sender, :subject and :recipients
+* Added support to symbols on :validate
+
+# Version 0.2
+
+* Added support to request objects and append DSL
+* Added support to :attachments (thanks to @andrewtimberlake)
+
+# Version 0.1
+
+* First release

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Plataforma Tec http://blog.plataformatec.com.br/
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,186 @@
+== MailForm
+
+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
+    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.deliver
+
+Check your inbox and the e-mail will be there, with the sent fields (assuming
+that you configured your delivery method properly).
+
+MailForm also support attachments, I18n, error messages like in ActiveRecord 
+(so it works with custom FormBuilders) and can also send the user request information
+in the mail.
+
+It's tested and compatible with Rails 2.2.x and Rails 2.3.x.
+
+== Installation
+
+Install MailForm is very easy. It is stored in Gemcutter, so just run the following:
+
+   sudo gem install mail_form --version=1.0.0
+
+If you want it as plugin, just do:
+
+   script/plugin install git://github.com/plataformatec/mail_form.git
+
+== Request
+
+MailForm makes easy to append user information to the contact mail. You just
+have to do:
+
+  class ContactForm < MailForm
+    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.
+
+== 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
+     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')
+   # save is an alias to deliver
+   c.save #=> 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.
+
+==== 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)
+
+Additional headers to your e-mail.
+
+== I18n
+
+All models, attributes and messages in MailForm can be used with localized.
+Below is an I18n example file:
+
+  mail_form:
+    models:
+      contact_form: "Your site contact form"
+    attributes:
+      email: "E-mail"
+      telephone: "Telephone number"
+      message: "Sent message"
+    messages:
+      blank: "can not be blank"
+      invalid: "is not valid"
+      telephone: "must have eight digits"
+    request:
+      title: "Technical information about the user"
+      remote_ip: "IP Address"
+      user_agent: "Browser"
+
+== 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 Plataforma Tec http://blog.plataformatec.com.br/

data/Rakefile

@@ -0,0 +1,38 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+require File.join(File.dirname(__FILE__), "lib", "mail_form", "version")
+
+desc 'Run tests for MailForm.'
+Rake::TestTask.new(:test) do |t|
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Generate documentation for MailForm.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'MailForm'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('MIT-LICENSE')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |s|
+    s.name = "mail_form"
+    s.version = MailForm::VERSION
+    s.summary = "Send e-mail straight from forms in Rails with I18n, validations, attachments and request information."
+    s.email = "contact@plataformatec.com.br"
+    s.homepage = "http://github.com/plataformatec/mail_form"
+    s.description = "Send e-mail straight from forms in Rails with I18n, validations, attachments and request information."
+    s.authors = ['José Valim', 'Carlos Antônio']
+    s.files =  FileList["[A-Z]*", "{lib,views}/**/*"]
+  end
+
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler, or one of its dependencies, is not available. Install it with: sudo gem install jeweler"
+end

data/lib/mail_form.rb

@@ -0,0 +1,32 @@
+require 'mail_form/base'
+require 'mail_form/dsl'
+require 'mail_form/errors'
+require 'mail_form/notifier'
+
+class MailForm
+  extend MailForm::DSL
+
+  ACCESSORS = [ :form_attributes, :form_validatable, :form_subject,
+                :form_attachments, :form_recipients, :form_sender,
+                :form_captcha, :form_headers, :form_template, :form_appendable ]
+
+  DEFAULT_MESSAGES = { :blank => "can't be blank", :invalid => "is invalid" }
+
+  class_inheritable_reader *ACCESSORS
+  protected *ACCESSORS
+
+  # Initialize arrays and hashes
+  #
+  write_inheritable_array :form_captcha, []
+  write_inheritable_array :form_appendable, []
+  write_inheritable_array :form_attributes, []
+  write_inheritable_array :form_attachments, []
+  write_inheritable_hash  :form_validatable, {}
+
+  headers({})
+  sender {|c| c.email }
+  subject{|c| c.class.human_name }
+  template 'contact'
+end
+
+MailForm::Notifier.template_root = File.join(File.dirname(__FILE__), '..', 'views')

data/lib/mail_form/base.rb

@@ -0,0 +1,126 @@
+class MailForm
+  attr_accessor :request
+
+  # Initialize assigning the parameters given as hash (just as in ActiveRecord).
+  #
+  # It also accepts the request object as second parameter which must be sent
+  # whenever :append is called.
+  #
+  def initialize(params={}, request=nil)
+    @request = request
+    params.each_pair do |attr, value|
+      self.send(:"#{attr}=", value)
+    end unless params.blank?
+  end
+
+  # In development, raises an error if the captcha field is not blank. This is
+  # is good to remember that the field should be hidden with CSS and shown only
+  # to robots.
+  #
+  # In test and in production, it returns true if aall captcha field are blank,
+  # returns false otherwise.
+  #
+  def spam?
+    form_captcha.each do |field|
+      next if send(field).blank?
+
+      if RAILS_ENV == 'development'
+        raise ScriptError, "The captcha field #{field} was supposed to be blank"
+      else
+        return true
+      end
+    end
+
+    return false
+  end
+
+  def not_spam?
+    !spam?
+  end
+
+  # To check if the form is valid, we run the validations.
+  #
+  # If the validation is true, we just check if the field is not blank. If it's
+  # a regexp, we check if it is not blank AND if the Regexp matches.
+  #
+  # You can have totally custom validations by sending a symbol. Then the method
+  # given as symbol will be called and then you cann hook your validations there.
+  #
+  def valid?
+    return false unless errors.empty?
+
+    form_validatable.each_pair do |field, validation|
+      next unless validation
+
+      if validation.is_a?(Symbol)
+        send(validation)
+      elsif send(field).blank?
+        errors.add(field, :blank)
+      elsif validation.is_a?(Regexp)
+        errors.add(field, :invalid) unless send(field) =~ validation
+      end
+    end
+
+    errors.empty?
+  end
+
+  def invalid?
+    !valid?
+  end
+
+  # Always return true so when using form_for, the default method will be post.
+  #
+  def new_record?
+    true
+  end
+
+  # Always return nil so when using form_for, the default method will be post.
+  #
+  def id
+    nil
+  end
+
+  # If is not spam and the form is valid, we send the e-mail and returns true.
+  # Otherwise returns false.
+  #
+  def deliver(run_validations=true)
+    if !run_validations || (self.not_spam? && self.valid?)
+      MailForm::Notifier.deliver_contact(self)
+      return true
+    else
+      return false
+    end
+  end
+  alias :save :deliver
+
+  # Add a human attribute name interface on top of I18n. If email is received as
+  # attribute, it will look for a translated name on:
+  #
+  #   mail_form:
+  #     attributes:
+  #       email: E-mail
+  #
+  def self.human_attribute_name(attribute, options={})
+    I18n.translate("attributes.#{attribute}", options.merge(:default => attribute.to_s.humanize, :scope => [:mail_form]))
+  end
+
+  # Add a human name interface on top of I18n. If you have a model named
+  # MailForm, it will search for the localized name on:
+  #
+  #   mail_form:
+  #     models:
+  #       contact_form: Contact form
+  #
+  def self.human_name(options={})
+    underscored = self.name.demodulize.underscore
+    I18n.translate("models.#{underscored}", options.merge(:default => underscored.humanize, :scope => [:mail_form]))
+  end
+
+  # Return the errors in this form. The object returned as the same API as the
+  # ActiveRecord one.
+  #
+  def errors
+    @errors ||= MailForm::Errors.new(self)
+  end
+
+end

data/lib/mail_form/dsl.rb

@@ -0,0 +1,171 @@
+class MailForm
+  module DSL
+
+    protected
+
+      # Declare your form attributes. All attributes declared here will be appended
+      # to the e-mail, except the ones captcha is true.
+      #
+      # == Options
+      #
+      # * <tt>:validate</tt> - 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).
+      #
+      # * <tt>:attachment</tt> - When given, expects a file to be sent and attaches
+      #   it to the e-mail. Don't forget to set your form to multitype.
+      #
+      # * <tt>:captcha</tt> - When true, validates the attributes must be blank
+      #   This is a simple way to avoid spam
+      #
+      # == Examples
+      #
+      #   class ContactForm < MailForm
+      #     attributes :name,  :validate => true
+      #     attributes :email, :validate => /^([^@]+)@((?:[-a-z0-9]+\.)+[a-z]{2,})$/i
+      #     attributes :message
+      #     attributes :type
+      #     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 when you are reporting an interface bug")
+      #       end
+      #     end
+      #   end
+      #
+      def attribute(*accessors)
+        options = accessors.extract_options!
+
+        attr_accessor *accessors
+
+        if options[:attachment]
+          write_inheritable_array(:form_attachments, accessors)
+        elsif options[:captcha]
+          write_inheritable_array(:form_captcha, accessors)
+        else
+          write_inheritable_array(:form_attributes, accessors)
+        end
+
+        if options[:validate]
+          validations = {}
+          accessors.each{ |a| validations[a] = options[:validate] }
+
+          write_inheritable_hash(:form_validatable, validations)
+        end
+      end
+      alias :attributes :attribute
+
+      # 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 simple form
+      # instance. By default is the class human name.
+      #
+      # == Examples
+      #
+      #   class ContactForm < MailForm
+      #     subject "My Contact Form"
+      #   end
+      #
+      def subject(duck=nil, &block)
+        write_inheritable_attribute(:form_subject, duck || block)
+      end
+
+      # 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 simple form
+      # instance. By default is:
+      #
+      #   sender{ |c| c.email }
+      #
+      # This requires that your MailForm object have an email attribute.
+      #
+      # == Examples
+      #
+      #   class ContactForm < MailForm
+      #     # Change sender to include also the name
+      #     sender { |c| %{"#{c.name}" <#{c.email}>} }
+      #   end
+      #
+      def sender(duck=nil, &block)
+        write_inheritable_attribute(:form_sender, duck || block)
+      end
+      alias :from :sender
+
+      # 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 simple form instance.
+      #
+      # Both the proc and the symbol must return a string or an array. By default
+      # is nil.
+      #
+      # == Examples
+      #
+      #   class ContactForm < MailForm
+      #     recipients [ "first.manager@domain.com", "second.manager@domain.com" ]
+      #   end
+      #
+      def recipients(duck=nil, &block)
+        write_inheritable_attribute(:form_recipients, duck || block)
+      end
+      alias :to :recipients
+
+      # Additional headers to your e-mail.
+      #
+      # == Examples
+      #
+      #   class ContactForm < MailForm
+      #     headers { :content_type => 'text/html' }
+      #   end
+      #
+      def headers(hash)
+        write_inheritable_hash(:form_headers, hash)
+      end
+
+      # Customized template for your e-mail, if you don't want to use default
+      # 'contact' template or need more than one contact form with different
+      # template layouts.
+      #
+      # 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 simple form
+      # instance. Both method and proc must return a string with the template
+      # name. Defaults to 'contact'.
+      #
+      # == Examples
+      #
+      #   class ContactForm < MailForm
+      #     # look for a template in views/mail_form/notifier/my_template.erb
+      #     template 'my_template'
+      #   end
+      #
+      def template(new_template)
+        write_inheritable_attribute(:form_template, new_template)
+      end
+
+      # Values from request object to be appended to the contact form.
+      # Whenever used, you have to send the request object when initializing the object:
+      #
+      #   @contact_form = ContactForm.new(params[:contact_form], request)
+      #
+      # You can get the values to be appended from the AbstractRequest
+      # documentation (http://api.rubyonrails.org/classes/ActionController/AbstractRequest.html)
+      #
+      # == Examples
+      #
+      #   class ContactForm < MailForm
+      #     append :remote_ip, :user_agent, :session, :cookies
+      #   end
+      #
+      def append(*values)
+        write_inheritable_array(:form_appendable, values)
+      end
+
+  end
+end

data/lib/mail_form/errors.rb

@@ -0,0 +1,59 @@
+# Provides an Errors class similar with ActiveRecord ones.
+#
+#   class ContactForm < MailForm
+#     attributes :name,  :validate => true
+#     attributes :email, :validate => /^([^@]+)@((?:[-a-z0-9]+\.)+[a-z]{2,})$/i
+#     attributes :message
+#     attributes :nickname, :captcha => true
+#   end
+#
+# When validating an attribute name as above, it will search for messages in
+# the following order:
+#
+#   mail_form.messages.name
+#   mail_form.messages.blank
+#
+# When validating email, it will search for:
+#
+#   mail_form.messages.name
+#   mail_form.messages.invalid
+#
+# If the message is not available, it will output: "can't be blank" in the first
+# case and "is invalid" in the second.
+#
+class MailForm
+  class Errors < Hash
+
+    def initialize(base, *args)
+      @base = base
+      super(*args)
+    end
+
+    alias :add   :store
+    alias :count :size
+    alias :get   :[]
+
+    def on(attribute)
+      attribute = attribute.to_sym
+      return nil unless get(attribute)
+
+      generate_message_for(attribute, get(attribute))
+    end
+    alias :[] :on
+
+    def full_messages
+      map do |attribute, message|
+        next if message.nil?
+        attribute = attribute.to_sym
+        "#{@base.class.human_attribute_name(attribute)} #{generate_message_for(attribute, message)}"
+      end.compact.reverse
+    end
+
+    protected
+
+      def generate_message_for(attribute, message)
+        I18n.t(attribute, :default => [ message, DEFAULT_MESSAGES[message] ], :scope => [:mail_form, :messages])
+      end
+
+  end
+end

data/lib/mail_form/notifier.rb

@@ -0,0 +1,48 @@
+# This is the class responsable to send the e-mails.
+#
+class MailForm
+  class Notifier < ActionMailer::Base
+
+    def contact(form)
+      @from       = get_from_class_and_eval(form, :form_sender)
+      @subject    = get_from_class_and_eval(form, :form_subject)
+      @recipients = get_from_class_and_eval(form, :form_recipients)
+      @template   = get_from_class_and_eval(form, :form_template)
+
+      raise ScriptError, "You forgot to setup #{form.class.name} recipients" if @recipients.blank?
+      raise ScriptError, "You set :append values but forgot to give me the request object" if form.request.nil? && !form.class.form_appendable.blank?
+
+      @body['form']    = form
+      @body['subject'] = @subject
+
+      @sent_on = Time.now.utc
+      @headers = form.class.form_headers
+      @content_type = 'text/html'
+
+      form.class.form_attachments.each do |attribute|
+        value = form.send(attribute)
+        if value.respond_to?(:read)
+          attachment value.content_type.to_s do |att|
+            att.filename = value.original_filename
+            att.body = value.read
+          end
+        end
+      end
+    end
+
+    protected
+
+      def get_from_class_and_eval(form, method)
+        duck = form.class.send(method)
+
+        if duck.is_a?(Proc)
+          duck.call(form)
+        elsif duck.is_a?(Symbol)
+          form.send(duck)
+        else
+          duck
+        end
+      end
+
+  end
+end

data/lib/mail_form/version.rb

@@ -0,0 +1,3 @@
+module MailForm
+  VERSION = "1.0.0".freeze
+end

data/test/base_test.rb

@@ -0,0 +1,110 @@
+require File.dirname(__FILE__) + '/test_helper'
+
+class MailFormBaseTest < ActiveSupport::TestCase
+
+  def setup
+    ActionMailer::Base.deliveries = []
+  end
+
+  def test_id_is_nil
+    assert_equal nil, ContactForm.new.id
+  end
+
+  def test_is_always_a_new_record
+    assert ContactForm.new.new_record?
+  end
+
+  def test_initialize_with_options
+    form = ContactForm.new(:name => 'José', :email => 'jose@my.email.com')
+    assert_equal 'José', form.name
+    assert_equal 'jose@my.email.com', form.email
+  end
+
+  def test_spam_is_true_when_captcha_field_is_set
+    form = ContactForm.new(:nickname => 'not_blank')
+    assert form.spam?
+    assert !form.not_spam?
+  end
+
+  def test_spam_is_false_when_captcha_field_is_not_set
+    form = ContactForm.new
+    assert !form.spam?
+    assert form.not_spam?
+  end
+
+  def test_is_not_valid_when_validatable_attributes_are_blank
+    form = ContactForm.new
+    assert !form.valid?
+    assert form.invalid?
+
+    assert_equal(2, form.errors.count)
+    assert_equal({:email=>:blank, :name=>:blank}, form.errors)
+  end
+
+  def test_is_not_valid_when_validatable_regexp_does_not_match
+    form = ContactForm.new(:name => 'Jose', :email => 'not_valid')
+    assert !form.valid?
+    assert form.invalid?
+
+    assert_equal(1, form.errors.count)
+    assert_equal({:email=>:invalid}, form.errors)
+  end
+
+  def test_is_valid_when_validatable_attributes_are_valid
+    form = ContactForm.new(:name => 'Jose', :email => 'is.valid@email.com')
+    assert form.valid?
+    assert !form.invalid?
+  end
+
+  def test_symbols_given_to_validate_are_called
+    form = ContactForm.new
+    assert form.instance_variable_get('@_callback_run').nil?
+    form.valid?
+    assert form.instance_variable_get('@_callback_run')
+  end
+
+  def test_deliver_is_false_when_is_a_spam
+    form = ContactForm.new(:name => 'Jose', :email => 'is.valid@email.com', :nickname => 'not_blank')
+    assert form.valid?
+    assert form.spam?
+    assert !form.deliver
+  end
+
+  def test_deliver_is_false_when_is_invalid
+    form = ContactForm.new(:name => 'Jose', :email => 'is.com')
+    assert form.invalid?
+    assert form.not_spam?
+    assert !form.deliver
+  end
+
+  def test_deliver_is_true_when_is_not_spam_and_valid
+    form = ContactForm.new(:name => 'Jose', :email => 'is.valid@email.com')
+    assert form.valid?
+    assert form.not_spam?
+    assert form.deliver
+    assert_equal 1, ActionMailer::Base.deliveries.size
+  end
+
+  def test_human_name_returns_a_humanized_name
+    assert_equal 'Contact form', ContactForm.human_name
+  end
+
+  def test_human_name_can_be_localized
+    I18n.backend.store_translations(:en, :mail_form => { :models => { :contact_form => 'Formulário de contato' } })
+    assert_equal 'Formulário de contato', ContactForm.human_name
+  end
+
+  def test_human_attribute_name_returns_a_humanized_attribute
+    assert_equal 'Message', ContactForm.human_attribute_name(:message)
+  end
+
+  def test_human_attribute_name_can_be_localized
+    I18n.backend.store_translations(:en, :mail_form => { :attributes => { :message => 'Mensagem' } })
+    assert_equal 'Mensagem', ContactForm.human_attribute_name(:message)
+  end
+
+  def teardown
+    I18n.reload!
+  end
+
+end

data/test/errors_test.rb

@@ -0,0 +1,85 @@
+require File.dirname(__FILE__) + '/test_helper'
+
+class MailFormErrorsTest < ActiveSupport::TestCase
+
+  def test_errors_respond_to_some_hash_methods
+    assert ContactForm.new.errors.respond_to?(:each)
+    assert ContactForm.new.errors.respond_to?(:each_pair)
+    assert ContactForm.new.errors.respond_to?(:size)
+  end
+
+  def test_count_is_an_alias_to_size
+    errors = ContactForm.new.errors
+    assert_equal errors.size, errors.count
+  end
+
+  def test_on_returns_the_message_in_the_given_attribute
+    form = ContactForm.new(:email => 'not_valid')
+    form.valid?
+    assert_equal "can't be blank", form.errors.on(:name)
+    assert_equal "is invalid",     form.errors.on(:email)
+    assert_equal nil,              form.errors.on(:message)
+  end
+
+  def test_on_returns_a_default_localized_message_in_the_given_attribute
+    I18n.backend.store_translations(:en, :mail_form => { :messages => { :invalid => 'is not valid', :blank => 'should be filled' } })
+
+    form = ContactForm.new(:email => 'not_valid')
+    form.valid?
+
+    assert_equal "should be filled", form.errors.on(:name)
+    assert_equal "is not valid",     form.errors.on(:email)
+    assert_equal nil,                form.errors.on(:message)
+  end
+
+  def test_on_returns_an_attribute_localized_message_in_the_given_attribute
+    I18n.backend.store_translations(:en, :mail_form => { :messages => { :email => 'fill in the email', :name => 'fill in the name' } })
+
+    form = ContactForm.new(:email => 'not_valid')
+    form.valid?
+
+    assert_equal "fill in the name",  form.errors.on(:name)
+    assert_equal "fill in the email", form.errors.on(:email)
+    assert_equal nil,                 form.errors.on(:message)
+  end
+
+  def test_array_like_option_acts_as_an_alias_for_on
+    form = ContactForm.new(:email => 'not_valid')
+    form.valid?
+    assert_equal "can't be blank",       form.errors[:name]
+    assert_equal form.errors.on(:name),  form.errors[:name]
+    assert_equal "is invalid",           form.errors[:email]
+    assert_equal form.errors.on(:email), form.errors[:email]
+    assert_equal nil,                    form.errors[:message]
+  end
+
+  def test_get_returns_the_real_value_in_the_given_attribute
+    form = ContactForm.new(:email => 'not_valid')
+    form.valid?
+    assert_equal :blank,   form.errors.get(:name)
+    assert_equal :invalid, form.errors.get(:email)
+    assert_equal nil,      form.errors.get(:message)
+  end
+
+  def test_full_messages
+    form = ContactForm.new(:email => 'not_valid')
+    form.valid?
+
+    assert form.errors.full_messages.include?("Name can't be blank")
+    assert form.errors.full_messages.include?("Email is invalid")
+  end
+
+  def test_full_localized_messages
+    I18n.backend.store_translations(:en, :mail_form => { :messages => { :email => 'is not valid', :blank => 'should be filled' }, :attributes => { :email => 'E-mail' } })
+
+    form = ContactForm.new(:email => 'not_valid')
+    form.valid?
+
+    assert form.errors.full_messages.include?("Name should be filled")
+    assert form.errors.full_messages.include?("E-mail is not valid")
+  end
+
+  def teardown
+    I18n.reload!
+  end
+end

data/test/notifier_test.rb

@@ -0,0 +1,183 @@
+require File.dirname(__FILE__) + '/test_helper'
+
+class MailFormNotifierTest < ActiveSupport::TestCase
+
+  def setup
+    @form = ContactForm.new(:name => 'José', :email => 'my.email@my.domain.com', :message => 'Cool')
+
+    @request          = ActionController::TestRequest.new
+    @valid_attributes = { :name => 'José', :email => 'my.email@my.domain.com', :message => "Cool\nno?" }
+    @advanced         = AdvancedForm.new(@valid_attributes, @request)
+
+    test_file  = ActionController::TestUploadedFile.new(File.join(File.dirname(__FILE__), 'test_file.txt'))
+    @with_file = FileForm.new(:name => 'José', :email => 'my.email@my.domain.com', :message => "Cool", :file => test_file)
+
+    @template = TemplateForm.new(@valid_attributes)
+
+    ActionMailer::Base.deliveries = []
+  end
+
+  def test_email_is_sent
+    @form.deliver
+    assert_equal 1, ActionMailer::Base.deliveries.size
+  end
+
+  def test_subject_defaults_to_class_human_name
+    @form.deliver
+    assert_equal 'Contact form', ActionMailer::Base.deliveries.first.subject
+  end
+
+  def test_subject_is_a_string
+    @advanced.deliver
+    assert_equal 'My Advanced Form', ActionMailer::Base.deliveries.first.subject
+  end
+
+  def test_sender_defaults_to_form_email
+    @form.deliver
+    assert_equal ['my.email@my.domain.com'], ActionMailer::Base.deliveries.first.from
+  end
+
+  def test_error_is_raised_when_recipients_is_nil
+    assert_raise ScriptError do
+      NullRecipient.new.deliver
+    end
+  end
+
+  def test_recipients_is_a_string
+    @form.deliver
+    assert_equal ['my.email@my.domain.com'], ActionMailer::Base.deliveries.first.to
+  end
+
+  def test_recipients_is_an_array
+    @advanced.deliver
+    assert_equal ['my.first@email.com', 'my.second@email.com'], ActionMailer::Base.deliveries.first.to
+  end
+
+  def test_recipients_is_a_symbold
+    @with_file.deliver
+    assert_equal ['contact_file@my.domain.com'], ActionMailer::Base.deliveries.first.to
+  end
+
+  def test_headers_is_a_hash
+    @advanced.deliver
+    assert_equal '<mypath>', ActionMailer::Base.deliveries.first.header['return-path'].to_s
+  end
+
+  def test_body_contains_subject
+    @form.deliver
+    assert_match /Contact form/, ActionMailer::Base.deliveries.first.body
+  end
+
+  def test_body_contains_attributes_values
+    @form.deliver
+    assert_match /José/, ActionMailer::Base.deliveries.first.body
+    assert_match /my.email@my.domain.com/, ActionMailer::Base.deliveries.first.body
+    assert_match /Cool/, ActionMailer::Base.deliveries.first.body
+  end
+
+  def test_body_contains_attributes_names
+    @form.deliver
+    assert_match /Name:/, ActionMailer::Base.deliveries.first.body
+    assert_match /Email:/, ActionMailer::Base.deliveries.first.body
+    assert_match /Message:/, ActionMailer::Base.deliveries.first.body
+  end
+
+  def test_body_contains_localized_attributes_names
+    I18n.backend.store_translations(:en, :mail_form => { :attributes => { :message => 'Sent message' } })
+    @form.deliver
+    assert_match /Sent message:/, ActionMailer::Base.deliveries.first.body
+    assert_no_match /Message:/, ActionMailer::Base.deliveries.first.body
+  end
+
+  def test_body_mail_format_messages_with_break_line
+    @form.deliver
+    assert_no_match /<p>Cool/, ActionMailer::Base.deliveries.first.body
+
+    @advanced.deliver
+    assert_match /<p>Cool/, ActionMailer::Base.deliveries.last.body
+  end
+
+  def test_body_does_not_append_request_if_append_is_not_called
+    @form.deliver
+    assert_no_match /Request information/, ActionMailer::Base.deliveries.first.body
+  end
+
+  def test_body_does_append_request_if_append_is_called
+    @advanced.deliver
+    assert_match /Request information/, ActionMailer::Base.deliveries.last.body
+  end
+
+  def test_request_title_is_localized
+    I18n.backend.store_translations(:en, :mail_form => { :request => { :title => 'Information about the request' } })
+    @advanced.deliver
+    assert_no_match /Request information/, ActionMailer::Base.deliveries.last.body
+    assert_match /Information about the request/, ActionMailer::Base.deliveries.last.body
+  end
+
+  def test_request_info_attributes_are_printed
+    @advanced.deliver
+    assert_match /Remote ip/, ActionMailer::Base.deliveries.last.body
+    assert_match /User agent/, ActionMailer::Base.deliveries.last.body
+  end
+
+  def test_request_info_attributes_are_localized
+    I18n.backend.store_translations(:en, :mail_form => { :request => { :remote_ip => 'IP Address' } })
+    @advanced.deliver
+    assert_match /IP Address/, ActionMailer::Base.deliveries.last.body
+    assert_no_match /Remote ip/, ActionMailer::Base.deliveries.last.body
+  end
+
+  def test_request_info_values_are_printed
+    @advanced.deliver
+    assert_match /0\.0\.0\.0/, ActionMailer::Base.deliveries.last.body
+    assert_match /Rails Testing/, ActionMailer::Base.deliveries.last.body
+  end
+
+  def test_request_info_hashes_are_print_inside_lis
+    @request.session = { :my => :session, :user => "data" }
+    @advanced.deliver
+    assert_match /<li>my: :session<\/li>/, ActionMailer::Base.deliveries.last.body
+    assert_match /<li>user: &quot;data&quot;<\/li>/, ActionMailer::Base.deliveries.last.body
+  end
+
+  def test_error_is_raised_when_append_is_given_but_no_request_is_given
+    assert_raise ScriptError do
+      @advanced.request = nil
+      @advanced.deliver
+    end
+  end
+
+  def test_form_with_file_includes_an_attachment
+    @with_file.deliver
+
+    #For some reason I need to encode the mail before the attachments array returns values
+    ActionMailer::Base.deliveries.first.to_s
+    assert_equal 1, ActionMailer::Base.deliveries.first.attachments.size
+  end
+
+  def test_form_with_file_does_not_output_attachment_as_attribute
+    @with_file.deliver
+    assert_no_match /File/, ActionMailer::Base.deliveries.first.body
+  end
+
+  def test_form_with_customized_template_raise_missing_template_if_not_found
+    assert_raise ActionView::MissingTemplate do
+      @template.deliver
+    end
+  end
+
+  def test_form_with_customized_template_render_correct_template
+    begin
+      default_template_root = MailForm::Notifier.template_root
+      MailForm::Notifier.template_root = File.join(File.dirname(__FILE__), 'views')
+      @template.deliver
+      assert_match 'Hello from my cystom template!', ActionMailer::Base.deliveries.last.body
+    ensure
+      MailForm::Notifier.template_root = default_template_root
+    end
+  end
+
+  def teardown
+    I18n.reload!
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,64 @@
+require 'test/unit'
+require 'rubygems'
+
+RAILS_ENV = ENV["RAILS_ENV"] = "test"
+
+require 'active_support'
+require 'active_support/test_case'
+require 'action_mailer'
+require 'action_controller/test_case'
+
+ActionMailer::Base.delivery_method = :test
+
+# Load respond_to before defining ApplicationController
+require File.dirname(__FILE__) + '/../lib/mail_form.rb'
+
+class ContactForm < MailForm
+  recipients 'my.email@my.domain.com'
+
+  attribute :name,     :validate => true
+  attribute :email,    :validate => /[^@]+@[^\.]+\.[\w\.\-]+/
+  attribute :nickname, :captcha => true
+  attributes :tellphone, :message, :validate => :callback
+
+  def callback
+    @_callback_run = true
+  end
+end
+
+class AdvancedForm < ContactForm
+  append :remote_ip, :user_agent, :session
+
+  recipients [ 'my.first@email.com', 'my.second@email.com' ]
+  subject 'My Advanced Form'
+  sender{|c| %{"#{c.name}" <#{c.email}>} }
+  headers 'return-path' => 'mypath'
+end
+
+class FileForm < ContactForm
+  attribute :file, :attachment => true, :validate => true
+  recipients :set_recipient
+
+  def set_recipient
+    if file
+      "contact_file@my.domain.com"
+    else
+      "contact@my.domain.com"
+    end
+  end
+end
+
+class NullRecipient < MailForm
+  sender 'my.email@my.domain.com'
+end
+
+class TemplateForm < ContactForm
+  template 'custom_template'
+end
+
+# Needed to correctly test an uploaded file
+class ActionController::TestUploadedFile
+  def read
+    @tempfile.read
+  end
+end

data/views/mail_form/notifier/contact.erb

@@ -0,0 +1,30 @@
+<h4 style="text-decoration:underline"><%=h @subject %></h4>
+
+<% @form.class.form_attributes.each do |attribute|
+  value = @form.send(attribute)
+  next if value.blank? %>
+
+  <p><b><%= @form.class.human_attribute_name(attribute) %>:</b>
+  <%= value.include?("\n") ? simple_format(h(value)) : h(value) %></p>
+<% end %>
+
+<% unless @form.class.form_appendable.blank? %>
+  <br /><h4 style="text-decoration:underline"><%= I18n.t :title, :scope => [ :mail_form, :request ], :default => 'Request information' %></h4>
+
+  <% @form.class.form_appendable.each do |attribute|
+    value = @form.request.send(attribute)
+
+    value = if value.is_a?(Hash) && !value.empty?
+      content_tag(:ul, value.to_a.map{|k,v| content_tag(:li, h("#{k}: #{v.inspect}")) }.join("\n"), :style => "list-style:none;")
+    elsif value.is_a?(String)
+      h(value)
+    else
+      h(value.inspect)
+    end
+  %>
+
+    <p><b><%= I18n.t attribute, :scope => [ :mail_form, :request ], :default => attribute.to_s.humanize %>:</b>
+    <%= value.include?("\n") ? simple_format(value) : value %></p>
+  <% end %>
+  <br />
+<% end %>

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification 
+name: mail_form
+version: !ruby/object:Gem::Version 
+  version: 1.0.0
+platform: ruby
+authors: 
+- "Jos\xC3\xA9 Valim"
+- "Carlos Ant\xC3\xB4nio"
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-12-24 00:00:00 +01:00
+default_executable: 
+dependencies: []
+
+description: Send e-mail straight from forms in Rails with I18n, validations, attachments and request information.
+email: contact@plataformatec.com.br
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- CHANGELOG
+- MIT-LICENSE
+- README.rdoc
+- Rakefile
+- lib/mail_form.rb
+- lib/mail_form/base.rb
+- lib/mail_form/dsl.rb
+- lib/mail_form/errors.rb
+- lib/mail_form/notifier.rb
+- lib/mail_form/version.rb
+- views/mail_form/notifier/contact.erb
+has_rdoc: true
+homepage: http://github.com/plataformatec/mail_form
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Send e-mail straight from forms in Rails with I18n, validations, attachments and request information.
+test_files: 
+- test/base_test.rb
+- test/errors_test.rb
+- test/notifier_test.rb
+- test/test_helper.rb