Typo Sidebar Tutorial
I’ve been playing around a bit with Typo, a Rails blogging program, recently. The main reason I chose Typo is because I wanted to add some news features to a golf league manager I’ve also written in Rails. Merging the two code bases is probably a bit much at this stage but I did want to add something to Typo to integrate the two. The best way to do is sidebar components. This is a brief tutorial on how to write a sidebar component. In my examples I’ll use the category sidebar from Typo.
There are three files you need to supply for a Typo sidebar component:
- typo/components/plugins/sidebars/category_controller.rb
- typo/components/plugins/sidebars/category/content.rhtml
- typo/components/plugins/sidebars/category/configure.rhtml
Replacing ‘category’ with the name of your sidebar component.
The controller file is where all the code goes, the other two files are the view parts for the admin (configure.rhtml) and public (content.rhtml).
Config Configuration for your component is stored in a Ruby Hash. It’s not necessary to create your own database table, the hash stored in a text column of the sidebars table. So all you need to worry about at the moment is the name of each field.
The configuration options of the category side bar are:
- count - Whether or not to show the number of pages in each category
- empty - Whether or not to show empty categories
category_controller.rb This class needs to extend ‘Sidebars::Plugin’, which does most of the work:
class Plugins::Sidebars::CategoryController < Sidebars::Plugin
def self.display_name
"Categories"
end
def self.description
"List of categories for this blog"
end
def self.default_config
{'empty' => false, ‘count’ => true }
end
def content
@categories = Category.find_all_with_article_counters
end
def configure
end
end
Most of it should be self explanatory. ‘displayname’ and ‘description’ is used in the sidebar admin page to identify your component. ‘defaultconfig’ needs to return a hash or the default values for your configuration options.
‘content’ and ‘config’ are like methods in normal Rails constructors and use to generate the data for your view. ‘content’ is the controller method for the public view. The category example simply loads all the categories from the database, but you obviously can do anything you can normally do in Rails. One thing I did noticed was that the ‘params’ object does not get filled with the URL parameters. I’ve raised this issue. Until it gets fixed you can pull the URL parameters from the request object, e.g.
sort = request.query_parameters['sort']
Sidebar::Plugin loads the config for you, so normally the ‘configure’ method can be empty.
configure.rhtml
<%= form_tag({},{:id => 'configure_'+@sidebar.id.to_s, :class=>'configblock'}) %>
<input type="checkbox"
id="configure_<%= @sidebar.id.to_s %>_count"
name="configure[count]"
<% unless @sidebar.staged_config['count'].blank? %>checked="checked"<% end %>/>
<input name="configure[count]"
type="hidden"
value="" />
<label for="configure_<%= @sidebar.id.to_s %>_count">Show article count</label><br/>
<input type="checkbox"
id="configure_<%= @sidebar.id.to_s %>_empty"
name="configure[empty]"
<% unless @sidebar.staged_config['empty'].blank? %>checked="checked"<% end %>/>
<input name="configure[empty]"
type="hidden"
value="" />
<label for="configure_<%= @sidebar.id.to_s %>_empty">Show empty categories</label>
<%= end_form_tag %>
<%=
observe_form "configure_"+@sidebar.id.to_s,
:url => { :action => "save_config", :id=>@sidebar.id},
:with => 'value'
%>
This is the form to edit the configuration options. It has to follow the boilerplate above. The only things you have to worry about are the INPUT tags, simply make sure the name attribute is configure[field_name].
You’ll noticed in the form about that there is also a hidden field matching each checkbox. This is because a value is only sent for a checkbox field if it’s checked. The empty hidden field guarantees something is always sent.
content.rhtml
<% unless @categories.blank? -%>
<h3>Categories</h3>
<ul id="categories">
<% for category in @categories -%>
<% unless @sb_config['empty'].blank? and category.article_counter == 0 %>
<li><%= link_to h(category.name),
:controller => "articles",
:action => "category",
:id => category.permalink %>
<% unless @sb_config['count'].blank? %>
<em>(<%= category.article_counter %>)</em>
<% end %>
</li>
<% end %>
<% end -%>
</ul>
<% end %>
The public view is the same as any other Rails view and is a combination of HTML and embedded Ruby. We don’t need to put anything special in this file to make it a sidebar component.
And that’s all there is to writing your own sidebar plugin.
