Web Components for Rails.
<img src=“https://secure.travis-ci.org/apotonick/apotomo.png” />
Do you need an interactive user interface for your Rails application? A cool Rich Client Application with dashboards, portlets and AJAX, Drag&Drop and jQuery?
Is your controller gettin’ fat? And your partial-helper-AJAX pile is getting out of control?
Do you want a framework to make the implementation easier? You want Apotomo.
Apotomo is based on Cells, the popular View Components framework for Rails.
It gives you widgets and encapsulation, bubbling events, AJAX page updates, rock-solid testing and more. Check out apotomo.de for a bunch of tutorials and a nice web 2.0 logo.
Easy as hell.
gem install apotomo
gem install apotomo -v 0.1.4
Don’t forget to load the gem in your app, either in your Gemfile or environment.rb.
A shitty example is worse than a shitty framework, so let’s choose wisely…
Say you had a blog application. The page showing the post should have a comments block, with a list of comments and a form to post a new comment. Submitting should validate and send back the updated comments list, via AJAX.
Let’s wrap that comments block in a widget.
$ rails g apotomo:widget comments show -e haml invoke haml create app/widgets/comments/views/show.html.haml invoke rspec create spec/widgets/comments/comments_widget_spec.rb create app/widgets/comments/comments_widget.rb create app/assets/stylesheets/widgets/comments_widget.css create app/assets/javascripts/widgets/comments_widget.coffee
Go and generate a widget TopBar stub.
$ rails g apotomo:widget TopBar show -e haml invoke haml create app/widgets/top_bar/views/show.html.haml invoke rspec create spec/widgets/top_bar/top_bar_widget_spec.rb create app/widgets/top_bar/top_bar_widget.rb create app/assets/stylesheets/widgets/top_bar_widget.css create app/assets/javascripts/widgets/top_bar_widget.coffee
And a Form widget within the TopBar namespace
$ rails g apotomo:widget TopBar::Form show -e haml invoke haml create app/widgets/top_bar/form/views/show.html.haml invoke rspec create spec/widgets/top_bar/form/form_widget_spec.rb create app/widgets/top_bar/form/form_widget.rb create app/assets/javascripts/widgets/top_bar/form_widget.coffee create app/assets/stylesheets/widgets/top_bar/form_widget.css
Note that the widget generator supports the following templating engines:
-
erb
-
haml
-
slim
Apotomo can also be used with engines. In your engine, simply run the apotomo engine_setup generator.
$ rails g apotomo:engine_setup my_cool create config/initializers/apotomo.rb
This will add the following initialization code
Rails.application.config.after_initialize do Apotomo::Widget.append_view_path MyCool::Engine.root + 'app/widgets' end
This instructs the Rails app hosting the engine to append this engine’s widgets path to the global list of apotomo widget paths.
You now tell your controller about the new widget.
class PostsController < ApplicationController
include Apotomo::Rails::ControllerMethods
has_widgets do |root|
root << widget(:comments, :post => @post)
end
This creates a widget instance called comments_widget from the class CommentsWidget. We pass the current post into the widget - the block is executed in controller instance context, that’s were @post comes from. Handy, isn’t it?
Rendering usually happens in your controller view, views/posts/show.html.haml, for instance.
%h1 @post.title %p @post.body %p = render_widget :comments
A widget is like a cell which is like a mini-controller.
class CommentsWidget < Apotomo::Widget
responds_to_event :post
def show(args)
@comments = args[:post].comments # the parameter from outside.
render
end
Having show as the default state when rendering, this method collects comments to show and renders its view.
And look at line 2 - if encountering a :post event we invoke #post, which is simply another state. How cool is that?
def post(evt)
@comment = Comment.new(:post_id => evt[:post_id])
@comment.update_attributes evt[:comment] # a bit like params[].
update :state => :show
end
end
The event is processed with three steps in our widget:
-
create the new comment
-
re-render the
showstate -
update itself on the page
Apotomo helps you focusing on your app and takes away the pain of action dispatching and page updating.
So how and where is the :post event triggered?
Take a look at the widget’s view show.html.haml.
= widget_div do
%ul
- for c in @comments
%li c.text
- form_for :comment, @comment, :url => url_for_event(:post), :remote => true do |f|
= f.error_messages
= f.text_field :text
= submit_tag "Don't be shy, comment!"
That’s a lot of familiar view code, almost looks like a partial.
As soon as the form is submitted, the form gets serialized and sent using the standard Rails mechanisms. The interesting part here is the endpoint URL returned by #url_for_event as it will trigger an Apotomo event.
Now what happens when the event request is sent? Apotomo - again - does three things for you, it
-
accepts the request on a special event route it adds to your app
-
triggers the event in your ruby widget tree, which will invoke the
#poststate in our comment widget -
sends back the page updates your widgets rendered
In this example, we use jQuery for triggering. We could also use Prototype, RightJS, YUI, or a self-baked framework, that’s up to you.
Also, updating the page is in your hands. Where Apotomo provides handy helpers as #replace, you could also emit your own JavaScript.
Look, replace basically generates
$("comments").replaceWith(<the rendered view>);
If that’s not what you want, do
def post(evt) if evt[:comment][:text].explicit? render :text => 'alert("Hey, you wanted to submit a pervert comment!");' end end
Apotomo doesn’t depend on any JS framework - you choose!
-
element(id)
-
update(id, markup)
-
replace(id, markup)
-
update_id(id, markup)
-
replace_id(id, markup)
Extras (jQuery only):
-
find_element(id, selector)
-
selector_for(var, id, selector)
Example usage:
“‘ruby top_item = selector_for(:top_item, widget_id, ’.item:first’) render js: top_item + append_to(:_top_item, markup)
Will select ‘.item:first` under the widget container element as a variable `_apo_top_item` and then append the markup to the DOM element(s) pointed to by that variable. “`
Inverse jQuery manipulation API
-
append_to(selector, markup)
-
prepend_to(selector, markup)
-
replace_all(selector, markup)
Normal jQuery manipulation API
-
update_text(id, selector, markup)
-
append(id, selector, markup)
-
prepend(id, selector, markup)
-
after(id, selector, markup)
-
before(id, selector, markup)
-
unwrap(id, selector)
-
wrap(id, selector, markup)
-
wrap_inner(id, selector, markup)
-
wrap_all(id, selector, markup)
-
remove(id, selector)
-
remove_class(id, selector, *classes)
-
add_class(id, selector, *classes)
-
toggle_class(id, selector, *classes)
-
toggle_class_fun(id, selector, fun)
-
empty(id, selector)
jQuery “get” functions
-
get_attr(id, selector, name)
-
get_prop(id, selector, name)
-
get_val(id, selector)
-
get_html(id, selector)
The first argument ‘id` is always optional. It is meant to be used to select the div for the widget. The `selector` then finds one or more elements within the widget to perform the action on.
These functions should be used sparingly, for _Proof of Concept_ only if possible. It is far better to have javascript asset files if possible (== non-intrusive javascript).
A non-intrusive approach could involve the use of:
-
widget_class_call(id, function, hash)
-
widget_call(id, function, hash)
Example:
‘widget_class_call ’TopBar’, :toggle_active, {item: ‘item:first’}‘
Will call a function on the widget class (or module):
“‘javascript Widget.TopBar.toggleActive({’item’: ‘item:first’}); “‘
‘widget_call ’Admin::TopBar’, :toggle_active, {item: ‘item:first’}‘
Will call a function on a particular instance of that widget!
“‘javascript Widgets.admin.topBar.toggleActive({’item’: ‘item:first’}); “‘
This ensures that all our javascript for a widget is nicely namespace contained.
In your ‘application.js` manifest file
“‘ //= require apotomo/namespaces “`
An alternative ‘apotomo/Namespace.js` is also available, which you might want to experiment with also.
In the ‘top_bar.coffee` file the following is generated for our convenience
“‘javascript Widget.TopBar = namespace(’Widget.TopBar’);
Widget.TopBar = {
// add widget functions here
foo: function(bar) {},
bar: function(foor) {}
} “‘
We can then implement clean non-intrusive, namespaced javascript functionality as follows:
“‘javascript Widget.TopBar = namespace(’Widget.TopBar’);
Widget.TopBar = {
update: function(item) {
'updated:' + item }
},
toggleActive: function(widget_id, options) {
item = options['item'];
// do some toggle magic!!!
$(widget_id).find(item).toggleClass('active');
}
} “‘
Note that you can use fx jQuery [extend](api.jquery.com/jQuery.extend/) to extend javascript widget functionality similar to modules (prototypical inheritance). There are many other powerful javascript libraries out there (fx Base2, Prototype.js, JS.Class) that can be used to great effect for OOP javascript with inheritance etc.
“‘javascript $.extend(Widget.admin.TopBar, Widget.TopBar); “`
Here we extended the ‘admin.TopBar` with base functionality from `TopBar` :)
Also see the Coffeescript section below to see how to use namespaces.
Coffeescript has built in [class structure](coffeescript.org/#classes). and [namespaces](spin.atomicobject.com/2011/04/01/namespace-a-coffeescript-nugget/).
Please also see:
-
[namespaced classes](stackoverflow.com/questions/8730859/classes-within-coffeescript-namespace)
-
[namespace.coffee](github.com/CodeCatalyst/namespace.coffee)
-
[oop coffee](www.gridlinked.info/oop-with-coffeescript-javascript/)
Here an appetizer :) replace animals with widgets and you get the idea…
“‘coffeescript namespace “samples.coffeescript.oop.abstract”
Animal :
class Animal
constructor : (@species, @isMammal=false) ->
return this
# NOTE: Animal must be defined BEFORE Dog # namespace “samples.coffeescript.oop.pets”
Dog :
class Dog extends samples.coffeescript.oop.abstract.Animal
constructor : (@name) ->
“‘
You should first require ‘namespaces`:
“‘ //= require apotomo/namespaces.min “`
When you generate a widget, the coffescript file for it should look like this:
‘rails g apotomo:widget TopBar show -e haml`
“‘coffeescript namespace “Widget”
TopBar :
class TopBar
constructor : (@widget_id = widget_id) ->
toggleActive: (options) ->
“‘
“‘coffeescript namespace “Widget”
TopBar :
class TopBar
constructor : (@widget_id = widget_id) ->
toggleActive: (options) ->
item = options.item
$(@widget_id).find(item).toggleClass 'active'
“‘
‘rails g apotomo:widget TopBar::SuperThang show -e haml`
“‘coffeescript namespace “Widget.topBar”
SuperThang :
class SuperThang extends Widget.TopBar
constructor : (@widget_id = widget_id) ->
createBottomBar : (widget_id) -> new BottomBar(widget_id)
createFooter : (widget_id) -> new Footer(widget_id)
# private variable declarations (aliases)
#
BottomBar = Widget.BottomBar
Footer = Widget.Footer
“‘
For an Ajax enabled page, you can create javascript widget instances in the ‘Widgets` namespace.
“‘coffeescript Widgets.thang = new Widget.topBar.SuperThang “
Then you can update an existing widget instance from your Widget (controller) using ‘call_widget` as follows:
“‘ruby call_widget :thang, :toggleActive, item: “.item:first” “`
Which will result in the statement:
“‘javascript Widgets.thang.toggleActive(’action’: “.item:first”); “‘
A render buffer can be used for the views like this:
render_buffer do |b| b.replace "##{widget_id}", :view => :display if invitation b.replace "section#invite", :text => "" end
Apotomo comes with its own test case and assertions to build rock-solid web components.
class CommentsWidgetTest < Apotomo::TestCase has_widgets do |root| root << widget(:comments, :post => @pervert_post) end def test_render render_widget :comments assert_select "li#me" trigger :post, :comment => {:text => "Sex on the beach"} assert_response 'alert("Hey, you wanted to submit a pervert comment!");' end end
You can render your widgets, spec the markup, trigger events and assert the event responses, so far. If you need more, let us know!
There’s even more, too much for a simple README.
- Statefulness
-
Deriving your widget from
StatefulWidgetgives you free statefulness. - Composability
-
Widgets can range from small standalone components to nested widget trees like complex dashboards.
- Bubbling events
-
Events bubble up from their triggering source to root and thus can be observed, providing a way to implement loosely coupled, distributable components.
- Team-friendly
-
Widgets encourage encapsulation and help having different developers working on different components without getting out of bounds.
Give it a try- you will love the power and simplicity of real web components!
Please visit apotomo.de, the official project page with lots of examples.
If you have questions, visit us in the IRC channel #cells at irc.freenode.org.
If you wanna be cool, subscribe to our feed!
Copyright © 2007-2012 Nick Sutterer <apotonick@gmail.com> under the MIT License