Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

markdownify README #15

Merged
merged 1 commit into from

2 participants

Vasiliy Ermolovich José Valim
Vasiliy Ermolovich
Collaborator

:wink:

José Valim josevalim merged commit 7bc9769 into from
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Mar 25, 2012
  1. Vasiliy Ermolovich

    markdownify README

    nashby authored
This page is out of date. Refresh to see the latest.
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
217 README.md
View
@@ -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/
199 README.rdoc
View
@@ -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/
2  Rakefile
View
@@ -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
2  mail_form.gemspec
View
@@ -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"]
Something went wrong with that request. Please try again.