By: Bruce Bahlmann - Contributing Author (your feedback is important to us!)

In rails development, you may have a need for visual widgets that can be easily created and arranged on a display. Fortunately, rather than building widgets from scratch, there is a framework available from Nick Sutterer that provides a nice foundation for doing this. Problem is, while Nick is an accomplished coder, the documentation around his examples will not yield a working prototype. Also, not being a huge fan of HAML, I keep everything in embedded ruby (erb).

Start by creating an apotomo widget example project in Rails. Name it what you want, but I prefer simple acronyms for describing code projects.

$ rails new awe -d mysql
	create
	...
	Fetching gem metadata from https://rubygems.org/.........
	...
	Your bundle is complete!...

[.gitignore]
# See http://help.github.com/ignore-files/ for more about ignoring files.
#
# If you find yourself ignoring temporary files generated by your text editor
# or operating system, you probably want to add a global ignore instead:
#   git config --global core.excludefile ~/.gitignore_global

#Ignore bundler config
/.bundle

# Ignore the default SQLite database.
/db/*.sqlite3

# Ignore all logfiles and tempfiles
/log/*.log
/tmp

/config/environments/
/config/database.yml
*.sw?

Update your project's Gemfile. I don't generally use SQLite, rather just stay with MySQL for everything which keeps things standard for all my development. The remainder of the Gemfile is what ever rails generates automatically.

[Gemfile]
source 'https://rubygems.org'

gem 'rails', '3.2.3'
gem 'mysql2'
gem 'apotomo'

Update your project's bundle.

$ bundle install

Create the model for our example. This model allows users to post and display posts - a poor man's twitter.

$ rails generate model tweet text:string
	invoke active_record
	create db/migrate/20120530200619_create_tweets.rb
	create app/models/tweet.rb
	invoke test_unit
	create test/unit/tweet_test.rb
	create test/fixtures/tweets.yml

$ rake db:create
$ rake db:migrate
== CreateTweets: migrating ========================
-- create_table(:tweets)
  -> 0.1663s
== CreateTweats: migrated (0.1664s) ===============

Create the controller which hosted widgets are usually embedded into.

$ rails generate controller dashboard index
	create app/controllers dashboard_controller.rb
	 route get "dashboard/index"
	invoke erb
	create app/views/dashboard
	create app/views/dashboard/index.html.erb
	invoke test_unit
	create test/functional/dashboard_controller_test.rb
	invoke helper
	create app/helpers/dashboard_helper.rb
	invoke test_unit
	create test/unit/helpers/dashboard_helper_test.rb
	invoke assets
	invoke coffee
	create app/assets/javascripts/dashboard.js.coffee
	invoke scss
	create app/assets/stylesheet/dashboard.css.scss

Create your first Apotomo widget. In this step we add the -e flag to use embedded ruby (erb), but if you are into it you can just as easily substitute HAML, only I find that format confusing.

$ rails generate apotomo:widget twitter display -e erb
	invoke erb
	create app/widgets/twitter/display.html.erb
	invoke test_unit
	create test/widgets/twitter_widget_test.rb
	create app/widgets/twitter_widget.rb

Perform some house cleaning, to set up rails to properly execute. This is probably common sense for seasoned rails people, but here just to be thurough.

$ rm public/index.html

Then update your routes to ensure rails knows how to get to your widget application. This configuration should be limited to modifying the root :to statement.

[config/routes.rb]
Awe::Application.routes.draw do

  get "dashboard/index"
  root :to => 'dashboard#index'
end

The remainder of this example involves the configuration of the project and widget to properly display. First we update the controller as follows:

[apps/controllers/dashboard_controller.erb]
class DashboardController < Application Controller

  has_widgets do |root|
    root << widget(:twitter)
  end

  def index
  end
end

Then we render the widget which is associated with the controller.

[app/views/dashboard/index.html.erb]
<h1>Twitter Dashboard</h1>
<div id="dashboard">
  <div class="column">
    <%= render_widget :twitter %>
  </div>
</div>

Then we configure the actual code to display the widget.

[app/widgets/twitter/display.html.erb]
<%= widget_div do %>
  <ul>
    <% for tweet in @tweets %>
      <li><%= tweet.text %></li>
    <% end %>
  </ul>
  <p> What are you up to?</p>
  <%= form_for :tweet, :url => url_for_event(:submit), :remote => true do |f| %>
    <%= f.text_field :text %>
    <%= f.submit 'Tweet!' %>
  <% end %>
<% end %>

[/app/widgets/twitter_widget.rb]
class TwitterWidget < Apotomo::Widget
  responds_to_event :submit, :with => :process_tweet

  def display
    @tweets = Tweet.all
    render
  end

  def process_tweet(evt)
    logger.debug "EVENT TEXT: #{evt[:tweet][:text]}"
    Tweet.new(:text => evt[:tweet][:text]).save

    @tweets = Tweet.all
    replace :view => :display
  end
end

Once all this is complete, all that is required is to run it. So, from the command line, launch rails built in web server (WEBrick).

$ rails s

Finally browse to your local rails web server.

http://localhost:3000

[Peter Roosakos] Apotomo Widget example using Erb - Great article, one of the few I've found that are clear, understandable, and actually work!

Can Birds-Eye.Net help you or your Company? Receive your Birds-Eye.Net articles and white papers hot off the presses by adding our RSS feed to your reader.

(C) Copyright Birds-Eye.Net, All rights reserved.
It is against the law to reproduce this content or any portion of it in any form without the explicit written permission of Birds-Eye Network Services, LLC. Federal copyright law (17 USC 504) makes it illegal, punishable with fines up to $100,000 per violation plus attorney's fees.