A Cookbook.

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.