Ok, last week we had a working app with a list widget showing the items. Today we’re gonna write a form widget to add new items. The code for this lesson is at tag 0.7.

1First thing to do is generating stubs.

$ script/generate widget item_form display create --haml
      create  app/cells/item_form
      create  app/cells/item_form.rb
      create  app/cells/item_form/display.html.haml
      create  app/cells/item_form/create.html.haml

The app/cells/item_form.rb file looks like this, after some editing.

1
2
3
4
5
6

class ItemForm < Apotomo::StatefulWidget
  def display
    @todo = Todo.new
    render
  end
end

I create a new Todo so I can use it in the view.

2The view needs to be implemented, too!

app/cells/item_form/display.html.haml

1
2
3
4
5
6
7

%h3 Create new item
 
= error_messages_for :todo
 
- form_to_event(:submit) do
  = text_area :todo, :text, :rows => 2
  = submit_tag "Create Todo!"

Easy. The only interesting here is the call to #form_to_event
which basically triggers a :submit event when the form is, nah, submitted (line 5).

3
Let’s append the form widget to our widget tree in app/controllers/dashboard_controller.rb.

1
2
3
4
5
6
7
8
9
10

class DashboardController < ApplicationController
  include Apotomo::ControllerMethods
 
  def index
    use_widgets do |root|
      root << widget(:item_list, 'dashboard_list')
      root << widget(:item_form, 'new_item')
    end
  end
end

I call the widget new_item (line 7).

4Pluggin’ the widget into the controller again happens in app/views/dashboard/index.html.erb (line 10 and 12).

<h2>Dashboard</h2>
 
<div class="slot">
  <%= render_widget 'dashboard_list' %>
</div>
 
<div class="slot">
  <%= render_widget 'new_item' %>
</div>

5In order to process the form, we need to observe that :submit event, so I will extend the widget class a bit.

1
2
3
4
5
6
7
8
9
10
11
12
13
14

class ItemForm < Apotomo::StatefulWidget
  def display
    respond_to_event :submit, :with => :create
 
    @todo = Todo.new
    render
  end
 
  def create
    @todo.update_attributes(param(:todo))
 
    render :view => :display
  end
end

The event handler (line 3) will execute the #create method when the form is submitted.

Nothing unusual happens there, I update the @todo and instruct the widget to render the former view display.html.haml.

6Entering some text into the form and pressing Submit yields the expected result! The new item gets saved.

However, the list doesn’t update so we can not see what we did. We should implement some notification so the list updates when there was a new item created.

That’s what we’re gonna do in the next lesson, the 12 minutes are over!

In every Rails app is some reoccurring element.

In my blog example, this is a small teaser box (to the right!) showing a snippet from the newest post, and a footer section that provides a link to the article.

However. My imaginary blog also has a page about RubyFlow where I’d list the links I posted there, just to proof how cool I am.

On the RubyFlow page, I don’t want the teaser to show a link to the article, but a red button to RubyFlow. Of course, this doesn’t make sense at all.

My god, I hate that red in combination with the pink on this site.

The medieval if-cascade

Things like that are usually implemented in the partial with some if/else part.

if @current_page == 'rubyflow'
  Don't read it, better go to rubyflow
else
  = link_to "Read it!", "/blog/read/#{@post.id}"

Pretty ugly.

Things start getting really ugly when there are more conditions to respect and end up in a medieval if-cascade. It’s geting even worse when those deciders are copied and spread across multiple files.

How we do it

Cells brings back the power of OOP to your views. It offers a feature called View Inheritance that saves us here. I will briefly discuss that while showing you how I implemented the different teasers.

$ script/generate cell teaser box body footer --haml
      create  app/cells/teaser_cell.rb
      create  app/cells/teaser/box.html.haml   
      create  app/cells/teaser/body.html.haml
      create  app/cells/teaser/footer.html.haml

The TeaserCell has three states that don’t do much right now.

1
2
3
4
5
6
7
8
9
10
11
12
13
14

class TeaserCell < ::Cell::Base
  def box
    @post = Post.find :first
    render
  end
 
  def body
    render
  end
 
  def footer
    render
  end
end

Just grabbing the newest post in line 3.

Nesting states

I use the box state as a container. It renders the body and footer in its view app/cells/teaser/box.html.haml.

#teaser
  %h3
    Nick says
 
  .body
    = render :state => :body
  .footer
    = render :state => :footer

That’s right, I use render :state in a cell view. That’s somehow comparable to rendering a partial, although it first executes the #body method, which in turn renders its view.

That’s how the teaser currently looks like as we didn’t customize the body and footer view, yet.

It is pretty obvious that our body view should print out the teaser text, whereas the footer displays the link.

app/cells/teaser/body.html.haml

%h2 #{@post.title}
%p  #{@post.body}

And the footer in app/cells/teaser/footer.html.haml.

= link_to "Read it!", "/blog/read/#{@post.id}"

Enriching the controller

In the blog view I then call #render_cell to integrate the teaser in my blog ERB page.

<div id="right_menu">
  <%= render_cell :teaser, :box %>
</div>

Ok, so now we got a beautiful teaser in the blog page. How do we get that teaser to show a red button on the RubyFlow page?

Inheritance strikes again!

The answer is - unsurprisingly: we derive a new RubyflowTeaserCell from the TeaserCell.

$ script/generate cell rubyflow_teaser footer --haml
      create  app/cells/rubyflow_teaser_cell.rb
      create  app/cells/rubyflow_teaser/footer.html.haml

The actual inheritance happens in the class.

class RubyflowTeaserCell < TeaserCell
end

Note that we don’t need any methods as they all come from TeaserCell. The same applies to the views, they’re inherited as well!

But wait, we planned on overwriting the footer so here’s how the app/cells/rubyflow_teaser/footer.html.haml looks like.

Don't read it, better go to
%span rubyflow

In the Rubyflow controller view I add the cells rendering.

<div id="right_menu">
  <%= render_cell :rubyflow_teaser, :box %>
</div>

That’s a call to RubyflowTeaserCell. Now, what happens here.

• the derived RubyflowTeaserCell calls the #box method which is inherited
• as the respective view is not found in app/cells/rubyflow_teaser it is looked up in the parent directory app/cells/teaser/ and found
• the same happens with the :body state
• when rendering the footer, the view is found in the cells own view directory and thus not inherited

Conclusion

View inheritance comes into play whenever complex deciders threaten the straightforwardness of your view code. When you encounter if-cascades with more than two ifs, think about using a cell with inheritance there.

Code?

The example code can be found at github.

However, we got some Rails bindings now.

If you’re not yet familiar with ActiveHelper, no problem, it’s brandnew. Consider skimming the introducing post first. Or directly jump to the github repository.

Writing the helper

Let’s assume you want to create a new helper to replace the #link_to method. Why not name it LinkingHelper?

class LinkingHelper < ActiveHelper::Base
  provides :link_for
 
  def link_for(title, url)
    '<a href="' + url + '">' + title + '</a>'
  end
end

You’d put this into app/active_helpers/linking_helper.rb.

Preparing the controller

Bla bla bla, it’s obvious how to use ActiveHelpers in controllers.

class BlogController < ActionController::Base
  active_helper LinkingHelper
 
  def show
    @post = Post.find params[:id]
  end
end

Helping the view

As soon as the controller did include the LinkingHelper its provided methods are around in the view.

1
2
3
4
5
6

Bookmarkable link: <%= link_for @post.title, @post.url %>
 
<h1><%= @post.title %></h1>
<p>
  <%= @post.body %>
</p>

You used your #link_for to generate a link in line 1.

So… where’s the benefit?

Being a good programmer you instantly decide to extract the markup logic from the LinkingHelper to some separate MarkupHelper.

The latter would provide a method #tag for generating markup.

Your former helper now looks like this.

1
2
3
4
5
6
7

class LinkingHelper < MarkupHelper
  provides :link_for
 
  def link_for(title, url)
    tag(:a, title, :href => url)
  end
end

Noticed the inheritance in line 1? Wow- that’s OOP features in helpers. Nice.

Reusing old-school helpers

Now what if you still want to use #url_for to setup the link address? It’s hidden somewhere in Rails gloomy mixin magic.

You know it’s floating around in your view. So go and use it.

1
2
3
4
5
6
7
8
9

class LinkingHelper < MarkupHelper
  provides :link_for
  needs :url_for
 
  def link_for(title, url)
    url = url_for(url)
    tag(:a, title, :href => url)
  end
end

Step-by-step, dude. You simply use #url_for in line 6. Your helper knows about it since you defined the dependency (line 3).

That’s gonna work- but… why?

Well, any ActiveHelper simply delegates dependencies back to where it was imported into. In our case, any call to #url_for is routed to the ActionView instance which has to care about that.

Delegation for a better world

The new keywords in the Helper World are delegation and interfaces.

Besides that, we got back OOP and inheritance to helpers.

Lemme end this boring post by quoting Manuel who’s just diving into ActiveHelpers.

It’s funny- ActiveHelpers is nothing more than 80 lines of code. Anyway, it’s forcing you to write clean code… in a gentle way!

Isn’t that great?

A couple of guys (including mislav himself) told me to make the pagination unobstrusive, so here’s how i did this.

You’re gonna learn how to

• pack unobstrusive JavaScript in Apotomo widgets
• use Helpers in widgets
• configure your widget view with #render

1I didn’t have any clue what unobstrusive JavaScript refers to. It means “separating JavaScript and markup”. After lots of tries, I figured out how to let will_paginate handle the markup and do the JS part myself.

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

%h3 Things
%p
  = page_entries_info @items
 
%ul
  - @items.each do |item|
    %li
      = item.text
 
= will_paginate @items
 
- javascript_tag do
  $(document.body).observe('click', function(e) {
  var el = e.element()
 
  if (el.match('.pagination a')) {
  page = el.href.split("page=").last(); // I don't know how to do it better.
  = "new Ajax.Request('#{url_for_event(:paginate)}'+'&page='+page, { method: 'get' })"
 
  e.stop()
  }})

Instead of modifying will_paginate's output (line 10) I add an observer that triggers the :pagination event (line 13).

I have to extract the page from the element href, that’s a little bit fiddling. Maybe someone can tell me how to do it better (line 17)?

The interesting part here is the call to #url_for_event (line 18). It computes the url to trigger the paginate event, which happens in Ruby!

That works. After clicking a page, the widgets updates itself via AJAX.

2Anyway, I keeps adding observers as the widgets updates and re-injects the JS into the page over and over again. There are multiple solutions to the problem.

• Fix the JS to add the observer only once
• Use two different views in your widget, the initial one with, the following without the JS
• Write the JS to a global variable using #capture that’s evaluated only once when the page is rendered completely

Personally I hate using global variables (that’s what #capture does). I will use it anyway cause it shows a few interesting concepts.

3We need to render the JavaScript to the page footer.

Cells provide a view method #global_capture for sending local content to the global controller view. That’s not nice. Widgets shouldn’t know anything about the global page.

Apotomo widgets are based on cells, so they may use that technique as well.

In the display.html.erb view

...
- global_capture :ujs do
  - javascript_tag do
    $(document.body).observe('click', function(e) {
...

I embed the #javascript_tag into #global_capture that saves the whole block to the global view’s instance variable @ujs, which is a brutal interface violation.

In the app’s views/layouts/application.html.erb I have to render @ujs in order to embed the JavaScript into the page only once. I still hate myself for doing that.

  </body>
  <%= @ujs %>
</html>

That’s all for the markup.

4 The #global_capture method is not automatically available in the widget view, it’s provided by a helper, so let’s introduce it to our view.

class ItemList < Apotomo::StatefulWidget
  helper Cells::Helpers::CaptureHelper
 
  def display
  #...

That looks like in a controller. Note that you can use #helper to pull any helper in your widget view.

5Ok, the paging is working in some unobstrusive way. I’m still not sure if unobstrusive JavaScript is something I like.

What I like is CSS and how it can help us to beautify elements without adding obstrusive CSS.

To add a background to our item list I add a css class to it’s surrounding div.

1
2
3
4
5
6
7
8
9
10
11

class ItemList < Apotomo::StatefulWidget
  helper Cells::Helpers::CaptureHelper
 
  def display
    respond_to_event :paginate, :with => :display
 
    @items = Todo.paginate :page => param(:page), :per_page => 10, :order => 'created_at DESC'
 
    render :html_options => {:class => 'lined'}
  end
end

All I need is adding :html_options to the #render invocation (line 9), this will add the attributes to our list. Obviously I also added some class to the CSS document, but that’s not part of this course. My CSS-skills suck.

6Let’s view our page again.

Looks cooooool, doesn’t it?

I’d love to see some JS fix to prevent the usage of #global_capture. Or do you like it? It’s a common technique in Rails, though. Doesn’t mean that this is a good thing.

In the next lesson we’ll add an interactive form to add Todo items which processes and updates like the list widget, via AJAX and superfast.

• a missing method that should be included in the helper already, but isn’t
• an undefined method for nil:NilClass

target = Object.new
target.extend ActionView::Helpers::UrlHelper
target.url_for('/fix/me')
 
#=> url_helper.rb:94:in `url_for': undefined method `escape_once' for #<Object:0xb7496300> (NoMethodError)

That’s due to dependencies between different helpers and the instances they’re mixed into.

Wrapping the UrlHelper

I’m gonna explain how ActiveHelper can help solving this problem by wrapping the UrlHelper step-by-step.

This will make the UrlHelper a predictable, well-behaving class. Helpers should be good kids, nothin’ more.

Here’s a first version for the new helper.

module Rails
  class UrlHelper < ActiveHelper::Base
    include ActionView::Helpers::UrlHelper
 
    provides :url_for, :link_to, :button_to # add more if you need.
  end
end

We derive the new helper from ActiveHelper::Base, include the original module and define our interface with provides.

A rails scenario setup

In Rails, this is what roughly happens when a view is rendered.

controller = ActionController::Base.new
view       = ActionView::Base.new([], {}, controller)
 
view.extend ActiveHelper
view.use Rails::UrlHelper

Usually the use call would happen in the controller’s action processing, or in #render.

view.url_for('fix/me')
# => url_helper.rb:85:in `send': undefined method `url_for' for nil:NilClass (NoMethodError)

Ok, send is accessing nil. Let’s inspect the original helper.

  def url_for(options = {})
    ...
    @controller.send(:url_for, options)

The rails helpers blindly accesses an instance var @controller, it simply assumes the instance it is mixed into does provide it.
Even worse, it uses send to invoke a method on the controller. That’s one of rails major drawbacks and must be fixed.

Providing the @controller

Unfortunately, we won’t touch the original UrlHelper and open pandora’s box.

Remember, we got a helper instance which mixed-in the original UrlHelper module. That means we’d just have to provide the @controller instance variable in our helper instance.

module Rails
  class UrlHelper < ActiveHelper::Base
    include ActionView::Helpers::UrlHelper
 
    provides :url_for, :link_to, :button_to # add more if you need.
 
    def initialize(*args)
      super(*args)
      @controller = parent.controller
    end

We setup an ivar @controller by accessing parent, that’s the object which is using us, so it’s the ActionView and that itself does provide a public accessor to its controller.

Fixing another helper dependency

Not nice, but anyway, cleaner than things were before.

view.url_for('fix/me')
url_helper.rb:94:in `url_for': undefined method `escape_once' for #<Rails::UrlHelper:0xb747b794> (NoMethodError)

Oh. #escape_once is needed in rails’ original helper, too. I will spare the details about the code now, the method is defined in TagHelper. However it is not mixed in UrlHelper. Shitty helpers.

That’s another broken dependency we’ll have to fix.

We now have three possibilities

• we could wrap TagHelper in an ActiveHelper as well, and derive UrlHelper
• wrapping and use‘ing it inside UrlHelper would be the second solution
• or simply include the original module, hoping all will go well

For now I’ll choose the third, anyway, that’s far from good architecture.

module Rails
  class UrlHelper < ActiveHelper::Base
    include ActionView::Helpers::UrlHelper
    include ActionView::Helpers::TagHelper
 
    provides :url_for, :link_to, :button_to # add more if you need.
 
    def initialize(*args)
      super(*args)
      @controller = parent.controller
    end

Let’s see if it works.

view.url_for('fix/me') #=> "fix/me"
view.button_for('fix/me')
#=> url_helper.rb:298:in `button_to': undefined method `protect_against_forgery?' for #<Rails::UrlHelper:0xb74a7eac> (NoMethodError)

Now what’s that again? Looks as if #button_for needs protect_against_forgery?.

Delegating dependency to the ActionView

Let’s express that dependency.

module Rails
  class UrlHelper < ActiveHelper::Base
    include ActionView::Helpers::UrlHelper
    include ActionView::Helpers::TagHelper
 
    provides :url_for, :link_to, :button_to # add more if you need.
 
    needs :protect_against_forgery?
    ...

Having that defined, calls to protect_against_forgery? will be delegated back to the view. That should work.

view.button_for("Click me!", 'fix/me')
#=> <form method="post" action="fix/me" class="button-to"><div><input type="submit" value="Click me!" /></div></form>

Yeah!

Where to go from here?

Now that you know how easy it is to clean up the Rails helpers (or Merb, or …!!!), go and do it. I’d love to see ActiveHelper being used to replace nasty modules and bringing back the power of OOP to your views.

When I was prototyping a new JavaScript generator library using Rails’ helpers I came to a conclusion: Helpers suck.

Typically helpers in ruby frameworks are implemented as simple modules. However, despite the word simple, they suffer from two problems:

• Dependency helper modules assume there are other helpers mixed into the target and blindly use foreign methods
• Dependency helper modules rely on instance variables from the target they were mixed into.

ActiveHelper - An example

ActiveHelper puts helpers back to where they belong: classes.

Here’s how a typical MVC helper would look like with ActiveHelper. And, hey, if this is too brief, go and check out the README.

class View
  include ActiveHelper
 
  def https_request?; false; end
end

We have an exemplary View class that knows if an HTTP request is secure or not.

use

The include pendant for helpers and target instances is use.

> view.use FormHelper

The instance can use a helper to gain he-man’s form building capabilities.

class FormHelper < TagHelper
  provides :form_tag
  uses UrlHelper
 
  def form_tag(destination)
    destination = url_for(destination)  # in UrlHelper.
    tag(:form, "action=#{destination}") # in TagHelper.
  end
end

provides

The FormHelper exposes its interface as it provides a method #form_tag that itself uses two foreign methods #tag and #url_for.

The #tag method is simply inherited from the TagHelper, which provides :tag again. See the inheritance?

The latter, #url_for, is implemented in UrlHelper, so the form lib references that dependency when it uses the required helper.

needs

Let’s look into that url thing helper.

class UrlHelper < ActiveHelper::Base
  provides  :url_for
  needs     :https_request?
 
  def url_for(url)
    protocol = https_request? ? 'https' : 'http'
    "#{protocol}://#{url}"
  end
end

You already got it, don’t you?

The UrlHelper relies on a mysterious method #https_request?. There is no magical inclusion somewhere. As soon as it needs a method an accessor will be created delegated all calls to the View instance, which was the target.

Handling dependencies

So it’s the importing instance that has to handle methods declared with needs.

If the view wouldn’t expose the required method, it would be like

> view.form_tag('apotomo.de')
# => 11:in `url_for': undefined method `https_request?' for #<View:0xb749d4fc> (NoMethodError)

which is a clear, debugable issue.

Come on!

The approach found with ActiveHelper is completely generic, not bound to a specific framework like Rails, Merb or Sinatra. It may (and should!) be used in order to make helpers cleaner, use OOP features and make them easier to debug.

What’s your impression, what’s your problems and experiences with helpers? Don’t be shy, tell us!

Curious about the source? Check out my repository at the github, trans.

Cheers!

• limiting the amount of items will help keeping the UI clean
• using will_paginate proofs that helpers in widgets are just like helpers in controllers
• switching to AJAX pagination will touch Apotomo’s simple event handling

1Limiting the item list means limiting the #find operation in our list widget.
app/cells/item_list.rb

class ItemList < Apotomo::StatefulWidget
  def display
    @items = Todo.paginate :page => param(:page), :per_page => 10, :order => 'created_at DESC'
 
    render
  end
end

That’s dead simple, we just exchanged #find with #paginate. Accessing request parameters can happen with params[], however, in widgets it’s a good practice to stick to #param.
The later prevents you from accessing parameters not bound to your widget.

2 Obviously we need to fix our view as well, as pagination only makes sense when we got buttons to switch pages.
app/cells/item_list/display.html.haml

%h3 Things
%p
  = page_entries_info @items
 
%ul
  - @items.each do |item|
    %li
      = item.text
 
= will_paginate @items

When viewing our page, we got a basic paging list, clicking a page button issues a new request.

3That works (tag 0.4), but it’s not the concept behind widgets. Widgets usually want to update via AJAX to save load time and to assure proper encapsulation.

Why should we reload the whole page for updating a single list? That’s overhead!

Keeping that in our collective mind we should add ajaxed buttons.

4Unfortunately will_paginate doesn’t provide a simple way to change the rendering of links (what about some block that’d define the link markup, mislav?) so we’re goin’ that way by foot.

app/cells/item_list/display.html.haml

1
2
3
4
5
6
7
8
9
10
11

%h3 Things
%p
  = page_entries_info @items
 
%ul
  - @items.each do |item|
    %li
      = item.text
 
- (1..@items.total_pages).each do |page|
  = link_to_event "|#{page}| ", :paginate, :page => page

We still use the handy #page_entries_info in line 3. To generate the page list we iterate through all available pages (line 10) calling a yet fameless method #link_to_event.

5 The small helper method creates linked page numbers (|1| |2|). When clicking, nothing happens.

Well, you just fired an event! Looking at firebug’s XHTTP tracking, a :paginate event is triggered in the 'dashboard_list'. That’s our baby!

6Alright, so let’s handle this event. In Apotomo, triggered events can be observed, maybe we should try that.

1
2
3
4
5
6
7
8
9

class ItemList < Apotomo::StatefulWidget
  def display
    respond_to_event :paginate, :with => :display
 
    @items = Todo.paginate :page => param(:page), :per_page => 10, :order => 'created_at DESC'
 
    render
  end
end

Another apotomo’ed method, #respond_to_event, instructs our list to run the #display state again when it encounters the :paginate event (line 3).

After clicking a page link the updated list appears instantaneously. At the right place. Suuuperfast. Via AJAX. That means:

• the :paginate event is triggered
• it’s catched by our list widget using #respond_to_event
• the list invokes the #display method again
• the new content replaces the old content, automatically

Cool.

But there’s more.

In the next lessons we’ll polish our list view and add another widget for posting new items. Hope to see you, guys! COMMENT.

In this tutorial we’re going to model and implement a small todo application, namely dumdidoo, which saves and displays things you have to do.

1 It’s on github, so go and get it. Be sure to change to the 0.1 tag, so you’re at the very beginning of our exciting way.

$ git clone git://github.com/apotonick/dumdidoo.git
$ cd dumdidoo/
$ git submodule init
$ git submodule update
 
$ script/server

When browsing to http://localhost:3000/dashboard you see the raw view of the #index action in the DashboardController.

2Luckily, I already provide you with some Todo model and random items in the database. What about some list widget to show the items?

$ script/generate widget item_list display --haml
      create  app/cells/
      create  app/cells/item_list
      create  test/widgets
      create  app/cells/item_list.rb
      create  app/cells/item_list/display.html.haml
      create  test/widgets/item_list_test.rb

Just telling the widget generator to create things for me. It spits out the widget class in app/cells/item_list.rb and a bare view for the display state.

In Apotomo a widget is like a controller in Rails, and a state is similar to an action. The standard state of a widget is usually #display, that’s somehow matching to the index action in a controller.

So if you look into the widget class and view files you’ll see they look like good old controllers!

3To plug the widget into a page we have to work in the controller.

1
2
3
4
5
6
7
8
9

class DashboardController < ApplicationController
  include Apotomo::ControllerMethods
 
  def index
    use_widgets do |root|
      root << widget(:item_list, 'dashboard_list')
    end
  end
end

In Apotomo, widgets are organized in a tree. The #use_widgets method yields this ominous root node, and we attach a widget of type item_list to it, identified by ‘dashboard_list‘.

We need the id to render that widget.

app/views/dashboard/index.html.erb

<h2>Dashboard</h2>
 
<%= render_widget 'dashboard_list' %>

Ok, so we can call #render_widget in controller views to render widgets that we defined earlier with #use_widgets. Widgets, widgets, widgets…

When viewing the page, the widget’s default view appears within the controller’s view. That looks trivial, but, hey, you implemented your first widget! Congratulations!

4Now it’s time to extend this item_list widget and add functionality to list the items.

1
2
3
4
5
6

class ItemList < Apotomo::StatefulWidget
  def display
    @items = Todo.find :all
    render
  end
end

app/cells/item_list.rb

This will collect all the Todo items and push ‘em to an instance variable of our widget.

The render call without any arguments just looks for the corresponding view in app/cells/item_list/ (which is named after the state). In our case, it will find app/cells/item_list/display.html.haml.

Note that you could also have erb views, or builder, or whatever you prefer.

%h3 Things
 
%ul
  - @items.each do |item|
    %li
      = item.text

app/cells/item_list/display.html.haml

Widget views can access instance variables from its widget instance, just as you know that from ordinary controllers.

When browsing back to the page, we see the list of all Todo items!
Wow! You just learned how to implement encapsulated, reuseable components, and we’re at tag 0.3, yet.

5I was drunk yesterday. Today, I’m tired. I will stop here. Did it take you 12 minutes? No? Do you have questions already? Feel free to use the comments below.

Well, tomorrow we’re gonna extend the list, so it is pageable. We’re gonna use will_paginate for that and on top of that we’ll get AJAX paging. Exciting!

Apotomo is stateful widgets for Ruby and Rails that help you keep your code clean and enrich your user interfaces with components.

And what do we do?

We’re gonna develop a small Todo app dumdidoo with Rails that utilizes a bunch of nifty Web 2.0 features, including

• dashboards with slots for widgets
• tab panel and more popular elements for a user-friendly GUI
• drag&drop everywhere
• AJAX pagination, form processing and file uploads

Sounds cool, what else?

This is not a JavaScript tutorial, it is all Ruby! From a software developer’s point-of-view you’re gonna learn about

• UI design with widgets
• component-oriented architecture
• event triggering in the browser and in your Ruby code
• event mapping from JS to Ruby
• statefulness and persistence vs. traditional Rails controllers
• unit- and functional tests for components
• YUI controls integration in your Rails app with Apotomo’s YUI widgets

Can we go?

The first lesson is right here.

And, please…

Open your mouth and post questions so we can discuss obscure things in the next lection. Also, don’t be shy and post “feature requests” (what you’d like the app to do) cause I need to know what you guys want.

We can implement proposed features in one of the following lessons.

Looking forward to the trip!

Bubbling events is, in contrast to Ruby’s own Observable module, focused on observing events triggered by business objects, not watching the objects themselves.

In addition, a triggered event will bubble up the tree branch and subsequently inform all ancestors- you get automatic organic event filtering.

Complete instructions are on the github page.

Let’s see how it works.

> require 'rubygems'
> require 'onfire'
> class Object
>   include Onfire
>   attr_accessor :parent
> end

Bubbling events only make sense in a tree structure. That’s why Onfire has one requirement to the class it’s mixed into- #parent.

ruby = Object.new
 
ruby.on :syntaxError do |event| puts "ruby: omg, a syntax error in #{event.source}" end
ruby.fire :syntaxError
# => ruby: omg, a syntax error in #<Object:0xb75a087c>

That was simple, Observable can do this, too.

Appending a method

Now let’s add a method object to ruby.

method = Object.new
method.parent = ruby
 
method.on :syntaxError do |event| puts "method: a syntax error in ME?" end
method.fire :syntaxError
#=> method: a syntax error in ME?
#=> ruby: omg, a syntax error in #<Object:0xb756dd00>

The event bubbles. What about some variable in the method?

variable = Object.new
variable.parent = method
 
variable.on :syntaxError do |event| puts "variable: I am the problem." end
variable.fire :syntaxError
#=> variable: I am the problem.
#=> method: a syntax error in ME?
#=> ruby: omg, a syntax error in #<Object:0xb756dd00>

Extending the tree model

Maybe there’s another method attached to ruby.

method2 = Object.new
method2.parent = ruby
 
method2.on :syntaxError do |event| puts "method2: Whoops, something here is wrong." end

Now if variable fires, method2 shouldn’t be informed. Remember, the variable is in method.

variable.fire :syntaxError
#=> variable: I am the problem.
#=> method: a syntax error in ME?
#=> ruby: omg, a syntax error in #<Object:0xb756dd00>

Works. That’s organic event filtering resulting from ascending event propagation.
The bubbling event from variable never hits method2 on its way up.

Stopping the event

What if method wants to intercept syntax errors in its scope, so ruby won’t get informed any further about errors in method?

method.on :syntaxError do |event| 
  puts "method: that's private things"
  event.stop!
end
 
variable.fire :syntaxError
#=> variable: I am the problem.
#=> method: a syntax error in ME?
#=> method: that's private things

The event stops in method.

And what if method2 contains errors?

method2.fire :syntaxError
#=> method2: Whoops, something here is wrong.
#=> ruby: omg, a syntax error in #<Object:0xb75348d4>

It still bubbles up to root. Yeah, makes sense, it’s a different tree branch.

More!

I told you, more examples, source filtering, bubbling, babbling, intercepting on the github. Have fun and let me know how it works for you!