Write your own Typo sidebar

Posted by Piers Cawley Sun, 16 Apr 2006 17:19:00 GMT

If you’ve been following typo development on the trac you’ll have seen that I’ve been niggling away at the Typo sidebar system and I haven’t finished with it yet. The changes waiting in my current SVK repository are rather substantial so I’m going to give you a preview of them here.

Why mess with sidebars?

Well, in the past, developing a sidebar required you to sling a bunch of boilerplate code in with the code that actually did stuff, which violates the DRY principle in all sorts of horrible ways. Also, the boilerplate code we were using breaks with IE6.

Sidebars have two ‘sides’ (a little like Apple’s Dashboard widgets, but without the cool/annoying graphic effects when you switch between the config and content views). Most of the ugliness for the developer being found on the configuration side.

Here’s how a configure.rhtml file used to look:

<%= form_tag({},{:id => 'configure_'+@sidebar.id.to_s, :class=>'configblock'}) %>
  <input type="checkbox" id="configure_<%= @sidebar.id.to_s %>_show_count" name="configure[show_count]"<% if @sidebar.staged_config['show_count'] %> checked="checked"<% end %> />
  <label for="configure_<%= @sidebar.id.to_s %>_show_count">Show article count</label><br />
  <label for="configure_<%= @sidebar.id.to_s %>_count">Number of months</label>
  <input class="text" type="text" id="configure_<%= @sidebar.id.to_s %>_count" name="configure[count]" value="<%=h @sidebar.staged_config['count'] %>" />
<%= end_form_tag %><%= form_tag({},{:id => ’configure_’+@sidebar.id.to_s, :class=>’configblock’}) >

  <input type="checkbox" id="configure_<= @sidebar.id.to_s >show_count" name="configure[showcount]"< if @sidebar.staged_config[‘show_count’] > checked="checked"< end > />

  <label for="configure_<= @sidebar.id.to_s >show_count">Show article count</label><br />

  <label for="configure<= @sidebar.id.to_s >count">Number of months</label>

  <input class="text" type="text" id="configure<= @sidebar.id.to_s >_count" name="configure[count]" value="<=h @sidebar.staged_config[‘count’] >" />

<= end_form_tag %>
<%= observe_form "configure_"+@sidebar.id.to_s, 

    :url => { :action => "save_config", :id=>sidebar.id},
    :with =&gt; 'value'
 %&gt;</span></span></notextile></pre></div>
You'd be hard pressed to call it 'pretty' wouldn't you? The @form_tag and observe_form stuff is just boilerplate, repeated in every single configuration form.
Here’s what it looks like in trunk typo (until I check in my latest changes):

<input type="checkbox" id="configure_<%= @sidebar.id.to_s %>_show_count" name="configure[<%= @sidebar.id.to_s %>][show_count]"<% if @sidebar.config['show_count'] %> checked="checked"<% end %> />
<label for="configure_<%= @sidebar.id.to_s %>_show_count">Show article count</label><br />
<label for="configure_<%= @sidebar.id.to_s %>_count">Number of months</label>
<input class="text" type="text" id="configure_<%= @sidebar.id.to_s %>_count" name="configure[<%= @sidebar.id.to_s %>][count]" value="<%=h @sidebar.config['count'] %>" />


Still not pretty, but at least we’ve got rid of some boilerplate.
Here’s what it will look like once I’ve checked in the latest changes:

Yup, I’ve got rid of it.
Well, I haven’t got rid of it, I’ve moved it, the sidebar still needs to be configured. So, I’ve changed the sidebar controller class. Here’s how ArchivesController (the sidebar controller that that config view belonged to) used to look:

class Plugins::Sidebars::ArchivesController < Sidebars::ComponentPlugin
  def self.display_name
    "Archives"
  endclass Plugins::Sidebars::ArchivesController < Sidebars::ComponentPlugin

  def self.display_name

    "Archives"

  end
def self.description
‘Displays links to monthly archives’
end
def self.default_config
{‘count’ => 10, ‘show_count’ => true}
end
def content
…
end
def configure
end
end

And here’s how my local version looks:
class Plugins::Sidebars::ArchivesController < Sidebars::ComponentPlugin
  description 'Displays links to monthly archives'
  setting :show_count, true, :label => 'Show article counts', :input_type => :checkbox
  setting :count,      10,   :label => 'Number of Months'


  def content
    ...
  end
end
I’ve hidden content behind an ellipsis, but even that’s neater now, declaring a setting creates an accessor method for it, so rather than write @sb_config['show_count'], you can write show_count and be done with it (it’s declared as a helper method too, so it’ll work in your content.rhtml).
Getting rid of the form_tag/observe_form stuff broke pretty much every third party sidebar and there was no way of avoiding it. This change is backwards compatible though. If you have a sidebar that works with trunk rails today, it should continue to work with trunk rails tomorrow. But if you’re about to write a new sidebar, I strongly suggest using the new style.
If I get my act together, I hope to write a slightly more in depth tutorial on making a new style Typo sidebar, and maybe even providing a sidebar generator.