Simple Messenger

Add messaging functionality to active record models.

Requires ruby >= 2.0.0

Installation

Add this line to your application's Gemfile:

gem 'simple_messenger'

And then execute:

$ bundle

Or install it yourself as:

$ gem install simple_messenger

Run the generator to create the migration file and message model:

$ rails g messages

Migrate the database:

$ rake db:migrate

Usage

Message Model

The following model will be generated and placed in your app/models folder:

class Message
  include SimpleMessenger::MessageAdditions
end

You can add custom functionality to the Message model here.

Messenger Model

Add simple_messenger to the top of your activerecord model:

class User
  simple_messenger
end

The class is not restricted to User, it can be any class you add simple_messenger to.

Creating Messages

Send messages by passing in a sender, receiver and some content:

bob = User.create
alice = User.create
bob.create_message!(receiver: alice, content: 'Hello')
# => <Message id: 1 sender_id: 1 sender_type 'User' ... content: "Hello" viewed: false>

bob.messages.count
# => 1

bob.sent_messages.count
# => 1

bob.sent_messages_to(alice).count
# => 1

bob.sent_messages_to(jimmy).count
# => 0

bob.received_messages.count
# => 0

bob.new_messages.count
# => 0

bob.messages_with(alice)
# => <Message id: 1 ... >

alice.messages.count
# => 1

alice.sent_messages.count
# => 0

alice.received_messages.count
# => 1

alice.received_messages_from(bob).count
# => 1

alice.received_messages_from(jimmy).count
# => 0

alice.new_messages.count
# => 1

alice.messages_with(bob)
# => <Message id: 1 ... >

Messenger Helpers

The following constructors are available:

bob.build_message
bob.new_message
bob.create_message
bob.create_message!

Due to the design of the library you would have to type:

bob.sent_messages.build ...

As typing the bob.messages returns a specialized relation and is not created through a has_many relationship:

Message Helpers

Class Methods

To get all the member ids in a collection of messages use the following:

Message.uniq_member_ids_for(messages)

You can optionally omit one or more member from the collection:

Message.uniq_member_ids_for(messages, remove: current_user)

This could be useful for rendering a list of users which the current_user has messaged.

remove can be an id, array of ids, ActiveRecord object, collection of ActiveRecord objects, or anything that respond_to?(:id)

Instance Methods

Check to see if the message has been read:

msg = Message.create(sender: bob, receiver: alice, content: 'Hello')
# => <Message ... viewed: false>
msg.read?(bob) # true as bob is the sender
# => true
msg.read?(alice)
# => false

Find the opposite member in the message:

msg = Message.create(sender: bob, receiver: alice, content: 'Hello')
# => <Message ... >
msg.member_who_is_not(bob)
# => <User ... username: 'alice'>
msg.member_who_is_not(alice)
# => <User ... username: 'bob'>
msg.member_who_is_not(jimmy)
# => SimpleMessenger::NotInvolved error

Contributing

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request