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:



129
130
131
132
 
# File 'lib/spree/event.rb', line 129

def subscribers
  Spree::Deprecation.warn("`#{self}.subscribers` is deprecated. Please use `#{self}.subscriber_registry` instead.", caller)
  Spree::Config.events.subscribers
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:



113
114
115
 
# File 'lib/spree/event.rb', line 113

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.finalize!
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



102
103
104
 
# File 'lib/spree/event.rb', line 102

def listeners
  adapter.listeners_for(listener_names)
end

#require_subscriber_files ⇒ Object

Deprecated.

Loads all Solidus’ core and application’s event subscribers files.

The latter are loaded automatically only when the preference Spree::Config.events.autoload_subscribers is set to a truthy value.

Files must be placed under the directory ‘app/subscribers` and their name must end with `_subscriber.rb`.

Loading the files has the side effect of adding their module to the list in Spree::Event.subscribers.



41
42
43
44
 
# File 'lib/spree/event.rb', line 41

def require_subscriber_files
  Spree::Deprecation.warn("#{self}.require_subscriber_files is deprecated and will be removed in Solidus 3.0.", caller)
  subscriber_registry.send(:require_subscriber_files)
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:



69
70
71
72
73
 
# File 'lib/spree/event.rb', line 69

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

#subscriber_registry ⇒ Object 



136
137
138
 
# File 'lib/spree/event.rb', line 136

def subscriber_registry
  Spree::Config.events.subscriber_registry
end

#suffix ⇒ Object

The suffix used for namespacing Solidus events, defaults to ‘.spree`

See Also:



121
122
123
124
 
# File 'lib/spree/event.rb', line 121

def suffix
  Spree::Deprecation.warn "This method is deprecated and will be removed. Please use Event::Adapters::ActiveSupportNotifications#suffix"
  Spree::Config.events.suffix
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



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

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