Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 228 lines (164 sloc) 7.023 kB
b48ac73 @nashby markdownify README
nashby authored
1 ## MailForm
5f0e1e0 @carlosantoniodasilva Add badges [ci skip]
carlosantoniodasilva authored
2
3 [![Gem Version](https://fury-badge.herokuapp.com/rb/mail_form.png)](http://badge.fury.io/rb/mail_form)
4 [![Build Status](https://api.travis-ci.org/plataformatec/mail_form.png?branch=master)](http://travis-ci.org/plataformatec/mail_form)
5 [![Code Climate](https://codeclimate.com/github/plataformatec/mail_form.png)](https://codeclimate.com/github/plataformatec/mail_form)
b48ac73 @nashby markdownify README
nashby authored
6
7 ### Rails 3
8
9 This gem was built on top of `ActiveModel` to showcase how you can pull in validations, naming
10 and `i18n` from Rails to your models without the need to implement it all by yourself.
11
c2a5c02 @carlosantoniodasilva Drop support to Rails < 3.2 and Ruby 1.8
carlosantoniodasilva authored
12 This README refers to the **MailForm** gem to be used in Rails 3.2 or 4+. For instructions
13 on how to use MailForm in older versions of Rails, please refer to the available branches.
b48ac73 @nashby markdownify README
nashby authored
14
15 ### Description
16
17 **MailForm** allows you to send an e-mail straight from a form. For instance,
18 if you want to make a contact form just the following lines are needed (including the e-mail):
19
20 ```ruby
21 class ContactForm < MailForm::Base
22 attribute :name, :validate => true
23 attribute :email, :validate => /\A([\w\.%\+\-]+)@([\w\-]+\.)+([\w]{2,})\z/i
24 attribute :file, :attachment => true
25
26 attribute :message
27 attribute :nickname, :captcha => true
28
29 # Declare the e-mail headers. It accepts anything the mail method
30 # in ActionMailer accepts.
31 def headers
32 {
33 :subject => "My Contact Form",
34 :to => "your.email@your.domain.com",
35 :from => %("#{name}" <#{email}>)
36 }
37 end
38 end
39 ```
40
5914ccf @robin850 Few improvement for the README file
robin850 authored
41 Then you start a console with `rails console` and type:
b48ac73 @nashby markdownify README
nashby authored
42
43 ```ruby
5914ccf @robin850 Few improvement for the README file
robin850 authored
44 >> c = ContactForm.new(:name => 'José', :email => 'jose@email.com', :message => 'Cool!')
45 >> c.deliver
b48ac73 @nashby markdownify README
nashby authored
46 ```
47
48 Check your inbox and the e-mail will be there, with the sent fields (assuming that
49 you configured your mailer delivery method properly).
50
51 ### MailForm::Base
52
53 When you inherit from `MailForm::Base`, it pulls down a set of stuff from `ActiveModel`,
54 as `ActiveModel::Validation`, `ActiveModel::Translation` and `ActiveModel::Naming`.
55
a11fb4f @brchristian Typo fix in README.md
brchristian authored
56 This brings `I18n`, error messages, validations and attributes handling like in
b48ac73 @nashby markdownify README
nashby authored
57 `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:
58
59 ```ruby
60 attribute :email, :validate => /\A([\w\.%\+\-]+)@([\w\-]+\.)+([\w]{2,})\z/i
61 ```
62
63 You could actually do this:
64
65 ```ruby
66 attribute :email
67 validates_format_of :email, :with => /\A([\w\.%\+\-]+)@([\w\-]+\.)+([\w]{2,})\z/i
68 ```
69
70 Choose the one which pleases you the most. For more information on the API, please
71 continue reading below.
72
73 ### Playing together ORMs
74
75 **MailForm** plays nice with ORMs as well. You just need to include `MailForm::Delivery`
76 in your model and declare which attributes should be sent:
77
78 ```ruby
79 class User < ActiveRecord::Base
80 include MailForm::Delivery
81
82 append :remote_ip, :user_agent, :session
83 attributes :name, :email, :created_at
84
85 def headers
86 {
87 :to => "your.email@your.domain.com",
88 :subject => "User created an account"
89 }
90 end
91 end
92 ```
93
5914ccf @robin850 Few improvement for the README file
robin850 authored
94 The delivery will be triggered in an `after_create` hook.
b48ac73 @nashby markdownify README
nashby authored
95
96 ## Installation
97
5914ccf @robin850 Few improvement for the README file
robin850 authored
98 Install **MailForm** is very easy. Just edit your Gemfile adding the following:
b48ac73 @nashby markdownify README
nashby authored
99
5914ccf @robin850 Few improvement for the README file
robin850 authored
100 ```ruby
101 gem 'mail_form'
102 ```
103 Then run `bundle install` to install **MailForm**.
b48ac73 @nashby markdownify README
nashby authored
104
105 If you want it as plugin, just do:
106
107 `script/plugin install git://github.com/plataformatec/mail_form.git`
108
109 ## API Overview
110
111 ### attributes(*attributes)
112
113 Declare your form attributes. All attributes declared here will be appended
114 to the e-mail, except the ones :captcha is true.
115
116 Options:
117
118 * :validate - A hook to validates_*_of. When true is given, validates the
119 presence of the attribute. When a regexp, validates format. When array,
120 validates the inclusion of the attribute in the array.
121
122 Whenever :validate is given, the presence is automatically checked. Give
123 :allow_blank => true to override.
124
125 Finally, when :validate is a symbol, the method given as symbol will be
126 called. Then you can add validations as you do in ActiveRecord (errors.add).
127
128 * :attachment - When given, expects a file to be sent and attaches
129 it to the e-mail. Don't forget to set your form to multitype.
130
131 * :captcha - When true, validates the attributes must be blank.
132 This is a simple way to avoid spam and the input should be hidden with CSS.
133
134 Examples:
135
136 ```ruby
137 class ContactForm < MailForm::Base
138 attributes :name, :validate => true
139 attributes :email, :validate => /\A([\w\.%\+\-]+)@([\w\-]+\.)+([\w]{2,})\z/i
140 attributes :type, :validate => ["General", "Interface bug"]
141 attributes :message
142 attributes :screenshot, :attachment => true, :validate => :interface_bug?
143 attributes :nickname, :captcha => true
144
145 def interface_bug?
146 if type == 'Interface bug' && screenshot.nil?
147 self.errors.add(:screenshot, "can't be blank on interface bugs")
148 end
149 end
150 end
151
152 c = ContactForm.new(:nickname => 'not_blank', :email => 'your@email.com', :name => 'José')
153 c.valid? #=> true
154 c.spam? #=> true (raises an error in development, to remember you to hide it)
155 c.deliver #=> false (just delivers if is not a spam and is valid, raises an error in development)
156
157 c = ContactForm.new(:email => 'invalid')
158 c.valid? #=> false
159 c.errors.inspect #=> { :name => :blank, :email => :invalid }
160 c.errors.full_messages #=> [ "Name can't be blank", "Email is invalid" ]
161
162 c = ContactForm.new(:name => 'José', :email => 'your@email.com')
163 c.deliver
164 ```
165
166 ### append(*methods)
167
168 **MailForm** also makes easy to append request information from client to the sent
169 mail. You just have to do:
170
171 ```ruby
172 class ContactForm < MailForm::Base
173 append :remote_ip, :user_agent, :session
174 # ...
175 end
176 ```
177
178 And in your controller:
179
180 ```ruby
181 @contact_form = ContactForm.new(params[:contact_form])
182 @contact_form.request = request
183 ```
184
185 The remote ip, user agent and session will be sent in the e-mail in a
186 request information session. You can give to append any method that the
187 request object responds to.
188
189 ## I18n
190
191 I18n in **MailForm** works like in ActiveRecord, so all models, attributes and messages
192 can be used with localized. Below is an I18n file example file:
193
194 ```ruby
195 mail_form:
196 models:
197 contact_form: "Your site contact form"
198 attributes:
199 contact_form:
200 email: "E-mail"
201 telephone: "Telephone number"
202 message: "Sent message"
203 request:
204 title: "Technical information about the user"
205 remote_ip: "IP Address"
206 user_agent: "Browser"
207 ```
208
f5db6e9 @oponder Explain how to customize the email template
oponder authored
209 ## Custom e-mail template
210
211 To customize the e-mail template that is used create a file called contact.erb in app/views/mail_form.
212 Take a look at lib/mail_form/views/mail_form/contact.erb in this repo to see how the default template works.
213
b48ac73 @nashby markdownify README
nashby authored
214 ## Maintainers
215
216 * José Valim - http://github.com/josevalim
217 * Carlos Antonio - http://github.com/carlosantoniodasilva
218
219 ## Contributors
220
221 * Andrew Timberlake - http://github.com/andrewtimberlake
222
223 ## Bugs and Feedback
224
225 If you discover any bug, please use github issues tracker.
226
7cee02e @carlosantoniodasilva Bump copyright year [ci skip]
carlosantoniodasilva authored
227 Copyright (c) 2009-2015 Plataformatec http://plataformatec.com.br/
Something went wrong with that request. Please try again.