The Spree::Event
module allows to fire and subscribe events inside the
Solidus codebase and extensions.
The module can use different adapters that actually manage events at a low
level, the default adapter is Rails ActiveSupport::Notification
. Future
releases may include other adapters.
Among other uses, the Solidus codebase uses events in order to send confirmation emails when an order is finalized, or again to send emails when an order is refunded successfully.
Currently, the events fired by default in Solidus are:
* order_finalized
* reimbursement_reimbursed
* reimbursement_errored
Events make extending Solidus with custom behavior easy. For example, if besides the standard email you also want to send a SMS text message to the customer when a order is finalized, this pseudo-code may do the trick:
Spree::Event.subscribe 'order_finalized' do |event|
order = event.payload[:order]
SmsLibrary.deliver(order, :finalized)
end
The adapter can be changed using this code, for example in a initializer:
Spree::Config.events.adapter = "Spree::EventBus.new"
Spree::Event.subscribe
allows to subscribe to a certain event. The event
name is mandatory, the optional block will be executed every time the event
is fired:
Spree::Event.subscribe 'order_finalized' do |event|
order = event.payload[:order]
Spree::Mailer.order_finalized(order).deliver_later
end
Another way to subscribe to events is creating a "subscriber" module that
includes the Spree::Event::Subscriber
module. For example:
module Spree
module SmsSubscriber
include Spree::Event::Subscriber
event_action :order_finalized
event_action :send_reimbursement_sms, event_name: :reimbursement_reimbursed
def order_finalized(event)
order = event.payload[:order]
SmsLibrary.deliver(order, :finalized)
end
def send_reimbursement_sms(event)
reimbursement = event.payload[:reimbursement]
order = reimbursement.order
SmsLibrary.deliver(order, :reimbursed)
end
end
end
The Spree::Event::Subscriber
module provides a simple interface that
allows executing code when a specific event is fired. The event_action
method allows to map a method of the subscriber module to an event that
happens in the system. If the event_name
argument is not specified,
the event name and the method name should match.
These subscribers modules are loaded with the rest of your application but you need to manually subscribe to them.
For example, you could subscribe to them programmatically with something like:
if defined?(SmsLibrary)
Spree::SmsSubscriber.subscribe!
end
or just by adding thme to the list of default subscribers, using the
Spree::Config.events.subscribers
configuration:
Spree::Config.events.subscribers << 'Spree::SmsSubscriber'
All the modules present in this array will be loaded while your application
boots and the subscribe!
method is automatically called on them.
Spree::Event.fire
allows you to fire an event. The event name is mandatory,
then both a hash of options (it will be available as the event payload)
and an optional code block can be passed:
Spree::Event.fire 'order_finalized', order: @order do
@order.finalize!
end
This is an alternative way to basically have the same functionality but without the block:
@order.finalize!
Spree::Event.fire 'order_finalized', order: @order
For further information, please refer to the RDOC documentation included in
the Spree::Event
module.
Solidus is an open source platform supported by the community. We encourage everyone using Solius to contribute back to the documentation and the code.
If you’re interested in contributing to the docs, get started with the contributing guidelines. If you see something that needs fixing and can’t do it yourself, please send us an email.