Peter's Guide

This is a brief tutorial for setting up a small Rails 2.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 application for twittering. The first widget looks like this. Pretty straight-forward.

Installation

You already got Rails? Ok.

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

Now, rewrite config/environment.rb:

RAILS_GEM_VERSION = '2.3.8' unless defined? RAILS_GEM_VERSION
require File.join(File.dirname(__FILE__), 'boot')

Rails::Initializer.run do |config|
  config.gem "haml"
  config.gem "cells", :version => '3.3.4'
  config.gem "apotomo"
end

Apotomo.js_framework = :jquery

We’re gonna use JQuery in this examples.

Install the gems by hand, if you like:

$ gem install haml cells apotomo 

Layout

Next, we could need a layout.

%html
%head
  = javascript_include_tag "jquery-1.4.2.min"
  = stylesheet_link_tag "app"

%body
  = yield

The Tweet model

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

$ script/generate model tweet text:string
$ rake db:migrate

Controller

Widgets are usually embedded into controllers, so there should be one.

$ script/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.

$ script/generate widget twitter_widget display_form --haml
    exists  app/cells/
    create  app/cells/twitter_widget
    exists  test/widgets
    create  app/cells/twitter_widget.rb
    create  app/cells/twitter_widget/display_form.html.haml
    create  test/widgets/twitter_widget_test.rb

    

The widget class should look as follows.

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

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

The corresponding view for display_form is rendered in line 6. It contains the same tiresome markup as any other view in Rails.

 - widget_div do
   %ul
     - for tweet in @tweets
       %li
         = tweet.text
 
   %p
     What are you up to?
   
  - form_tag "", "data-event-url" => url_for_event(:submit) do
    = text_field_tag 'text'
  
    = submit_tag "Tweet!"
  
  :javascript
    var form = $("##{@name} form");
  
    form.submit(function() {
      $.ajax({url: form.attr("data-event-url"), data: form.serialize()})
      return false;
    });
  

Putting the tweeter in the dashboard

To plug your new widget in a controller, the controller should look like this.

 class DashboardController < ApplicationController
   include Apotomo::Rails::ControllerMethods
 
   has_widgets do |root|
     root << widget(:twitter_widget, 'parrot', :display_form)
   end
 
   def index
   end
end

Change the index view.

%h1 My Dashboard

= render_widget 'parrot'

Running it

Next, start the engine

$ script/server

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

Happy “tweeting”.

Apotomo is a Nick Sutterer product.