Skip to content

Latest commit

 

History

History
419 lines (309 loc) · 10.1 KB

README.md

File metadata and controls

419 lines (309 loc) · 10.1 KB
Raw

ActsAsMessageable

ActsAsMessageable is a Ruby gem that provides a flexible and robust messaging system between models in Rails applications. With this gem, you can easily implement features such as private messaging between users, conversations, message search, and much more. This gem is perfect for applications where communication between users or other models is required.

Build Status Code Climate Coverage Status Gem Version

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 [messages] [--uuid]
rake db:migrate

You need to run migration generator to create tables in database. You can do this with the acts_as_messageable:migration generator. Default table name is messages, you can pass table name and uuid option to enable uuid support (by default disabled). UUID support is required in case when your user primary key is uuid type.

Create messages table without uuid support

rails g acts_as_messageable:migration

Create messages table with uuid support

rails g acts_as_messageable:migration --uuid

Create my_messages table without uuid support

rails g acts_as_messageable:migration my_messages

Create my_messages table with uuid support

rails g acts_as_messageable:migration my_messages --uuid

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
                      :search_scope => :custom_search       # default :search
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 a 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]

This should receive list of latest messages in conversations.

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 for text within messages and get the records where a match exists.

Search text from messages

records = @alice.messages.search("Search me") # @alice searches for the text "Search me" in 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 from @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 read @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 deleted the message. That's why we use the .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 the message in the trash

@alice.deleted_messages #=> [@message]

We can delete the message permanently

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

@alice.delete_message #=> []

The 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 the 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 searches for the text "Search me" in all messages"

License

ActsAsMessageable is released under the MIT License. See the bundled LICENSE file for details.

Contributing

Contributions are welcome! To contribute:

  1. Fork the project.
  2. Create your feature branch (git checkout -b my-new-feature).
  3. Commit your changes (git commit -am 'Add some feature').
  4. Push to the branch (git push origin my-new-feature).
  5. Create a new Pull Request.