Creating Plugins

A Thoth plugin is really just a Ruby module that lives in the Thoth::Plugin namespace. Plugins can be distributed as RubyGems or you can just drop them into a /plugin directory under your Thoth home directory.

When you call a method like Thoth::Plugin::Foo.bar from a view (or even from another plugin), Thoth first looks for a file named thoth_foo.rb in the /plugin directory. If it doesn’t find the file, then it looks for a gem named thoth_foo. Once found, the plugin will be loaded automatically. It couldn’t be any easier.

Writing a Plugin

Let’s write a simple plugin that grabs the last five status updates from someone’s Twitter feed and returns them in an array.

Create a file in your /plugin directory named thoth_twitter.rb and open it in your favorite text editor.

Here’s the plugin code in its entirety (yes, this is really all of it):

require 'json'
require 'open-uri'

module Thoth; module Plugin
  module Twitter

    def self.recent_tweets(user)
      url = "http://twitter.com/statuses/user_timeline/#{user}.json?count=5"
      JSON.parse(open(url).read).collect {|item| item['text']}
    end

  end
end; end

Calling a Plugin

It’d be nice to have your recent tweets displayed just above the first blog post on your blog’s index page, don’t you think? Let’s make that happen. If you’ve read the Creating custom themes guide, you probably already have some idea of what to do now, but I’ll reiterate just to make sure.

First, create a new directory under your Thoth home directory to hold your custom views, then copy the default view/index.rhtml file into it, since that’s the file you’ll want to modify. If you’re not sure where the default views are, run thoth --help to find out.

mkdir -p ~/mysite/custom/view
cp /path/to/default/view/index.rhtml ~/mysite/custom/view/

Now open ~/mysite/custom/view/index.rhtml in your text editor. It should look something like this:

<% @posts.all do |post| %>
  <%= render_template('post/compact', :post => post) %>
<% end %>

<%=
render_template(:pager,
    :prev_text => '&laquo; Newer stuff',
    :next_text => 'Older stuff &raquo;')
%>

That loop up at the top is what displays the blog posts. Add your new Twitter feed just above it, like so:

<div id="twitter">
  <ul>
    <% Thoth::Plugin::Twitter.recent_tweets('yourname').each do |tweet| %>
      <li><%= tweet %></li>
    <% end %>
  </ul>
</div>

<% @posts.all do |post| %>
  <%= render_template('post/compact', :post => post) %>
<% end %>

<%=
render_template(:pager,
    :prev_text => '&laquo; Newer stuff',
    :next_text => 'Older stuff &raquo;')
%>

Save the file, restart Thoth, browse to your site, and you should see a lovely Twitter feed staring back at you. Well, maybe not lovely since we haven’t added any styles for it, but at least it works. How easy was that?

The Sky’s the Limit

This is obviously a very basic example just to get you started; there’s virtually no limit to what you can do with plugins. Your plugins have the full power of Ruby at their disposal. And since Ruby allows you to modify other classes at runtime, you can even override pieces of Thoth’s core functionality if you want to.

Be creative! And be sure to let us know about the awesome plugins you create.