module Stex::Acts::Messagable::ClassMethods

Public Instance Methods

acts_as_messagable(options = {}) click to toggle source

Adds the functionality to send and receive messages to this ActiveRecord class

@param [Hash] options

Available Options and overrides for this model class

@option options [Proc, Symbol] :sender_name (“Class.human_name self.id”)

Proc or Proc Name to determine the sender name.

@option options [Proc, Symbol] :recipient_name (“Class.human_name self.id”)

Proc or Instance Method Name to determine the recipient name.

@option options [Proc, Symbol] :forward_to

Proc or Instance Method Name. If specified, the system will forward
received messages to the method's return value instead of to
the actual record

@option options [Array<Array<Symbol, Proc|Symbol, String>>] :optional_recipients

One ore more recipients that may be included in a message
to an instance of this class. These should be selectable on the view part
of the application, e.g. checkboxes next to the actual recipient.
The elements are used as follows:

1. An identifier to access this optional recipient group,
2. The actual selector that should return the recipients,
3. A string or Proc that tells the system how to display this optional recipient

@option options [Proc, Symbol] :handler

If given, messages are sent to the given proc object / instance method instead of
actually created in the database.
The handler method has to accept 2 arguments, the message sender and a +Hash+ of options
These options include:
- :subject
- :content
- :additional_recipients (optional)

@option options [Bool, Symbol, Proc] :store_additional_recipients

If set or evaluating to +true+, all recipients (CC) are stored in a +Message+ record.
This might make sense in cases when e.g. an email should contain a list of
all the people that received it.
If the value is a Symbol, the system will assume that there is an instance method with that name.

@example Forwarding group messages to its students and optionally include the tutors

acts_as_messagable :forward_to          => :students,
                   :optional_recipients => [[:tutors, lambda { |r| r.tutors }, Tutor.human_name(:count => 2)]]
# The selector could simplified by +:tutors+ instead of the lambda expression
# File lib/stex/acts/messagable.rb, line 171
def acts_as_messagable(options = {})
  klass = Stex::Acts::Messagable.message_class_name

  #Add has_many associations for easy message management
  has_many :received_messages, :class_name => klass, :as => :recipient, :conditions => {:sender_copy => false}
  has_many :unread_messages, :class_name => klass, :as => :recipient, :conditions => {:read_at => nil, :sender_copy => false}
  has_many :read_messages, :class_name => klass, :as => :recipient, :conditions => ['read_at IS NOT NULL AND sender_copy = ?', false]
  has_many :sent_messages, :class_name => klass, :as => :sender, :conditions => {:sender_copy => true}

  cattr_accessor :acts_as_messagable_options

  coptions                       = {}

  #Sender and recipient procs
  coptions[:sender_name]         = options[:sender_name] || lambda { |r| "#{r.class.human_name}: #{r.id}" }
  coptions[:recipient_name]      = options[:recipient_name] || lambda { |r| "#{r.class.human_name}: #{r.id}" }

  #Forward and message handler proc
  coptions[:forward_to]          = options[:forward_to] if options.has_key?(:forward_to)
  coptions[:handler]             = options[:handler] if options.has_key?(:handler)

  #optional recipients
  coptions[:optional_recipients] = options[:optional_recipients] if options[:optional_recipients]

  coptions[:store_additional_recipients] = options[:store_additional_recipients]

  self.acts_as_messagable_options = coptions.freeze

  include Stex::Acts::Messagable::InstanceMethods
end