Bubbling Events, pt. 1

The simple event system in Apotomo is one of its strengths when being compared to traditional controllers.

It helps you building decoupled systems without having to write manual dispatching code.

Triggering events

When starting with Apotomo the first events are usually fired through triggering requests from the browser.

In order to notify the outer world about a new tweet, we need to modify the FormWidget.

 class Twitter::FormWidget < Apotomo::Widget
   responds_to_event :submit
   
   def display
     @tweet = Tweet.new
     render
   end
 
   def submit(evt)
    @tweet = Tweet.new
    
    if @tweet.update_attributes(evt[:tweet])
      trigger :newTweet
      replace :state => :display
    else
      replace :view => :display
    end
  end

end

There’s a #trigger statement, wow (line 13)! This is all we need to fire a bubbling :newTweet event.

How do events bubble?

Remember, we have something to say to the outer world: “Hey, there’s a brand-new tweet from the form widget!”

How can the panel catch that event and in response update the tweets list it manages? Well, let’s check the way the bubbling event is traveling.

root
|-- panel
|   |-- form (triggers :newTweet)

Since the triggering form widget is a child of panel, the event will pass the panel on its way to root.

That means, we can simply use #responds_to_event in the PanelWidget.

 class Twitter::PanelWidget < Apotomo::Widget
   responds_to_event :newTweet, :with => :redraw_list
   
   has_widgets do
     self << widget("twitter/form", :tweet_form)
   end
   
   
   def display
    @tweets = Tweet.find(:all)
    render
  end
  
  def list(tweets)
    render :locals => {:tweets => tweets}
  end
  
  def redraw_list(evt)
    replace "##{widget_id} ul", {:state => :list}, Tweet.find(:all)
  end
  
end

Two things got added here.

First, we watch out for the :newTweet event and let it invoke the panel’s #redraw_list state (line 2).

Second, I added a #redraw_list method (line 18-20). This one is pretty interesting. The #replace methods passes the updated tweets list to the #list state and the replaces the list in the page using a custom selector.

Using selectors

The rendered panel roughly looks like this:

  <div id="twitter">
    <ul>
      <li data-id='10'>
        Listening to ALL.
      </li>

Everything inside the <ul> is from the #list state, so why not simply render that state and then replace it?

    replace "##{widget_id} ul", {:state => :list}, Tweet.find(:all)

An alternative way to replace content

If that does look weird to you, you can go another way. The replace statement could also be written like this:

html = render({:state => :list}, Tweet.find(:all))
replace "##{widget_id} ul", :text => html

Summary

Clicking “Tweet!” after typing in some text really updates the form and the panel list. Awesome! Our bubbling event worked.

• The :submit event is processed in the form widget.
• It adds a new tweet to the database, triggers an event and then re-renders itself.
• The panel widget gets alerted by the triggered event and re-renders its list.
• Both page updates are returned to the browser.

Bubbling events is a powerful tool when it comes to inter-widget communication. What a ridiculous word.

Anyway, the list redrawing consumes a lot of cycles as it reloads the entire tweets collection. Let’s learn how we can use the event as a message object in the next excursus.

Apotomo is a Nick Sutterer product.