Categories
ruby ruby on rails

A treatise on mailboxer ruby gem

Mailbox Gem

Mailboxer gem adds messaging capability to your models.By far of all messaging gems we have found this one easy to implement / add to your models with good documentation.

Mailboxer Installation

In you rails application add

gem "mailboxer", "~> 0.9.0"

to your Gemfile and run bundle install to install it.

Now go to rails application directory and run to generate the necessary migrations and then migrate the changes to your database

rails g mailboxer:install
rake db:migrate

Configuring Maiboxer

In rails you can create an intializer called mailboxer.rb in folder /config/intializer and modify the default behaviour of mailboxer. An example intializer. In our setup we are not interested in user emails. so we have just disabled it. Mailboxer automatically generates a initializer for you can go and change the default settings.

Mailboxer.setup do |config|

  #Configures if you applications uses or no the email sending for Notifications and Messages
  config.uses_emails = false

  #Configures the default from for the email sent for Messages and Notifications of Mailboxer
  config.default_from = "no-reply@mailboxer.com"

  #Configures the methods needed by mailboxer
  # These methods must be implemented in the model which will be using mailboxer
  config.email_method = :email # This method is needed only if you are going to send an email for each converstion / replies
  config.name_method = :name # This method is needed if you want to user mailboxer

  #Configures if you use or not a search engine and wich one are you using
  #Supported enignes: [:solr,:sphinx]
  config.search_enabled = false
  config.search_engine = :solr
end

Preparing the Model

In your user model add acts_as_messageable and implement the method name as shown below

class User < ActiveRecord::Base
  attr_accessible :email, :first_name, :last_name
  acts_as_messageable

  # Returns the name of the user
  def name
   return "#{first_name} #{last_name}"
  end
end

Basic Messaging

In mailboxer when an user send message to another user, a conversation is started. So there will be a notification is created with the content of the message and a receipt of notification is add to sent box of the sending user and a receipt of notification is added to the inbox of receiving user.

mailboxer flow (1)

To send a message to user2 from user1

user1.send_message(user2, body_of_the_message, subject_of_the_message)

#sending a message

To send message to multiple users use (just pass and array of recipients to send_message function.

user1.send_message([user2, user3, user4], body_of_the_message, subject_of_the_message)

To reply to the message

#message reply
user2.reply_to_conversation(conversation, "Reply body")

#Reply to all in the conversation (if the conversation involves more than two users )
user2.reply_to_all(receipt, "Reply body")

#To reply to the message sender
user2.reply_to_sender(receipt, "Reply body")

Retrieve all messages of the user

#user1 wants to retrieve all his conversations
user1.mailbox.conversations

#user1 wants to retrieve his inbox
user1.mailbox.inbox

#user1 wants to get unread messages in inbox
user1.mailbox.inbox(:unread => true)

#user1 wants to get all the read messages in inbox
user1.mailbox.inbox - user1.mailbox.inbox(:unread => true)

#user1 wants to retrieve his sent conversations
user1.mailbox.sentbox

#user1 wants to retrieve his trashed conversations
user1.mailbox.trash

To read the contents of a conversation user get the receipts of the message for him and reads the messages. The following snippet gets the messages in a conversation in reverse chronological order.

#user gets the last conversation (chronologically, the first in the inbox)
conversation = user1.mailbox.inbox.first

#user gets it receipts chronologically ordered.
receipts = conversation.receipts_for user1

#using the receipts (i.e. in the view)
receipts.each do |receipt|
  message = receipt.message
  read = receipt.is_unread?
end

Misc stuff

#To get the originator of the conversation
conversation.originator

#To get all participants of the conversation
conversation.particpants

#To get the first messsage of the conversation
conversation.original_message

#To get no of messages in the conversation
conversation.count_messages

#to mark a conversation as read by the participant (example user2)
user2.mark_as_read(conversation)

To change the views of email messages

#run this command
rails g mailboxer:views

the views are added to your app/views folders so you can edit them.

Thats all for now folks. If you need more info just post in the comments i will try to answer

Update: Follow up tutorial on how to customize mailboxer views

References

  1. https://github.com/ging/mailboxer
  2. http://www.rubydoc.info/github/ging/mailboxer/frames