Passing Messages with Events

In this guide we’re gonna explore an interesting feature related with events, which is called message passing.

The example in this guide may look weird, and it actually is – let’s use it for discussion and learning a couple of things about Apotomo.

Events can transport payload

In the last chapter the :newTweet event urged our panel widget to redraw the entire tweets list. As it consumes a lot of time to reload the tweets from the database instead we could also just redraw the new tweet.

How would the panel know which tweet is the one just created? The form widget could propagate that using the event.

 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, :tweet => @tweet
      replace :state => :display
    else
      replace :view => :display
    end
  end

end

We simply append the new tweet to the triggered event (line 13). States triggered by this event can now access this payload data – cool!

The event object speaks!

Let’s see how we can query the event object for the new tweet.

 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)
    text = evt[:tweet].text
    
    render :text => "$(\"##{widget_id} ul\").append(\"<li>#{text}</li>\");"
  end
  
end

I tweaked the #redraw_list method. What re-rendered the display state now sends back one new <li>...</li> item, only (line 18-22).

By using evt[:tweet] I can access the tweet model sitting piggy-back on the event triggered in the form (line 19).

Sending back plain JavaScript

Note how I don’t use #replace anymore but send back hand-made JavaScript (line 21).

The content sent to the browser roughly looks like this.

$("#twitter ul").append("<li>boardumb</li>");

This simply appends the new tweet to the list. Nothing more.

Discussion

The alert reader with the desire for strong encapsulation will notice a small interface violation here: The panel widget knows about the HTML format of a list item. This should be handled by the list state, or by a separate tweet widget.

We’re gonna cover that in the next chapter.

Apotomo is a Nick Sutterer product.