Very Basic Widget

Documentation in Progress

I will try to explain how to create a very simple widget to help you understand how to use apotomo. I asume you understand how cells works.
In the first iteration we will create a widget only to show text.

Create an empty widget

scripts/generator widget text show

This must create:

• app/cells/text_cell.rb
• app/cells/text/show.html.erb
• test/functional/test_text_cell.rb

Put some content in the widget

We need to define a micro-controller for our widget.

• Edit: app/cells/text_cell

class TextCell < Apotomo::StatefulWidget
  def transition_map
    { 
    }
  end
  def show
    @text = "it's alive"
    nil
  end
end

Also we need to create a view for that micro controller

• Edit: app/cells/text/show.html.erb

<h1>Text#show</h1>
<p>This is your text: <%= @text %></p>

Stick our widget to a normal controller.

• Edit: app/controllers/foo_controller.rb

class FooController < ApplicationController
  include Apotomo::ControllerMethods
  def index
    use_widgets do |root|
      root << cell(:text, :show, 'text_widget')
    end
    @widget = render_widget 'text_widget'
    respond_to do |format|
      format.html
    end
  end
end

Note what we did here:

• include the Apotomo ControllerMethods
• define our widget with use_widgets using this format:

root << cell(:WidgetName,:WidgetAction,'Assigned_Name')

• assign our widget to a instace variable:

@widget = render_widget 'Assigned_Name'

Finally we need to render the widget in the view of the same controller.

• Edit: app/views/foo/index.html.erb

<%= @widget %>

Reuse the widget
What if we want to use the same widget in several controllers?
You can share widgets using application_widget_tree.rb
Remove the use_widgets block from your controller and edit app/model/_application_widget_tree, Add this:

class ApplicationWidgetTree < Apotomo::WidgetTree
  def draw
    root << cell(:text, :show, 'text_widget')
  end
end

We just define the widget as we did before using use_widgets. Notice all widgets definitions must go in a method called draw.

Pass options to the widget from the controller (not finished)

somthing like?

render_widget 'widget_name', :foo => "bar"

We need to define a micro-controller for our widget.

• Edit: app/cells/text_cell

class TextCell < Apotomo::StatefulWidget
  def transition_map
    { 
    }
  end
  def show
    @text = "it's alive"
    nil
  end
end

Also we need to create a view for that micro controller

• Edit: app/cells/text/show.html.erb

<h1>Text#show</h1>
<p>This is your text: <%= @text %></p>

Stick our widget to a normal controller.

• Edit: app/controllers/foo_controller.rb

class FooController < ApplicationController
  include Apotomo::ControllerMethods
  def index
    use_widgets do |root|
      root << cell(:text, :show, 'text_widget')
    end
    @widget = render_widget 'text_widget'
    respond_to do |format|
      format.html
    end
  end
end

Note what we did here:

• include the Apotomo ControllerMethods
• define our widget with use_widgets using this format:

root << cell(:WidgetName,:WidgetAction,'Assigned_Name')

• assign our widget to a instace variable:

@widget = render_widget 'Assigned_Name'

Finally we need to render the widget in the view of the same controller.

• Edit: app/views/foo/index.html.erb

<%= @widget %>