Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

markdownify README

  • Loading branch information...
commit b48ac73644d834b1d637338ad22a20fa130abb66 1 parent d5d37f4
@nashby nashby authored
Showing with 219 additions and 201 deletions.
  1. +217 −0 README.md
  2. +0 −199 README.rdoc
  3. +1 −1  Rakefile
  4. +1 −1  mail_form.gemspec
View
217 README.md
@@ -0,0 +1,217 @@
+## 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):
+
+```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 `script/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. 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 - 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"
+```
+
+## 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/
View
199 README.rdoc
@@ -1,199 +0,0 @@
-== 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::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 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 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:
-
- attribute :email, :validate => /\A([\w\.%\+\-]+)@([\w\-]+\.)+([\w]{2,})\z/i
-
-You could actually do this:
-
- 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:
-
- 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. 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 - 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:
-
- 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:
-
- 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.
-
-== 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:
-
- 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"
-
-== 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/
View
2  Rakefile
@@ -21,6 +21,6 @@ RDoc::Task.new(:rdoc) do |rdoc|
rdoc.rdoc_dir = 'rdoc'
rdoc.title = 'MailForm'
rdoc.options << '--line-numbers'
- rdoc.rdoc_files.include('README.rdoc')
+ rdoc.rdoc_files.include('README.md')
rdoc.rdoc_files.include('lib/**/*.rb')
end
View
2  mail_form.gemspec
@@ -12,7 +12,7 @@ Gem::Specification.new do |s|
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 = Dir["CHANGELOG", "MIT-LICENSE", "README.rdoc", "lib/**/*"]
+ s.files = Dir["CHANGELOG", "MIT-LICENSE", "README.md", "lib/**/*"]
s.test_files = Dir["test/**/*"]
s.require_paths = ["lib"]
Please sign in to comment.
Something went wrong with that request. Please try again.