mail_form 1.0.0 → 1.1.0

data/README.rdoc

@@ -1,9 +1,21 @@
 == 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
+  class ContactForm < MailForm::Base
     subject "My Contact Form"
     recipients "your.email@your.domain.com"
     sender{|c| %{"#{c.name}" <#{c.email}>} }
@@ -19,61 +31,73 @@ if you want to make a contact form just the following lines are needed (includin
 Then you start a script/console and type:
 
   c = ContactForm.new(:name => 'José', :email => 'jose@email.com', :message => 'Cool!')
-  c.deliver
+  c.create
 
-Check your inbox and the e-mail will be there, with the sent fields (assuming
-that you configured your delivery method properly).
+Check your inbox and the e-mail will be there, with the sent fields (assuming that
+you configured your mailer 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.
+=== MailForm::Base
 
-It's tested and compatible with Rails 2.2.x and Rails 2.3.x.
+When you inherit from MailForm::Base, it pulls down a set of stuff from ActiveModel,
+as ActiveModel::Validation, ActiveModel::Translation and ActiveModel::Naming.
 
-== Installation
+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:
 
-Install MailForm is very easy. It is stored in Gemcutter, so just run the following:
+  attribute :email, :validate => /[^@]+@[^\.]+\.[\w\.\-]+/
 
-   sudo gem install mail_form --version=1.0.0
+You could actually do this:
 
-If you want it as plugin, just do:
+  attribute :email
+  validates_format_of :email, :with => /[^@]+@[^\.]+\.[\w\.\-]+/
 
-   script/plugin install git://github.com/plataformatec/mail_form.git
+Choose the one which pleases you the most. For more information on the API, please
+continue reading below.
 
-== Request
+=== Playing together ORMs
 
-MailForm makes easy to append user information to the contact mail. You just
-have to do:
+MailForm plays nice with ORMs as well. You just need to include MailForm::Delivery
+in your model and declare which attributes should be sent:
+
+  class User < ActiveRecord::Base
+    include MailForm::Delivery
 
-  class ContactForm < MailForm
     append :remote_ip, :user_agent, :session
-    # ...
+    attributes :name, :email, :created_at
+    subject "New user created"
+    recipients "your.email@your.domain.com"
   end
 
-And in your controller:
+The delivery will be triggered in an after_create hook.
 
-  @contact_form = ContactForm.new(params[:contact_form])
-  @contact_form.request = request
+== Installation
 
-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.
+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)
+=== 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.
+* :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 a symbol, the method given as symbol will be
-  called. You can then add validations as you do in ActiveRecord (errors.add).
+  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.
@@ -83,15 +107,18 @@ Options:
 
 Examples:
 
-   class ContactForm < MailForm
+   class ContactForm < MailForm::Base
      attributes :name,  :validate => true
      attributes :email, :validate => /[^@]+@[^\.]+\.[\w\.\-]+/
+     attributes :type,  :validate => ["General", "Interface bug"]
      attributes :message
-     attributes :screenshot, :attachment => true, :validate => :screenshot_required?
+     attributes :screenshot, :attachment => true, :validate => :interface_bug?
      attributes :nickname,   :captcha => true
 
-     def screenshot_required?
-       # ...
+     def interface_bug?
+       if type == 'Interface bug' && screenshot.nil?
+         self.errors.add(:screenshot, "can't be blank on interface bugs")
+       end
      end
    end
 
@@ -106,10 +133,9 @@ Examples:
    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
+   c.deliver #=> true
 
-==== subject(string_or_symbol_or_block)
+=== subject(string_or_symbol_or_block)
 
 Declares the subject of the contact email. It can be a string or a proc or a symbol.
 
@@ -120,7 +146,7 @@ to the class human name.
    subject "My Contact Form"
    subject { |c| "Contacted by #{c.name}" }
 
-==== sender(string_or_symbol_or_block)
+=== sender(string_or_symbol_or_block)
 
 Declares contact email sender. It can be a string or a proc or a symbol.
 
@@ -131,7 +157,7 @@ name as the symbol. As a proc, it receives a mail form instance. By default is:
 
 This requires that your MailForm object have an email attribute.
 
-==== recipients(string_or_array_or_symbol_or_block)
+=== 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.
 
@@ -140,31 +166,59 @@ 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)
+=== append(*methods)
+
+MailForm also makes easy to append request information from client to the sent
+mail. You just have to do:
+
+  class ContactForm < MailForm::Base
+    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.
+
+=== 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)
+=== 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:
 
-Additional headers to your e-mail.
+  MailForm.template_root = File.join(Rails.root, "app", "views")
 
 == I18n
 
-All models, attributes and messages in MailForm can be used with localized.
-Below is an I18n example file:
+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:
-      email: "E-mail"
-      telephone: "Telephone number"
-      message: "Sent message"
-    messages:
-      blank: "can not be blank"
-      invalid: "is not valid"
-      telephone: "must have eight digits"
+      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"

data/Rakefile

@@ -5,6 +5,7 @@ require File.join(File.dirname(__FILE__), "lib", "mail_form", "version")
 
 desc 'Run tests for MailForm.'
 Rake::TestTask.new(:test) do |t|
+  t.libs   << 'test'
   t.pattern = 'test/**/*_test.rb'
   t.verbose = true
 end

data/lib/mail_form.rb

@@ -1,32 +1,48 @@
-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')
+class MailForm < ActionMailer::Base
+  autoload :Base,      'mail_form/base'
+  autoload :Callbacks, 'mail_form/callbacks'
+  autoload :Delivery,  'mail_form/delivery'
+  autoload :Shim,      'mail_form/shim'
+
+  append_view_path File.expand_path('../views', __FILE__)
+
+  def contact(resource)
+    @from       = get_from_class_and_eval(resource, :mail_sender)
+    @subject    = get_from_class_and_eval(resource, :mail_subject)
+    @recipients = get_from_class_and_eval(resource, :mail_recipients)
+    @template   = get_from_class_and_eval(resource, :mail_template)
+
+    if @recipients.blank?
+      raise ScriptError, "You forgot to setup #{resource.class.name} recipients"
+    end
+
+    if resource.request.nil? && resource.class.mail_appendable.present?
+      raise ScriptError, "You set :append values but forgot to give me the request object"
+    end
+
+    @resource = @form = resource
+    @sent_on  = Time.now.utc
+    @headers  = resource.class.mail_headers
+    @content_type = 'text/html'
+
+    resource.class.mail_attachments.each do |attribute|
+      value = resource.send(attribute)
+      next unless value.respond_to?(:read)
+      attachments[value.original_filename] = value.read
+    end
+  end
+
+  protected
+
+  def get_from_class_and_eval(resource, method)
+    duck = resource.class.send(method)
+
+    if duck.is_a?(Proc)
+      duck.call(resource)
+    elsif duck.is_a?(Symbol)
+      resource.send(duck)
+    else
+      duck
+    end
+  end
+end

data/lib/mail_form/base.rb

@@ -1,126 +1,8 @@
-class MailForm
-  attr_accessor :request
+class MailForm::Base
+  include MailForm::Shim
+  include MailForm::Delivery
 
-  # 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?
+  def self.lookup_ancestors
+    super - [MailForm::Base]
   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
+end