Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 318 lines (237 sloc) 11.621 kb
a3ed4a4 @jcoyne Update travis badge for mailboxer/mailboxer [ci skip]
jcoyne authored
1 # Mailboxer [![Build Status](https://travis-ci.org/mailboxer/mailboxer.svg?branch=master)](https://travis-ci.org/mailboxer/mailboxer) [![Gem Version](https://badge.fury.io/rb/mailboxer.png)](http://badge.fury.io/rb/mailboxer) [![](https://gemnasium.com/ging/mailboxer.png)](https://gemnasium.com/ging/mailboxer)
e494420 updated readme to markdown format
Jeff Dickey authored
2
328b7a4 @trappist Fix up the README a bit
trappist authored
3 This project is based on the need for a private message system for [ging
e494420 updated readme to markdown format
Jeff Dickey authored
4 / social\_stream](https://github.com/ging/social_stream). Instead of creating our core message system heavily
328b7a4 @trappist Fix up the README a bit
trappist authored
5 dependent on our development, we are trying to implement a generic and
e494420 updated readme to markdown format
Jeff Dickey authored
6 potent messaging gem.
7
328b7a4 @trappist Fix up the README a bit
trappist authored
8 After looking for a good gem to use we noticed the lack of messaging gems
9 and functionality in them. Mailboxer tries to fill this void delivering
10 a powerful and flexible message system. It supports the use of
11 conversations with two or more participants, sending notifications to
12 recipients (intended to be used as system notifications “Your picture has
13 new comments”, “John Doe has updated his document”, etc.), and emailing the
fca4a9d @supremebeing7 add self to contributors
supremebeing7 authored
14 messageable model (if configured to do so). It has a complete implementation
328b7a4 @trappist Fix up the README a bit
trappist authored
15 of a `Mailbox` object for each messageable with `inbox`, `sentbox` and
e494420 updated readme to markdown format
Jeff Dickey authored
16 `trash`.
17
18 The gem is constantly growing and improving its functionality. As it is
19 used with our parallel development [ging / social\_stream](https://github.com/ging/social_stream) we are finding and fixing bugs continously. If you want
20 some functionality not supported yet or marked as TODO, you can create
328b7a4 @trappist Fix up the README a bit
trappist authored
21 an [issue](https://github.com/ging/mailboxer/issues) to ask for it. It will be great feedback for us, and we
22 will know what you may find useful in the gem.
e494420 updated readme to markdown format
Jeff Dickey authored
23
24 Mailboxer was born from the great, but outdated, code from [lpsergi /
2a8d8d4 minor readme tweaks
Jeff Dickey authored
25 acts*as*messageable](https://github.com/psergi/acts_as_messageable).
e494420 updated readme to markdown format
Jeff Dickey authored
26
328b7a4 @trappist Fix up the README a bit
trappist authored
27 We are now working to make exhaustive documentation and some wiki
28 pages in order to make it even easier to use the gem to its full potencial.
e494420 updated readme to markdown format
Jeff Dickey authored
29 Please, give us some time if you find something missing or [ask for
0180bb0 @searsaw Added Gitter account info to README
searsaw authored
30 it](https://github.com/ging/mailboxer/issues). You can also find us on the [Gitter room for this repo](https://gitter.im/mailboxer/mailboxer). Join us there to talk.
e494420 updated readme to markdown format
Jeff Dickey authored
31
32 Installation
33 ------------
34
35 Add to your Gemfile:
36
57ef4c2 @parndt Updated readme formatting
parndt authored
37 ```ruby
38 gem 'mailboxer'
39 ```
e494420 updated readme to markdown format
Jeff Dickey authored
40
41 Then run:
42
57ef4c2 @parndt Updated readme formatting
parndt authored
43 ```sh
5207edc @jezenielzapanta Update README.md
jezenielzapanta authored
44 $ bundle install
57ef4c2 @parndt Updated readme formatting
parndt authored
45 ```
e494420 updated readme to markdown format
Jeff Dickey authored
46
47 Run install script:
48
57ef4c2 @parndt Updated readme formatting
parndt authored
49 ```sh
2a8d8d4 minor readme tweaks
Jeff Dickey authored
50 $ rails g mailboxer:install
57ef4c2 @parndt Updated readme formatting
parndt authored
51 ```
e494420 updated readme to markdown format
Jeff Dickey authored
52
328b7a4 @trappist Fix up the README a bit
trappist authored
53 And don't forget to migrate your database:
e494420 updated readme to markdown format
Jeff Dickey authored
54
57ef4c2 @parndt Updated readme formatting
parndt authored
55 ```sh
2a8d8d4 minor readme tweaks
Jeff Dickey authored
56 $ rake db:migrate
57ef4c2 @parndt Updated readme formatting
parndt authored
57 ```
e494420 updated readme to markdown format
Jeff Dickey authored
58
4384b72 @supremebeing7 add views generator instructions to README
supremebeing7 authored
59 You can also generate email views:
60
61 ```sh
62 $ rails g mailboxer:views
63 ```
64
7db4535 @coblej Add upgrade instructions related to namespacing compatibility
coblej authored
65 Upgrading
66 ---------
67
41d4b0b @dstosik Complete README's 0.11 > 0.12 upgrade process.
dstosik authored
68 If upgrading from 0.11.0 to 0.12.0, run the following generators:
7db4535 @coblej Add upgrade instructions related to namespacing compatibility
coblej authored
69
70 ```sh
71 $ rails generate mailboxer:namespacing_compatibility
3f4d23d @dstosik Fix rails generate syntax in README. (see #281)
dstosik authored
72 $ rails generate mailboxer:install -s
7db4535 @coblej Add upgrade instructions related to namespacing compatibility
coblej authored
73 ```
74
75 Then, migrate your database:
76
77 ```sh
78 $ rake db:migrate
79 ```
80
087571a added missing content
Jeff Dickey authored
81 ## Requirements & Settings
82
83 ### Emails
84
328b7a4 @trappist Fix up the README a bit
trappist authored
85 We are now adding support for sending emails when a Notification or a Message is sent to one or more recipients. You should modify the mailboxer initializer (/config/initializer/mailboxer.rb) to edit these settings.
087571a added missing content
Jeff Dickey authored
86
57ef4c2 @parndt Updated readme formatting
parndt authored
87 ```ruby
087571a added missing content
Jeff Dickey authored
88 Mailboxer.setup do |config|
328b7a4 @trappist Fix up the README a bit
trappist authored
89 #Enables or disables email sending for Notifications and Messages
fca4a9d @supremebeing7 add self to contributors
supremebeing7 authored
90 config.uses_emails = true
328b7a4 @trappist Fix up the README a bit
trappist authored
91 #Configures the default `from` address for the email sent for Messages and Notifications of Mailboxer
087571a added missing content
Jeff Dickey authored
92 config.default_from = "no-reply@dit.upm.es"
93 ...
94 end
57ef4c2 @parndt Updated readme formatting
parndt authored
95 ```
087571a added missing content
Jeff Dickey authored
96
328b7a4 @trappist Fix up the README a bit
trappist authored
97 You can change the way in which emails are delivered by specifying a custom implementation of notification and message mailers
1dc688b @amaierhofer added configurable_mailer module
amaierhofer authored
98
57ef4c2 @parndt Updated readme formatting
parndt authored
99 ```ruby
1dc688b @amaierhofer added configurable_mailer module
amaierhofer authored
100 Mailboxer.setup do |config|
101 config.notification_mailer = CustomNotificationMailer
102 config.message_mailer = CustomMessageMailer
103 ...
104 end
57ef4c2 @parndt Updated readme formatting
parndt authored
105 ```
1dc688b @amaierhofer added configurable_mailer module
amaierhofer authored
106
087571a added missing content
Jeff Dickey authored
107 ### User identities
e494420 updated readme to markdown format
Jeff Dickey authored
108
328b7a4 @trappist Fix up the README a bit
trappist authored
109 Users must have an identity defined by a `name` and an `email`. We must ensure that Messageable models have some specific methods. These methods are:
e494420 updated readme to markdown format
Jeff Dickey authored
110
57ef4c2 @parndt Updated readme formatting
parndt authored
111 ```ruby
e494420 updated readme to markdown format
Jeff Dickey authored
112 #Returning any kind of identification you want for the model
113 def name
114 return "You should add method :name in your Messageable model"
115 end
57ef4c2 @parndt Updated readme formatting
parndt authored
116 ```
087571a added missing content
Jeff Dickey authored
117
57ef4c2 @parndt Updated readme formatting
parndt authored
118 ```ruby
e494420 updated readme to markdown format
Jeff Dickey authored
119 #Returning the email address of the model if an email should be sent for this object (Message or Notification).
120 #If no mail has to be sent, return nil.
121 def mailboxer_email(object)
122 #Check if an email should be sent for that object
123 #if true
124 return "define_email@on_your.model"
125 #if false
126 #return nil
127 end
57ef4c2 @parndt Updated readme formatting
parndt authored
128 ```
e494420 updated readme to markdown format
Jeff Dickey authored
129
087571a added missing content
Jeff Dickey authored
130 These names are explicit enough to avoid colliding with other methods, but as long as you need to change them you can do it by using mailboxer initializer (/config/initializer/mailboxer.rb). Just add or uncomment the following lines:
e494420 updated readme to markdown format
Jeff Dickey authored
131
57ef4c2 @parndt Updated readme formatting
parndt authored
132 ```ruby
087571a added missing content
Jeff Dickey authored
133 Mailboxer.setup do |config|
134 # ...
135 #Configures the methods needed by mailboxer
136 config.email_method = :mailboxer_email
137 config.name_method = :name
138 # ...
139 end
57ef4c2 @parndt Updated readme formatting
parndt authored
140 ```
e494420 updated readme to markdown format
Jeff Dickey authored
141
142 You may change whatever you want or need. For example:
143
57ef4c2 @parndt Updated readme formatting
parndt authored
144 ```ruby
d81475d @jasdeepsingh fixed a small typo in the README.md
jasdeepsingh authored
145 config.email_method = :notification_email
e494420 updated readme to markdown format
Jeff Dickey authored
146 config.name_method = :display_name
57ef4c2 @parndt Updated readme formatting
parndt authored
147 ```
e494420 updated readme to markdown format
Jeff Dickey authored
148
149 Will use the method `notification_email(object)` instead of `mailboxer_email(object)` and `display_name` for `name`.
150
328b7a4 @trappist Fix up the README a bit
trappist authored
151 Using default or custom method names, if your model doesn't implement them, Mailboxer will use dummy methods so as to notify you of missing methods rather than crashing.
e494420 updated readme to markdown format
Jeff Dickey authored
152
153 ## Preparing your models
154
155 In your model:
156
57ef4c2 @parndt Updated readme formatting
parndt authored
157 ```ruby
e494420 updated readme to markdown format
Jeff Dickey authored
158 class User < ActiveRecord::Base
159 acts_as_messageable
160 end
57ef4c2 @parndt Updated readme formatting
parndt authored
161 ```
e494420 updated readme to markdown format
Jeff Dickey authored
162
328b7a4 @trappist Fix up the README a bit
trappist authored
163 You are not limited to the User model. You can use Mailboxer in any other model and use it in serveral different models. If you have ducks and cylons in your application and you want to exchange messages as if they were the same, just add `acts_as_messageable` to each one and you will be able to send duck-duck, duck-cylon, cylon-duck and cylon-cylon messages. Of course, you can extend it for as many classes as you need.
e494420 updated readme to markdown format
Jeff Dickey authored
164
165 Example:
166
57ef4c2 @parndt Updated readme formatting
parndt authored
167 ```ruby
e494420 updated readme to markdown format
Jeff Dickey authored
168 class Duck < ActiveRecord::Base
169 acts_as_messageable
170 end
57ef4c2 @parndt Updated readme formatting
parndt authored
171 ```
e494420 updated readme to markdown format
Jeff Dickey authored
172
57ef4c2 @parndt Updated readme formatting
parndt authored
173 ```ruby
e494420 updated readme to markdown format
Jeff Dickey authored
174 class Cylon < ActiveRecord::Base
175 acts_as_messageable
176 end
57ef4c2 @parndt Updated readme formatting
parndt authored
177 ```
e494420 updated readme to markdown format
Jeff Dickey authored
178
087571a added missing content
Jeff Dickey authored
179 ## Mailboxer API
180
52b6ab4 @rafaelgg Bump version, update README.
rafaelgg authored
181 ### Warning for version 0.8.0
182 Version 0.8.0 sees `Messageable#read` and `Messageable#unread` renamed to `mark_as_(un)read`, and `Receipt#read` and `Receipt#unread` to `is_(un)read`. This may break existing applications, but `read` is a reserved name for Active Record, and the best pratice in this case is simply avoid using it.
183
3678001 Fixed headers
Jeff Dickey authored
184 ### How can I send a message?
087571a added missing content
Jeff Dickey authored
185
57ef4c2 @parndt Updated readme formatting
parndt authored
186 ```ruby
187 #alfa wants to send a message to beta
188 alfa.send_message(beta, "Body", "subject")
189 ```
087571a added missing content
Jeff Dickey authored
190
3678001 Fixed headers
Jeff Dickey authored
191 ### How can I reply a message?
087571a added missing content
Jeff Dickey authored
192
57ef4c2 @parndt Updated readme formatting
parndt authored
193 ```ruby
194 #alfa wants to reply to all in a conversation
195 #using a receipt
196 alfa.reply_to_all(receipt, "Reply body")
087571a added missing content
Jeff Dickey authored
197
57ef4c2 @parndt Updated readme formatting
parndt authored
198 #using a conversation
199 alfa.reply_to_conversation(conversation, "Reply body")
200 ```
201
202 ```ruby
203 #alfa wants to reply to the sender of a message (and ONLY the sender)
204 #using a receipt
205 alfa.reply_to_sender(receipt, "Reply body")
206 ```
087571a added missing content
Jeff Dickey authored
207
3678001 Fixed headers
Jeff Dickey authored
208 ### How can I retrieve my conversations?
087571a added missing content
Jeff Dickey authored
209
57ef4c2 @parndt Updated readme formatting
parndt authored
210 ```ruby
211 #alfa wants to retrieve all his conversations
212 alfa.mailbox.conversations
213
214 #A wants to retrieve his inbox
215 alfa.mailbox.inbox
216
217 #A wants to retrieve his sent conversations
218 alfa.mailbox.sentbox
219
220 #alfa wants to retrieve his trashed conversations
221 alfa.mailbox.trash
222 ```
087571a added missing content
Jeff Dickey authored
223
46c31ea @MhdAljuboori Added delete message feature
MhdAljuboori authored
224 ### How can I delete a message from trash?
225
226 ```ruby
227 #delete conversations forever for one receipt (still in database)
228 receipt.mark_as_deleted
229
230 #you can mark conversation as deleted for one participant
231 conversation.mark_as_deleted participant
232
233 #Mark the object as deleted for messageable
234 #Object can be:
235 #* A Receipt
236 #* A Conversation
237 #* A Notification
238 #* A Message
239 #* An array with any of them
240 alfa.mark_as_deleted conversation
241 ```
242
3678001 Fixed headers
Jeff Dickey authored
243 ### How can I paginate conversations?
087571a added missing content
Jeff Dickey authored
244
8a5b5ae @Roendal Fixing README
Roendal authored
245 You can use Kaminari to paginate the conversations as normal. Please, make sure you use the last version as mailboxer uses `select('DISTINCT conversations.*')` which was not respected before Kaminari 0.12.4 according to its changelog. Working corretly on Kaminari 0.13.0.
2cc659e @Roendal Fixing readme
Roendal authored
246
57ef4c2 @parndt Updated readme formatting
parndt authored
247 ```ruby
248 #Paginating all conversations using :page parameter and 9 per page
249 conversations = alfa.mailbox.conversations.page(params[:page]).per(9)
250
251 #Paginating received conversations using :page parameter and 9 per page
252 conversations = alfa.mailbox.inbox.page(params[:page]).per(9)
fca4a9d @supremebeing7 add self to contributors
supremebeing7 authored
253
57ef4c2 @parndt Updated readme formatting
parndt authored
254 #Paginating sent conversations using :page parameter and 9 per page
255 conversations = alfa.mailbox.sentbox.page(params[:page]).per(9)
256
257 #Paginating trashed conversations using :page parameter and 9 per page
fca4a9d @supremebeing7 add self to contributors
supremebeing7 authored
258 conversations = alfa.mailbox.trash.page(params[:page]).per(9)
57ef4c2 @parndt Updated readme formatting
parndt authored
259 ```
087571a added missing content
Jeff Dickey authored
260
3678001 Fixed headers
Jeff Dickey authored
261 ### How can I read the messages of a conversation?
087571a added missing content
Jeff Dickey authored
262
328b7a4 @trappist Fix up the README a bit
trappist authored
263 As a messageable, what you receive are receipts, which are associated with the message itself. You should retrieve your receipts for the conversation a get the message associated with them.
087571a added missing content
Jeff Dickey authored
264
265 This is done this way because receipts save the information about the relation between messageable and the messages: is it read?, is it trashed?, etc.
266
57ef4c2 @parndt Updated readme formatting
parndt authored
267 ```ruby
268 #alfa gets the last conversation (chronologically, the first in the inbox)
269 conversation = alfa.mailbox.inbox.first
270
271 #alfa gets it receipts chronologically ordered.
272 receipts = conversation.receipts_for alfa
273
274 #using the receipts (i.e. in the view)
275 receipts.each do |receipt|
276 ...
277 message = receipt.message
278 read = receipt.is_unread? #or message.is_unread?(alfa)
279 ...
280 end
281 ```
e494420 updated readme to markdown format
Jeff Dickey authored
282
328b7a4 @trappist Fix up the README a bit
trappist authored
283 You can take a look at the full documentation for Mailboxer in [rubydoc.info](http://rubydoc.info/gems/mailboxer/frames).
e494420 updated readme to markdown format
Jeff Dickey authored
284
e1203c4 @Roendal Update README.md
Roendal authored
285 ## Do you want to test Mailboxer?
286
a96e222 @Roendal Typo fix
Roendal authored
287 Thanks to [Roman Kushnir (@RKushnir)](https://github.com/RKushnir/) you can test Mailboxer with this [sample app](https://github.com/RKushnir/mailboxer-app).
e1203c4 @Roendal Update README.md
Roendal authored
288
916680a Added link to rails-messaging
Jeff Dickey authored
289 ## I need a GUI!
8a5b5ae @Roendal Fixing README
Roendal authored
290
328b7a4 @trappist Fix up the README a bit
trappist authored
291 If you need a GUI you should take a look a these links:
8a5b5ae @Roendal Fixing README
Roendal authored
292
3cb2e39 @Roendal Linking GUI wiki on README. Fixes #16.
Roendal authored
293 * The [rails-messaging](https://github.com/frodefi/rails-messaging) project.
294 * The wiki page [GUI Example on a real application](https://github.com/ging/mailboxer/wiki/GUI-Example-on-a-real-application).
916680a Added link to rails-messaging
Jeff Dickey authored
295
40c26a5 Added contributors
Jeff Dickey authored
296 ## Contributors
25140bf Added bullets to contributors
Jeff Dickey authored
297 * [Roendal](https://github.com/ging/mailboxer/commits/master?author=Roendal) (Eduardo Casanova)
80c59b2 @Roendal Typo fix
Roendal authored
298 * [dickeyxxx](https://github.com/ging/mailboxer/commits/master?author=dickeyxxx) (Jeff Dickey)
1bdcaa2 @Roendal Updating Contributors section in README
Roendal authored
299 * [RKushnir](https://github.com/ging/mailboxer/commits/master?author=RKushnir) (Roman Kushnir)
5d6e683 @Roendal Adding @amaierhofer to contributors
Roendal authored
300 * [amaierhofer](https://github.com/ging/mailboxer/commits/master?author=amaierhofer) (Andreas Maierhofer)
25140bf Added bullets to contributors
Jeff Dickey authored
301 * [tonydewan](https://github.com/ging/mailboxer/commits/master?author=tonydewan) (Tony Dewan)
302 * [plentz](https://github.com/ging/mailboxer/commits/master?author=plentz) (Diego Plentz)
1dc688b @amaierhofer added configurable_mailer module
amaierhofer authored
303 * [laserlemon](https://github.com/ging/mailboxer/commits/master?author=laserlemon) (Steve Richert)
6e83765 @Roendal Adding @daveworth to contributors
Roendal authored
304 * [daveworth](https://github.com/ging/mailboxer/commits/master?author=daveworth) (Dave Worth)
52b6ab4 @rafaelgg Bump version, update README.
rafaelgg authored
305 * [rafaelgg](https://github.com/ging/mailboxer/commits/master?author=rafaelgg) (Rafael Garcia)
8142b12 @fabianoalmeida Updating contributors and fixing #104 issue
fabianoalmeida authored
306 * [joshblour](https://github.com/ging/mailboxer/commits/master?author=joshblour) (joshblour)
307 * [iamdeuterium](https://github.com/ging/mailboxer/commits/master?author=iamdeuterium) (iamdeuterium)
308 * [daveworth](https://github.com/ging/mailboxer/commits/master?author=daveworth) (Dave Worth)
309 * [parndt](https://github.com/ging/mailboxer/commits/master?author=parndt) (Philip Arndt)
310 * [atd](https://github.com/ging/mailboxer/commits/master?author=atd) (Antonio Tapiador)
311 * [mobilutz](https://github.com/ging/mailboxer/commits/master?author=mobilutz) (Lutz)
312 * [bennick](https://github.com/ging/mailboxer/commits/master?author=bennick) (Ryan Bennick)
313 * [rjst](https://github.com/ging/mailboxer/commits/master?author=rjst) (Ricardo Trindade)
314 * [fabianoalmeida](https://github.com/ging/mailboxer/commits/master?author=fabianoalmeida) (Fabiano Almeida)
fca4a9d @supremebeing7 add self to contributors
supremebeing7 authored
315 * [supremebeing7](https://github.com/ging/mailboxer/commits/master?author=supremebeing7) (Mark J. Lehman)
9c8d0bd @searsaw Updated README with other contributors
searsaw authored
316 * [searsaw](https://github.com/mailboxer/mailboxer/commits/master?author=searsaw) (Alex Sears)
d81475d @jasdeepsingh fixed a small typo in the README.md
jasdeepsingh authored
317 * [joshblour](https://github.com/mailboxer/mailboxer/commits/master?author=joshblour) (Yonah Forst)
Something went wrong with that request. Please try again.