ActsAsMessageable

The Acts As Messageable allows communication between the models.

Usage

To use it, add it to your Gemfile:

Rails 3

gem 'acts-as-messageable'

Rails 2

Use this fork Thanks for @openfirmware

gem 'acts-as-messageable', :git => 'git://github.com/openfirmware/acts-as-messageable.git', 
                           :branch => 'rails2.3.11_compatible'

Post installation

rails g acts-as-messageable:migration table_name # default 'messages'
rake db:migrate

Usage

class User < ActiveRecord::Base
  acts_as_messageable :table_name => "table_with_messages", # default 'messages'
                      :required   => :body                  # default [:topic, :body]
                      :class_name => "CustomMessages"       # default "ActsAsMessageable::Message",
                      :dependent  => :destroy               # default :nullify
                      :group_messages => true               # default false
end

Upgrade

Just type once again

rails g acts-as-messageable:migration

And new migrations should be created.

~$ rails g acts-as-messageable:migration
    create  db/migrate/20110811223435_add_recipient_permanent_delete_and_sender_permanent_delete_to_messages.rb

Send message

@alice = User.first
@bob   = User.last

@alice.send_message(@bob, "Message topic", "Hi bob!")
@bob.send_message(@alice, "Re: Message topic", "Hi alice!")

With hash

@alice.send_message(@bob, { :body => "Hash body", :topic => "Hash topic" })

Custom required (validation)

In User model

class User < ActiveRecord::Base
  acts_as_messageable :required => :body
end

With hash

@alice.send_message(@bob, { :body => "Hash body" })

Normal

@alice.send_message(@bob, "body")

Required sequence

class User < ActiveRecord::Base
  acts_as_messageable :required => [:body, :topic]
end

@alice.send_message(@bob, "body", "topic")

First topic

class User < ActiveRecord::Base
  acts_as_messageable :required => [:topic, :body]
end

@alice.send_message(@bob, "topic", "body")

Custom class

You can use your own class that will represent the message object. First of all create custom class

class CustomMessage < ActsAsMessageable::Message
  def capitalize_title
    title.capitalize
  end
end

After that you can sepcify custom class in options.

class User
  acts_as_messageable :class_name => "CustomMessage"
end

From now on, your message has custom class.

@message = @alice.send_message(@bob, "hi!")
@message # => #<CustomMessage:0x000000024b6278>
@message.capitalize_title # => "Hi!"

Conversation

You can get conversation list from messages scope. For example:

@message = @alice.send_message(@bob, "Hello bob!", "How are you?")
@reply_message = @bob.reply_to(@message, "Re: Hello bob!", "I'm fine!")

@alice.received_messages.conversations # => [@reply_message]

should receive list of latest messages in conversations (like in facebook).

To create conversation just reply to a message.

@message = @alice.send_message(@bob, "Hello bob!", "How are you?")
@message.reply("Re: Hello bob!", "I'm fine")

Or with hash

@message.reply(:topic => "Re: Hello bob!", :body => "I'm fine")

Or in old style

@message = @alice.send_message(@bob, "Hello bob!", "How are you?")
@reply_message = @bob.reply_to(@message, "Re: Hello bob!", "I'm fine!")

Get conversation for a specific message

@message.conversation       #=> [@message, @reply_message]
@reply_message.conversation #=> [@message, @reply_message]

Search

You can search text from messages and get the records where match exist. For example:

Search text from messages

records = @alice.messages.search("Search me")  @alice seach text "Search me" from all messages

Inbox

@alice.received_messages

Outbox

@alice.sent_messages

Inbox + Outbox. All messages connected with @alice

@alice.messages

Trash

@alice.deleted_messages

Filters

==========

@alice.messages.are_from(@bob) # all message form @bob
@alice.messages.are_to(@bob) # all message to @bob
@alice.messages.with_id(@id_of_message) # message with id id_of_message
@alice.messages.readed # all readed @alice  messages
@alice.messages.unreaded # all unreaded @alice messages

You can use multiple filters at the same time

@alice.messages.are_from(@bob).are_to(@alice).readed # all message from @bob to @alice and readed
@alice.deleted_messages.are_from(@bob) # all deleted messages from @bob

Read messages

Read message

@message.open # open message
@message.read
@message.mark_as_read

Unread message

@message.close # unread message
@message.mark_as_unread

Delete message

We must know who delete message. That why we use .process method to save context

@message = @alice.send_message(@bob, "Topic", "Body")

@alice.messages.process do |message|
  message.delete # @alice delete message
end

Now we can find message in trash

@alice.deleted_messages #=> [@message]

We can delete the message permanently

@alice.deleted_messages.process do |message|
  message.delete
end

@alice.delete_message #=> []

Message has been deleted permanently

Delete message without context

@alice.delete_message(@message) # @alice delete @message

Restore message

@alice.deleted_messages.process do |m|
  m.restore # @alice restore 'm' message from trash
end

Restore message without context

@alice.restore_message(@message) # @alice restore message from trash

Group message

Enable group messages

class User
  acts_as_messageable :group_messages => true
end

How to join other users's conversation

@message =  @alice.send_message(@bob, :topic => "Helou bob!", :body => "What's up?")
@reply_message = @sukhi.reply_to(@message, "Hi there!", "I would like to join to this conversation!")
@sec_reply_message = @bob.reply_to(@message, "Hi!", "Fine!")
@third_reply_message = @alice.reply_to(@reply_message, "hi!", "no problem")

Know the people involved in conversation

@message.people # will give you participants users object
@message.people # => [@alice, @bob, @sukhi]

Search

Search text from messages

@alice.messages.search("Search me")  @alice seach text "Search me" from all messages

Copyright © 2011-2012 Piotr Niełacny (http://ruby-blog.pl), released under the MIT license