Peter's Guide

Apotomo is a generic widget framework for Rails. While you write the actual widgets – like a twitter box, tab panels or a full-blown shopping cart – Apotomo provides you with all you need for a component-oriented GUI application.

Here’s a quick overview:

• Apotomo::Widget – your starting point. It looks and feels like a mini-controller with views, states, event handling, and more. Did you know that Apotomo::Widget < Cell:Base? Check the cells project if you’re lost now.
• A generator to stub out all the necessary assets for you.
• Widgets can respond to events within Ruby.
• You can setup widget trees and use them throughout your ActionController.

What are we gonna do?

This is a brief tutorial for setting up a small Rails 3 app with Apotomo widgets. It’s meant as a starting point for learning Apotomo, so grab a beer and read on!

The code is available in a git repo, feel free to clone.

During the course we are developing a rich dashboard application for twittering. The first widget looks like this. Pretty straight-forward.

Installation

You've already got Rails? Ok.

$ rails new bar
    create  
    create  app/controllers
    create  app/helpers
    create  app/models
    create  app/views/layouts
    ...

Now, tweak your Gemfile, we need the Apotomo gem:

source 'http://rubygems.org'

gem 'rails', '~>3.0'
gem 'apotomo', "~>1.1.0"
gem 'haml'
gem 'sqlite3-ruby', :require => 'sqlite3'
gem 'jquery-rails'

Install the gems with bundler.

$ bundle install

Layout

Next, we need a layout.

%html
%head
  = javascript_include_tag :defaults
  = stylesheet_link_tag "app"

%body
  = yield

Notice that we already pull JQuery and Rails UJS support into the page (line 3).

Installing jquery-ujs needs another step.

$ rails generate jquery:install

The Tweet model

Say we’re writing a small widget that let’s you post and displays your recent posts. We need a Tweet model for that.

$ rails generate model tweet text:string
$ rake db:migrate

Controller

Widgets are usually embedded into controllers, so let’s generate a dashboard controller.

$ rails generate controller dashboard index
    exists  app/controllers/
    exists  app/helpers/
    ...

The first Widget!

Writing a tweet widget is as easy as creating a new controller.

$ rails generate apotomo:widget twitter display -e haml
    exists  app/widgets/
    create  app/widgets/twitter
    exists  test/widgets
    create  app/widgets/twitter_widget.rb
    create  app/widgets/twitter/display.html.haml
    create  test/widgets/twitter_widget_test.rb

    

The widget class should look as follows. Notice that widgets reside in app/widgets/.

 class TwitterWidget < Apotomo::Widget
   responds_to_event :submit, :with => :process_tweet
 
   def display
     @tweets = Tweet.find(:all)
     render
   end
   
   def process_tweet(evt)
    Tweet.new(:text => evt[:text]).save

    @tweets = Tweet.find(:all) # this is wet!
    replace :view => :display
  end
end

Feeling knocked down? No problem, let’s go through this step-by-step.

How do I render widgets in the dashboard controller?

Ok, I will start the other way round, with the dashboard controller which uses the twitter widget.

 class DashboardController < ApplicationController
 
   has_widgets do |root|
     root << widget(:twitter)
   end
 
   def index
   end
 end

Apotomo requires you to “declare” which widgets you’re gonna use in an action. And this is done in the has_widgets block (line 3-5). We simply append our brand-new twitter widget to the root widget.

Render it!

Nothing will happen until we actually render the widget in the action view.

%h1 My Dashboard

#dashboard
  .column
    = render_widget :twitter

This will invoke our twitter widget’s #display method and simply return the markup (or whatever else you do).

The widget got a view

Let’s peek at the widget’s source, again.

 class TwitterWidget < Apotomo::Widget
   responds_to_event :submit, :with => :process_tweet
 
   def display
     @tweets = Tweet.find(:all)
     render
   end

First, we grab all available tweets (line 5). Next, we call #render which will render #display’s view. This is roughly similar to ordinary controllers.

 - widget_div do
   %ul
     - for tweet in @tweets
       %li
         = tweet.text
  
   %p
     What are you up to?
    
  - form_tag url_for_event(:submit), :remote => true do
    = text_field_tag 'text'
   
    = submit_tag "Tweet!"

The entire view is wrapped by #widget_div (line 1) – which is just a helper doing something like

<div id="twitter">
  ...
</div>

Oh no, JavaScript!

Most of the view is boring stuff. We list all twitter items (line 3-5) and then create an AJAX form. Notice how we delegate computation of the form’s action url to Apotomo by calling #url_for_event (line 10).

Triggering an event

Now that you click “Submit”, what happens?

• The js logic wired in rails.js detects a form submission. Since the form is tagged with :remote => :true this usually means it wants to be submitted via AJAX.
• An AJAX request is sent, to something like http://localhost:3000/dashboard/render_event_response?source=twitter&type=submit&text=Hey.
• Apotomo processes this request and triggers the :submit event in the twitter widget.
• Now… how does the widget react?

Responding to events

Remember, our widget started like this:

 class TwitterWidget < Apotomo::Widget
   responds_to_event :submit, :with => :process_tweet

That’s where we set our observer, saying “If I see a :submit event, I run my #process_tweet state!”.

Updating the widget in the browser

What does the #process_tweet method do in order to respond to the event?

   def process_tweet(evt)
    Tweet.new(:text => evt[:text]).save

    @tweets = Tweet.find(:all) # this is wet!
    replace :view => :display
  end

Please note how the method receives the event object as argument (line 9) – how cool’s that?

The event may be queried for parameters sent with the event – this is how we retrieve the entered text from the form (line 10).

We then reload the tweets list (line 12) and call #replace to, well, replace the widget on the page (line 13). In other words, we re-render the display view and replace it in the browser.

Finally, let’s run it!

Now that we figured all the important parts, start the engine! I can hear the theme of Rocky I in the background…

$ rails s

…and browse to http://localhost:3000/dashboard

Happy “tweeting”.

Now, let’s learn how to improve our view architecture by using partials and states.

Apotomo is a Nick Sutterer product.