anoiaque/central_notifications

== Overview

Based on the idea of notifications in objective-C.

Register an object method for notifications.

When registered method is called, all objects which have registered will be notified and will be able to know the result of the registered method.

Can act as Rails observers, by registering on setters methods.

You can register both class or instance methods.

Several different objects, with different class can register for same object method.

See tests units for more examples of usage.

== Quality Metrics

{<img src="https://codeclimate.com/badge.png" />}[https://codeclimate.com/github/anoiaque/central_notifications]

== Continuous Integration
http://travis-ci.org/anoiaque/central_notifications.png

== Install

  gem install central_notifications

== Dependencies

none

== Usage


=== Declaring a notifier
==== In the model
You can declare a notifier inside the model by including the module CentralNotifications and then declare in you model :
  register_for_notification do |registration, notification|
    registration.klass = Order
    registration.method = :payment
    notification.method = :one_order_has_been_payed
  end
In this way you don't have to declare the notification klass, it will be automatically set to self.

==== In an initializer
You can register your notification in an initializer (for exemple, in Rails, in a file under config/initializers).

The analog as previous example will be in this initializer :
  CentralNotifications.notify do |registration, notification|
    registration.klass = Order
    registration.method = :payment
    notification.klass = User
    notification.method = :one_order_has_been_payed
  end

== Example
Suppose you have classes User and Order, and, you have registered for notification on instance method :payment (as previous)

  class User
    def one_order_has_been_payed
     puts "Hey! one user know that one order has been paid!"
    end
  end
  
  def Order
    def payment(amount)
      @amount = amount
    end
  end
  
  user = User.new
  order = Order.new
  order.payment(100)
  # => "Hey! one user know that one order has been paid!"
  
If you register notification for another class objects :

  class Acounting
    include CentralNotification
    
    def one_order_has_been_payed
      "Hey ! an accounting object know that one order has been payed"
    end
    
    register_for_notification do |registration, notification|
      registration.klass = Order
      registration.method = :payment
      notification.method = :one_order_has_been_payed
    end
  end
  
then :
  user = User.new
  accounting = Accounting.new
  order = Order.new
  order.payment(100)
  
   # => "Hey! one user know that one order has been paid!"
   # => "Hey ! an accounting object know that one order has been payed"

== Retrieve the result of the registered method

You can get in User class the result of Order#payment in the instance variable @registration_result.

  def one_order_has_been_payed
    puts "Payment is : " + @registration_result.to_s
  end
  
  user = User.new
  order = Order.new
  order.payment(100)
  
  # => "Payment is : 100"

== Retrieve the object which trigger the notification

You can get in User class the result of Order#payment in the instance variable @registration_result.

  def one_order_has_been_payed
    puts "payment has been called by this object : " + @notifier_object
  end
  
  user = User.new
  order = Order.new
  order.payment(100)
  
  # => "payment has been called by this object : <Order: ....>"

== Acting as Observer

You can use central notifications as observers on attribute values change.
For that, just register on setter :
    
    class Order
      attr_accessor :amount
    end

    class User
      include CentralNotification
    
      def amount_has_changed
        puts "The amount has changed and is now:" + @registration_result.to_s
      end
    
      register_for_notification do |registration, notification|
        registration.klass = Order
        registration.method = :amount=
        notification.method = :amount_has_changed
      end
    end



  user = User.new
  order = Order.new
  order.amount = 100
  #=> From user : The amount has changed and is now: 100

== ChangeLog

* FIX : Failures with Ruby 1.9 . #instance_methods, #singleton_methods ... family methods return symbols. Ruby 1.8.x return strings.
* NEW : Notified method has access to object which triggered notification