Module: Spree::Event

Extended by:
Event
Included in:
Event
Defined in:
lib/spree/event.rb,
lib/spree/event/subscriber.rb,
lib/spree/event/configuration.rb,
lib/spree/event/subscriber_registry.rb,
lib/spree/event/adapters/active_support_notifications.rb

Defined Under Namespace

Modules: Adapters, Subscriber Classes: Configuration, SubscriberRegistry

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#subscribers ⇒ Spree::Event::SubscriberRegistry (readonly)

Returns The registry for supporting class reloading for Spree::Event::Subscriber instances.

Returns:



105
106
107
 
# File 'lib/spree/event.rb', line 105

def subscriber_registry
  Spree::Config.events.subscriber_registry
end

Instance Method Details

#adapter ⇒ Object

The adapter used by Spree::Event, defaults to Spree::Event::Adapters::ActiveSupportNotifications

Examples:

Change the adapter

Spree::Config.events.adapter = "Spree::EventBus.new"

See Also:



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

def adapter
  Spree::Config.events.adapter
end

#fire(event_name, opts = {}) ⇒ Object

Allows to trigger events that can be subscribed using #subscribe. An optional block can be passed that will be executed immediately. The actual code implementation is delegated to the adapter.

Examples:

Trigger an event named ‘order_finalized’

Spree::Event.fire 'order_finalized', order: @order do
  @order.complete!
end

Parameters:

  • event_name (String) —

    the name of the event. The suffix “.spree” will be added automatically if not present

  • opts (Hash) (defaults to: {}) —

    a list of options to be passed to the triggered event



26
27
28
29
30
 
# File 'lib/spree/event.rb', line 26

def fire(event_name, opts = {})
  adapter.fire normalize_name(event_name), opts do
    yield opts if block_given?
  end
end

#listeners ⇒ Hash

Lists all subscriptions currently registered under the “.spree” namespace. Actual implementation is delegated to the adapter

Examples:

Current subscriptions

Spree::Event.listeners
  # => {"order_finalized.spree"=> [#<ActiveSupport...>],
    "reimbursement_reimbursed.spree"=> [#<ActiveSupport...>]}

Returns:

  • (Hash) —

    an hash with event names as keys and arrays of subscriptions as values



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

def listeners
  adapter.listeners_for(listener_names)
end

#subscribe(event_name, &block) ⇒ Object

Subscribe to an event with the given name. The provided block is executed every time the subscribed event is fired.

Examples:

Subscribe to the ‘order_finalized` event

Spree::Event.subscribe 'order_finalized' do |event|
  order = event.payload[:order]
  Spree::Mailer.order_finalized(order).deliver_later
end

Parameters:

  • event_name (String, Regexp) —

    the name of the event. When String, the suffix “.spree” will be added automatically if not present, when using the default adapter for ActiveSupportNotifications. When Regexp, due to the unpredictability of all possible regexp combinations, adding the suffix is developer’s responsibility (if you don’t, you will subscribe to all notifications, including internal Rails notifications as well).

Returns:

  • a subscription object that can be used as reference in order to remove the subscription

See Also:



55
56
57
58
59
 
# File 'lib/spree/event.rb', line 55

def subscribe(event_name, &block)
  name = normalize_name(event_name)
  listener_names << name
  adapter.subscribe(name, &block)
end

#subscriber_registry ⇒ Object 



105
106
107
 
# File 'lib/spree/event.rb', line 105

def subscriber_registry
  Spree::Config.events.subscriber_registry
end

#unsubscribe(subscriber) ⇒ Object

Unsubscribes a whole event or a specific subscription object

Examples:

Unsubscribe a single subscription

subscription = Spree::Event.fire 'order_finalized'
Spree::Event.unsubscribe(subscription)

Unsubscribe all ‘order_finalized` event subscriptions

Spree::Event.unsubscribe('order_finalized')

Unsubscribe an event by name with explicit prefix

Spree::Event.unsubscribe('order_finalized.spree')

Parameters:

  • subscriber (String, Object) —

    the event name as a string (with or without the “.spree” suffix) or the subscription object



73
74
75
76
 
# File 'lib/spree/event.rb', line 73

def unsubscribe(subscriber)
  name_or_subscriber = subscriber.is_a?(String) ? normalize_name(subscriber) : subscriber
  adapter.unsubscribe(name_or_subscriber)
end