A Cookbook.

After being compared to seaside I had a look at this project. Looks great, it is a stateful component framework in Smalltalk. To demonstrate my concepts in Apotomo I had to steal the counter example from the page.

As usual, we implement the counter logic in a cell.

app/cells/counter_cell.rb

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

class CounterCell < Apotomo::StatefulWidget
 
  def transition_map
    { :_increase => [:_increase, :_decrease],
      :_decrease => [:_increase, :_decrease],
    }
  end
 
  def count
    @count = 0
    jump_to_state :_increase
  end
 
  def _increase
    @count += 1  
    state_view :_count
  end
 
  def _decrease
    @count -= 1  
    state_view :_count
  end
end

The widget is plugged into an arbitrary part of the GUI.

app/apotomo/application_widget_tree.rb

some_pg << cell(:counter, :count, 'my_counter')

Start state is :count, which initializes the counter and jumps to the state :_increment (line 10-11). Here we actually increment our counter and render the view _count (line 16). Let’s look at the view.

app/cells/counter/_count.html.erb

<h1><%= @count %></h1>
 
<%= link_to_event("--", :state => :_decrease) %>
<%= link_to_event("++", :state => :_increase) %>

Simple stuff. We create two links which reference to the current widget my_counter and push the widget state machine into the respective state. Looking at the transition map (line 4-5) we see that the requested states are permitted.

After all this coding, I have to admit that the comparison with seaside made me somewhat proud.

Cell states are mapped to methods. They may return a string as view. However, if you want to use a real template as state view, just return nothing. Recall our Hello World! example.

app/cells/hello_world_cell.rb

1
2
3
4
5
6
7

class HelloWorldCell < Apotomo::StatefulWidget
  def shout_hello
    @my_object = "Me? I said nothing!"
 
    nil
  end
...

When the state shout_hello is invoked, it won’t return a string but nil. This tells Apotomo to look for a template file called shout_hello.[rhtml|haml|...]. Instance variables assigned in the method can be used within the view file - just as you’re used to from controller actions!

A view might look like this:

app/cells/hello_world/shout_hello.rhtml

<h1>Hey, hello world!</h1>
What did you say? <%= @my_object %>

This gives you all the power and functionality known from the traditional rails controllers approach, along with Apotomo’s component flexibility.

But what if you dont want to name your state view after the method? Well, keep cool. Use state_view to command Apotomo to look for a view with a different name.

app/cells/hello_world_cell.rb

8
9
10
11

  def yell_hello
    # do something senseful...
    state_view :another_view
  end

This will result in the view another_view.[rhtml|haml|...] being rendered.

Every cookbook needs a Hello world recipe. I won’t omit this.

We will write the first small widget here. It will plug into the application and show the magic words. As widgets are derived cells, widgets that contain user application logic are called Cell in Apotomo.

app/cells/hello_world_cell.rb

1
2
3
4
5

class HelloWorldCell < Apotomo::StatefulWidget
  def say_hello
    "Hello world!"
  end
end

Note that our fresh cell widget is derived from Apotomo::StatefulWidget, which is the superclass of any widget.

So, how do we plug that widget into our application? In Apotomo, widgets are organized in a widget tree. The initial widget tree is defined in a well-known ruby class file.

app/apotomo/application_widget_tree.rb

1
2
3
4
5

class ApplicationWidgetTree < Apotomo::WidgetTree
  def draw(root)
    root << cell(:hello_world, :say_hello, 'hello_world_cell')
  end
end

By using the method cell, we advise Apotomo to render the widget HelloWorldCell and its state say_hello. A state is mapped to a method that itself returns the state view.
The third argument is an id string - it’s needed when referencing to that widget.

To push the widget in the actual application we have to go into a controller method.

1
2
3
4
5
6
7

class SomeController < ApplicationController  
  include Apotomo::ControllerHelper
 
  def top
    act_as_widget('hello_world_cell')
  end
end

The method act_as_widget plugs in our handsome widget. In the end, when navigating to some_controller/top, you will see the string “Hello world!”. Wow, this is awesome. Congratulations to your first widget.