A Cookbook.

In the current refactoring of Apotomo I finally extracted the bubbling event library into a separate ruby gem Onfire.

Bubbling events is, in contrast to Ruby’s own Observable module, focused on observing events triggered by business objects, not watching the objects themselves.

In addition, a triggered event will bubble up the tree branch and subsequently inform all ancestors- you get automatic organic event filtering.

Complete instructions are on the github page.

Let’s see how it works.

> require 'rubygems'
> require 'onfire'
> class Object
>   include Onfire
>   attr_accessor :parent
> end

Bubbling events only make sense in a tree structure. That’s why Onfire has one requirement to the class it’s mixed into- #parent.

ruby = Object.new
 
ruby.on :syntaxError do |event| puts "ruby: omg, a syntax error in #{event.source}" end
ruby.fire :syntaxError
# => ruby: omg, a syntax error in #<Object:0xb75a087c>

That was simple, Observable can do this, too.

Appending a method

Now let’s add a method object to ruby.

method = Object.new
method.parent = ruby
 
method.on :syntaxError do |event| puts "method: a syntax error in ME?" end
method.fire :syntaxError
#=> method: a syntax error in ME?
#=> ruby: omg, a syntax error in #<Object:0xb756dd00>

The event bubbles. What about some variable in the method?

variable = Object.new
variable.parent = method
 
variable.on :syntaxError do |event| puts "variable: I am the problem." end
variable.fire :syntaxError
#=> variable: I am the problem.
#=> method: a syntax error in ME?
#=> ruby: omg, a syntax error in #<Object:0xb756dd00>

Extending the tree model

Maybe there’s another method attached to ruby.

method2 = Object.new
method2.parent = ruby
 
method2.on :syntaxError do |event| puts "method2: Whoops, something here is wrong." end

Now if variable fires, method2 shouldn’t be informed. Remember, the variable is in method.

variable.fire :syntaxError
#=> variable: I am the problem.
#=> method: a syntax error in ME?
#=> ruby: omg, a syntax error in #<Object:0xb756dd00>

Works. That’s organic event filtering resulting from ascending event propagation.
The bubbling event from variable never hits method2 on its way up.

Stopping the event

What if method wants to intercept syntax errors in its scope, so ruby won’t get informed any further about errors in method?

method.on :syntaxError do |event| 
  puts "method: that's private things"
  event.stop!
end
 
variable.fire :syntaxError
#=> variable: I am the problem.
#=> method: a syntax error in ME?
#=> method: that's private things

The event stops in method.

And what if method2 contains errors?

method2.fire :syntaxError
#=> method2: Whoops, something here is wrong.
#=> ruby: omg, a syntax error in #<Object:0xb75348d4>

It still bubbles up to root. Yeah, makes sense, it’s a different tree branch.

More!

I told you, more examples, source filtering, bubbling, babbling, intercepting on the github. Have fun and let me know how it works for you!