ruby script/plugin install http://progrium.com/svn/vforge/plugins/widgets/

Using Widgets
----------------
I’m really bad at coming up with clever examples for these things, so we’ll do a sort of “Hello, world” and I’ll leave it up to you to do something useful with them. We’ll call our widget “text/yell_banner,” imagining we have a lot of simple text related widgets or something.

To keep things simple, we define widget logic inside helper modules. In this case, we’ll use the ApplicationHelper module, but you can put them in any helper module. You need to include Widgets in the module to define widgets, and I find the include useful as a separator between your helper methods and widget definitions if you have both.

module ApplicationHelper
  include Widgets
	
  widget 'text/yell_banner' do |params|
    # process the parameters into local variables for the template
    yell_text = params[:text].upcase
	
    # return a hash used for the template variables
    {:text => yell_text}
  end
end

Like actions, widgets really don’t need to be big clunky classes like you might find in other, um, more verbose languages. However, method names are a bad place to represent hierarchy, and modules are a bit much. Since the idea is that a widget maps directly to a template, we might as well use the actual template path string as its name.

Our template will be ridiculously simple, and should be at app/views/widgets/text/yell_banner.rhtml

< h1><%= text %>< /h1>

Rendering the widget is the best part. From another view, you can call:

<%= render :widget => 'text/yell_banner', :text => 'Hello, world!' %>

It’s very similar to rendering a partial, only a little less verbose. After the widget name, you can just specify parameters that will get passed to the widget definition.

Actually, if you don’t have a widget definition, the parameters will just be passed along to the widget template as locals, assuming you have a template file by that name under the widgets directory. Of course, that wouldn’t be making the best use of widgets. Widgets are good when there’s lots of presentational information processing to do before rendering a template, which happens a lot when you want to create parameterized UI components.

There is currently no advanced documentation for this plugin.