Permalink
Browse files

Update documentation.

  • Loading branch information...
josevalim committed Dec 28, 2009
1 parent c58f0f0 commit 97e4727ddf1262881831bcda26301a444c81324e
Showing with 69 additions and 55 deletions.
  1. +16 −10 README.rdoc
  2. +25 −20 lib/mail_form.rb
  3. +28 −25 lib/mail_form/delivery.rb
View
@@ -48,13 +48,13 @@ so MailForm can be used in your controllers and form builders without extra twea
==== 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:
+MailForm::Delivery in your model and declare which attributes should be sent:
class User < ActiveRecord::Base
include MailForm::Delivery
append :remote_ip, :user_agent, :session
+ attributes :name, :email, :created_at
subject "New user created"
recipients "your.email@your.domain.com"
end
@@ -78,12 +78,15 @@ 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.
@@ -96,12 +99,15 @@ Examples:
class ContactForm < MailForm::Resource
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
View
@@ -6,40 +6,45 @@ class MailForm < ActionMailer::Base
self.template_root = File.expand_path('../views', File.dirname(__FILE__))
- def default(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)
+ def default(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
- 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?
+ 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 = form
+ @resource = @form = resource
@sent_on = Time.now.utc
- @headers = form.class.form_headers
+ @headers = resource.class.mail_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
+ resource.class.mail_attachments.each do |attribute|
+ value = resource.send(attribute)
+ next unless value.respond_to?(:read)
+
+ attachment value.content_type.to_s do |att|
+ att.filename = value.original_filename
+ att.body = value.read
end
end
end
protected
- def get_from_class_and_eval(form, method)
- duck = form.class.send(method)
+ def get_from_class_and_eval(resource, method)
+ duck = resource.class.send(method)
if duck.is_a?(Proc)
- duck.call(form)
+ duck.call(resource)
elsif duck.is_a?(Symbol)
- form.send(duck)
+ resource.send(duck)
else
duck
end
View
@@ -1,19 +1,19 @@
module MailForm::Delivery
extend ActiveSupport::Concern
- ACCESSORS = [ :form_attributes, :form_subject, :form_captcha,
- :form_attachments, :form_recipients, :form_sender,
- :form_headers, :form_template, :form_appendable ]
+ ACCESSORS = [ :mail_attributes, :mail_subject, :mail_captcha,
+ :mail_attachments, :mail_recipients, :mail_sender,
+ :mail_headers, :mail_template, :mail_appendable ]
included do
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_array :mail_captcha, []
+ write_inheritable_array :mail_appendable, []
+ write_inheritable_array :mail_attributes, []
+ write_inheritable_array :mail_attachments, []
headers({})
sender {|c| c.email }
@@ -33,12 +33,15 @@ module ClassMethods
#
# == 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).
+ # * :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).
#
# * <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.
@@ -51,8 +54,8 @@ module ClassMethods
# class ContactForm < MailForm
# attributes :name, :validate => true
# attributes :email, :validate => /^([^@]+)@((?:[-a-z0-9]+\.)+[a-z]{2,})$/i
+ # attributes :type, :validate => ["General", "Interface bug"]
# attributes :message
- # attributes :type
# attributes :screenshot, :attachment => true, :validate => :interface_bug?
# attributes :nickname, :captcha => true
#
@@ -68,11 +71,11 @@ def attribute(*accessors)
attr_accessor *(accessors - instance_methods.map(&:to_sym))
if options[:attachment]
- write_inheritable_array(:form_attachments, accessors)
+ write_inheritable_array(:mail_attachments, accessors)
elsif options[:captcha]
- write_inheritable_array(:form_captcha, accessors)
+ write_inheritable_array(:mail_captcha, accessors)
else
- write_inheritable_array(:form_attributes, accessors)
+ write_inheritable_array(:mail_attributes, accessors)
end
validation = options.delete(:validate)
@@ -109,7 +112,7 @@ def attribute(*accessors)
# end
#
def subject(duck=nil, &block)
- write_inheritable_attribute(:form_subject, duck || block)
+ write_inheritable_attribute(:mail_subject, duck || block)
end
# Declares contact email sender. It can be a string or a proc or a symbol.
@@ -130,7 +133,7 @@ def subject(duck=nil, &block)
# end
#
def sender(duck=nil, &block)
- write_inheritable_attribute(:form_sender, duck || block)
+ write_inheritable_attribute(:mail_sender, duck || block)
end
alias :from :sender
@@ -149,7 +152,7 @@ def sender(duck=nil, &block)
# end
#
def recipients(duck=nil, &block)
- write_inheritable_attribute(:form_recipients, duck || block)
+ write_inheritable_attribute(:mail_recipients, duck || block)
end
alias :to :recipients
@@ -162,7 +165,7 @@ def recipients(duck=nil, &block)
# end
#
def headers(hash)
- write_inheritable_hash(:form_headers, hash)
+ write_inheritable_hash(:mail_headers, hash)
end
# Customized template for your e-mail, if you don't want to use default
@@ -182,7 +185,7 @@ def headers(hash)
# end
#
def template(new_template)
- write_inheritable_attribute(:form_template, new_template)
+ write_inheritable_attribute(:mail_template, new_template)
end
# Values from request object to be appended to the contact form.
@@ -200,7 +203,7 @@ def template(new_template)
# end
#
def append(*values)
- write_inheritable_array(:form_appendable, values)
+ write_inheritable_array(:mail_appendable, values)
end
end
@@ -212,7 +215,7 @@ def append(*values)
# returns false otherwise.
#
def spam?
- form_captcha.each do |field|
+ mail_captcha.each do |field|
next if send(field).blank?
if RAILS_ENV == 'development'
@@ -222,7 +225,7 @@ def spam?
end
end
- return false
+ false
end
def not_spam?

0 comments on commit 97e4727

Please sign in to comment.