Module: Spree::Event::Subscriber

Included in:
MailerSubscriber
Defined in:
lib/spree/event/subscriber.rb

Overview

This module simplifies adding and removing subscriptions to Spree::Event events. Here’s a complete example:

 module EmailSender
   include Spree::Event::Subscriber

   event_action :order_finalized
   event_action :confirm_reimbursement, event_name: :reimbursement_reimbursed

   def order_finalized(event)
     Mailer.send_email(event.payload[:order])
   end

   def confirm_reimbursement(event)
     Mailer.send_email(event.payload[:reimbursement])
   end
 end

# Optional, required only when the subscriber needs to be loaded manually.
#
# If Spree::Config.events.autoload_subscribers is set to `true` and the module
# file matches the pattern `app/subscribers/**/*_subscriber.rb` then it will
# be loaded automatically at boot and this line can be removed:
EmailSender.activate

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.included(base) ⇒ Object 



29
30
31
32
33
34
35
36
 
# File 'lib/spree/event/subscriber.rb', line 29

def self.included(base)
  base.extend base

  base.mattr_accessor :event_actions
  base.event_actions = {}

  Spree::Event.subscriber_registry.register(base)
end

Instance Method Details

#activate ⇒ Object

Activates all declared event actions to their events. Only actions that are activated will be called when their event fires.

Examples:

activate all event actions for module ‘EmailSender’

EmailSender.activate


78
79
80
 
# File 'lib/spree/event/subscriber.rb', line 78

def activate
  Spree::Event.subscriber_registry.activate_subscriber(self)
end

#deactivate(event_action_name = nil) ⇒ Object

Deactivates all declared event actions (or a single specific one) from their events. This means that when an event fires then none of its unsubscribed event actions will be called.

Examples:

deactivate all event actions for module ‘EmailSender’

EmailSender.deactivate

deactivate only order_finalized for module ‘EmailSender’

EmailSender.deactivate(:order_finalized)


89
90
91
 
# File 'lib/spree/event/subscriber.rb', line 89

def deactivate(event_action_name = nil)
  Spree::Event.subscriber_registry.deactivate_subscriber(self, event_action_name)
end

#event_action(method_name, event_name: nil) ⇒ Object

Declares a method name in the including module that can be subscribed/unsubscribed to an event.

Examples:

Declares ‘send_email’ as an event action that can subscribe the event ‘order_finalized’

module EmailSender
  event_action :send_email, event_name: :order_finalized

  def send_email(event)
    Mailer.send_email(event.payload[:order])
  end
end

Same as above, but the method name is same as the event name:

module EmailSender
  event_action :order_completed

  def order_completed(event)
    Mailer.send_email(event.payload[:order])
  end
end

Parameters:

  • method_name (String, Symbol) —

    the method that will be called when the subscribed event is fired

  • event_name (String, Symbol) (defaults to: nil) —

    the name of the event to be subscribed



61
62
63
64
65
66
67
68
69
70
71
 
# File 'lib/spree/event/subscriber.rb', line 61

def event_action(method_name, event_name: nil)
  mattr_writer "#{method_name}_handler"

  define_method "#{method_name}_handler" do
    Spree::Deprecation.warn("#{name}.#{method_name}_handler and #{name}.#{method_name}_handler= from the old events mapping interface are deprecated. Please use the new mapping stored in Spree::Event.subscribers.", caller)

    class_variable_get("@@#{method_name}_handler")
  end

  event_actions[method_name] = (event_name || method_name).to_s
end

#subscribe! ⇒ Object 



93
94
95
96
 
# File 'lib/spree/event/subscriber.rb', line 93

def subscribe!
  Spree::Deprecation.warn("#{self}.subscribe! is deprecated. Please use `#{self}.activate`.", caller)
  activate
end

#unsubscribe! ⇒ Object 



98
99
100
101
 
# File 'lib/spree/event/subscriber.rb', line 98

def unsubscribe!
  Spree::Deprecation.warn("#{self}.unsubscribe! is deprecated. Please use `#{self}.deactivate`.", caller)
  deactivate
end