mailboxer 0.7.0 → 0.8.0

data/README.md

@@ -1,4 +1,4 @@
-# Mailboxer 0.7.x [![](https://secure.travis-ci.org/ging/mailboxer.png)](http://travis-ci.org/ging/mailboxer) [![](https://gemnasium.com/ging/mailboxer.png)](https://gemnasium.com/ging/mailboxer)
+# Mailboxer 0.8.x [![](https://secure.travis-ci.org/ging/mailboxer.png)](http://travis-ci.org/ging/mailboxer) [![](https://gemnasium.com/ging/mailboxer.png)](https://gemnasium.com/ging/mailboxer)
 
 This project is based on the need of a private message system for [ging
 / social\_stream](https://github.com/ging/social_stream). Instead of creating our core message system heavily
@@ -34,27 +34,27 @@ Installation
 
 Add to your Gemfile:
 
-````
-gem ‘mailboxer’
-````
+```ruby
+gem 'mailboxer'
+```
 
 Then run:
 
-````
+```sh
 $ bundle update
-````
+```
 
 Run install script:
 
-````
+```sh
 $ rails g mailboxer:install
-````
+```
 
 And don't forget to migrate you database:
 
-````
+```sh
 $ rake db:migrate
-````
+```
 
 ## Requirements & Settings
 
@@ -62,7 +62,7 @@ $ rake db:migrate
 
 We are now adding support for sending emails when a Notification or a Message is sent to one o more recipients. You should modify mailboxer initializer (/config/initializer/mailboxer.rb) to edit this settings.
 
-````ruby
+```ruby
 Mailboxer.setup do |config|
   #Configures if you applications uses or no the email sending for Notifications and Messages
   config.uses_emails = true  
@@ -70,30 +70,30 @@ Mailboxer.setup do |config|
   config.default_from = "no-reply@dit.upm.es"
   ...
 end
-````
+```
 
 You can change the way in which emails are delivered by specifying a custom implementation for notification and message mailer 
 
-````ruby
+```ruby
 Mailboxer.setup do |config|
   config.notification_mailer = CustomNotificationMailer
   config.message_mailer = CustomMessageMailer
   ...
 end
-````
+```
 
 ### User identities
 
 Users must have an identity defined by a `name` and an `email`. We must assure that Messageable models have some specific methods. These methods are:
 
-````ruby
+```ruby
 #Returning any kind of identification you want for the model
 def name
   return "You should add method :name in your Messageable model"
 end
-````
+```
 
-````ruby
+```ruby
 #Returning the email address of the model if an email should be sent for this object (Message or Notification).
 #If no mail has to be sent, return nil.
 def mailboxer_email(object)
@@ -103,11 +103,11 @@ def mailboxer_email(object)
   #if false
   #return nil
 end
-````
+```
 
 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:
 
-````ruby
+```ruby
 Mailboxer.setup do |config|
   # ...
   #Configures the methods needed by mailboxer
@@ -115,14 +115,14 @@ Mailboxer.setup do |config|
   config.name_method = :name
   # ...
 end
-````
+```
 
 You may change whatever you want or need. For example:
 
-````ruby
+```ruby
 config.email_method = :notifications_email
 config.name_method = :display_name
-````
+```
 
 Will use the method `notification_email(object)` instead of `mailboxer_email(object)` and `display_name` for `name`.
 
@@ -132,80 +132,90 @@ Using default or custom method names, if your model doesn't implement them, Mail
 
 In your model:
 
-````ruby
+```ruby
 class User < ActiveRecord::Base
   acts_as_messageable
 end
-````
+```
 
 You are not limited to 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 interchange messages as if they where the same, just use act_as_messageable in 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 clases as you need.
 
 Example:
 
-````ruby
+```ruby
 class Duck < ActiveRecord::Base
   acts_as_messageable
 end
-````
+```
 
-````ruby
+```ruby
 class Cylon < ActiveRecord::Base
   acts_as_messageable
 end
-````
+```
 
 ## Mailboxer API
 
+### Warning for version 0.8.0
+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.
+
 ### How can I send a message?
 
-````ruby
-  #alfa wants to send a message to beta
-  alfa.send_message(beta, "Body", "subject")
-````
+```ruby
+#alfa wants to send a message to beta
+alfa.send_message(beta, "Body", "subject")
+```
 
 ### How can I reply a message?
 
-````ruby
-  #alfa wants to reply to all in a conversation
-  #using a receipt
-  alfa.reply_to_all(receipt, "Reply body")
-  #using a conversation
-  alfa.reply_to_conversation(conversation, "Reply body")
-````
+```ruby
+#alfa wants to reply to all in a conversation
+#using a receipt
+alfa.reply_to_all(receipt, "Reply body")
+
+#using a conversation
+alfa.reply_to_conversation(conversation, "Reply body")
+```
 
-````ruby
-  #alfa wants to reply to the sender of a message (and ONLY the sender)
-  #using a receipt
-  alfa.reply_to_sender(receipt, "Reply body")
-````
+```ruby
+#alfa wants to reply to the sender of a message (and ONLY the sender)
+#using a receipt
+alfa.reply_to_sender(receipt, "Reply body")
+```
 
 ### How can I retrieve my conversations?
 
-````ruby
-  #alfa wants to retrieve all his conversations
-  alfa.mailbox.conversations
-  #A wants to retrieve his inbox
-  alfa.mailbox.inbox
-  #A wants to retrieve his sent conversations
-  alfa.mailbox.sentbox
-  #alfa wants to retrieve his trashed conversations
-  alfa.mailbox.trash
-````
+```ruby
+#alfa wants to retrieve all his conversations
+alfa.mailbox.conversations
+
+#A wants to retrieve his inbox
+alfa.mailbox.inbox
+
+#A wants to retrieve his sent conversations
+alfa.mailbox.sentbox
+
+#alfa wants to retrieve his trashed conversations
+alfa.mailbox.trash
+```
 
 ### How can I paginate conversations?
 
 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.
 
-````ruby
-  #Paginating all conversations using :page parameter and 9 per page
-  conversations = alfa.mailbox.conversations.page(params[:page]).per(9)
-  #Paginating received conversations using :page parameter and 9 per page
-  conversations = alfa.mailbox.inbox.page(params[:page]).per(9)
-  #Paginating sent conversations using :page parameter and 9 per page
-  conversations = alfa.mailbox.sentbox.page(params[:page]).per(9)
-  #Paginating trashed conversations using :page parameter and 9 per page
-  conversations = alfa.mailbox.trash.page(params[:page]).per(9) 
-````
+```ruby
+#Paginating all conversations using :page parameter and 9 per page
+conversations = alfa.mailbox.conversations.page(params[:page]).per(9)
+
+#Paginating received conversations using :page parameter and 9 per page
+conversations = alfa.mailbox.inbox.page(params[:page]).per(9)
+  
+#Paginating sent conversations using :page parameter and 9 per page
+conversations = alfa.mailbox.sentbox.page(params[:page]).per(9)
+
+#Paginating trashed conversations using :page parameter and 9 per page
+conversations = alfa.mailbox.trash.page(params[:page]).per(9) 
+```
 
 ### How can I read the messages of a conversation?
 
@@ -213,19 +223,21 @@ As a messageable, what you receive receipts wich are linked with the message its
 
 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.
 
-````ruby
-  #alfa gets the last conversation (chronologically, the first in the inbox)
-  conversation = alfa.mailbox.inbox.first
-  #alfa gets it receipts chronologically ordered.
-  receipts = conversation.receipts_for alfa
-  #using the receipts (i.e. in the view)
-  receipts.each do |receipt|
-    ...
-    message = receipt.message
-    read = receipt.is_unread? #or message.is_unread?(alfa)
-    ...
-  end
-````
+```ruby
+#alfa gets the last conversation (chronologically, the first in the inbox)
+conversation = alfa.mailbox.inbox.first
+
+#alfa gets it receipts chronologically ordered.
+receipts = conversation.receipts_for alfa
+
+#using the receipts (i.e. in the view)
+receipts.each do |receipt|
+  ...
+  message = receipt.message
+  read = receipt.is_unread? #or message.is_unread?(alfa)
+  ...
+end
+```
 
 You can take a look at the full documentation of Mailboxer in [rubydoc.info](http://rubydoc.info/gems/mailboxer/frames).
 
@@ -249,3 +261,4 @@ If you need a GUI you should take a look a this links:
 * [plentz](https://github.com/ging/mailboxer/commits/master?author=plentz) (Diego Plentz)
 * [laserlemon](https://github.com/ging/mailboxer/commits/master?author=laserlemon) (Steve Richert)
 * [daveworth](https://github.com/ging/mailboxer/commits/master?author=daveworth) (Dave Worth)
+* [rafaelgg](https://github.com/ging/mailboxer/commits/master?author=rafaelgg) (Rafael Garcia)

data/app/models/conversation.rb

@@ -24,7 +24,7 @@ class Conversation < ActiveRecord::Base
     participant(participant).merge(Receipt.trash)
   }
   scope :unread,  lambda {|participant|
-    participant(participant).merge(Receipt.unread)
+    participant(participant).merge(Receipt.is_unread)
   }
 
   #Mark the conversation as read for one of the participants
@@ -125,7 +125,7 @@ class Conversation < ActiveRecord::Base
   #Returns true if the participant has at least one unread message of the conversation
 	def is_unread?(participant)
 		return false if participant.nil?
-		return self.receipts_for(participant).not_trash.unread.count!=0
+		return self.receipts_for(participant).not_trash.is_unread.count!=0
 	end
 
 	protected

data/app/models/message.rb

@@ -30,7 +30,7 @@ class Message < Notification
     self.recipients.each do |r|
       msg_receipt = Receipt.new
       msg_receipt.notification = self
-      msg_receipt.read = false
+      msg_receipt.is_read = false
       msg_receipt.receiver = r
       msg_receipt.mailbox_type = "inbox"
       temp_receipts << msg_receipt
@@ -38,7 +38,7 @@ class Message < Notification
     #Sender receipt
     sender_receipt = Receipt.new
     sender_receipt.notification = self
-    sender_receipt.read = true
+    sender_receipt.is_read = true
     sender_receipt.receiver = self.sender
     sender_receipt.mailbox_type = "sentbox"
     temp_receipts << sender_receipt

data/app/models/notification.rb

@@ -17,7 +17,7 @@ class Notification < ActiveRecord::Base
     joins(:receipts).where('receipts.trashed' => false)
   }
   scope :unread,  lambda {
-    joins(:receipts).where('receipts.read' => false)
+    joins(:receipts).where('receipts.is_read' => false)
   }
 
   include Concerns::ConfigurableMailer
@@ -26,8 +26,8 @@ class Notification < ActiveRecord::Base
     #Sends a Notification to all the recipients
     def notify_all(recipients,subject,body,obj = nil,sanitize_text = true,notification_code=nil)
       notification = Notification.new({:body => body, :subject => subject})
-      notification.recipients = recipients.is_a?(Array) ? recipients : [recipients]
-      notification.recipients = notification.recipients.uniq
+      notification.recipients = recipients.respond_to?(:each) ? recipients : [recipients]
+      notification.recipients = notification.recipients.uniq if recipients.respond_to?(:uniq)
       notification.notified_object = obj if obj.present?
       notification.notification_code = notification_code if notification_code.present?
       return notification.deliver sanitize_text
@@ -58,7 +58,7 @@ class Notification < ActiveRecord::Base
     self.recipients.each do |r|
       msg_receipt = Receipt.new
       msg_receipt.notification = self
-      msg_receipt.read = false
+      msg_receipt.is_read = false
       msg_receipt.receiver = r
       temp_receipts << msg_receipt
     end
@@ -105,7 +105,7 @@ class Notification < ActiveRecord::Base
   #Returns if the participant have read the Notification
   def is_unread?(participant)
     return false if participant.nil?
-    return !self.receipt_for(participant).first.read
+    return !self.receipt_for(participant).first.is_read
   end
 
   def is_read?(participant)

data/app/models/receipt.rb

@@ -22,19 +22,19 @@ class Receipt < ActiveRecord::Base
   scope :inbox, where(:mailbox_type => "inbox")
   scope :trash, where(:trashed => true)
   scope :not_trash, where(:trashed => false)
-  scope :read, where(:read => true)
-  scope :unread, where(:read => false)
+  scope :is_read, where(:is_read => true)
+  scope :is_unread, where(:is_read => false)
 
   after_validation :remove_duplicate_errors
   class << self
     #Marks all the receipts from the relation as read
     def mark_as_read(options={})
-      update_receipts({:read => true}, options)
+      update_receipts({:is_read => true}, options)
     end
 
     #Marks all the receipts from the relation as unread
     def mark_as_unread(options={})
-      update_receipts({:read => false}, options)
+      update_receipts({:is_read => false}, options)
     end
 
     #Marks all the receipts from the relation as trashed
@@ -78,12 +78,12 @@ class Receipt < ActiveRecord::Base
 
   #Marks the receipt as read
   def mark_as_read
-    update_attributes(:read => true)
+    update_attributes(:is_read => true)
   end
 
   #Marks the receipt as unread
   def mark_as_unread
-    update_attributes(:read => false)
+    update_attributes(:is_read => false)
   end
 
   #Marks the receipt as trashed
@@ -114,7 +114,7 @@ class Receipt < ActiveRecord::Base
 
   #Returns if the participant have read the Notification
   def is_unread?
-    return !self.read
+    return !self.is_read
   end
 
   #Returns if the participant have trashed the Notification

data/db/migrate/20111204163911_add_attachments.rb

@@ -1,5 +1,9 @@
 class AddAttachments < ActiveRecord::Migration
-  def change
+  def self.up
     add_column :notifications, :attachment, :string
   end
+  
+  def self.down
+    remove_column :notifications, :attachment, :string
+  end
 end

data/db/migrate/20120813110712_rename_receipts_read.rb

@@ -0,0 +1,9 @@
+class RenameReceiptsRead < ActiveRecord::Migration
+  def up
+    rename_column :receipts, :read, :is_read
+  end
+
+  def down
+    rename_column :receipts, :is_read, :read
+  end
+end

data/lib/mailboxer/models/messageable.rb

@@ -96,7 +96,7 @@ module Mailboxer
         #* A Notification
         #* A Conversation
         #* An array with any of them
-        def read(obj)
+        def mark_as_read(obj)
           case obj
           when Receipt
             return obj.mark_as_read if obj.receiver == self
@@ -105,9 +105,9 @@ module Mailboxer
           when Conversation
             obj.mark_as_read(self)
           when Array
-            obj.map{ |sub_obj| read(sub_obj) }
+            obj.map{ |sub_obj| mark_as_read(sub_obj) }
           else
-          return nil
+            return nil
           end
         end
 
@@ -119,7 +119,7 @@ module Mailboxer
         #* A Notification
         #* A Conversation
         #* An array with any of them
-        def unread(obj)
+        def mark_as_unread(obj)
           case obj
           when Receipt
             return obj.mark_as_unread if obj.receiver == self
@@ -128,7 +128,7 @@ module Mailboxer
           when Conversation
             obj.mark_as_unread(self)
           when Array
-            obj.map{ |sub_obj| unread(sub_obj) }
+            obj.map{ |sub_obj| mark_as_unread(sub_obj) }
           else
           return nil
           end