Creating Plugins

Rethoth plugins

A Rethoth plugin is really just a Ruby module that lives in the Thoth::Plugin namespace. Plugins can just be placed into the /plugin directory under your Rethoth home directory (e.g., ~/myblog/plugin) or in the Rethoth installation (e.g., path/lib/thoth/plugin/). Rethoth plugins can be distributed as RubyGems as well. If you don’t distribute them as RubyGems, or if you are in development, remember that if you put them in the Rethoth installation directory they will be overwritten next time you upgrade Rethoth.

When you call a method like Thoth::Plugin::Foo.bar from a view (or even from another plugin), Rethoth first looks for a file named thoth_foo.rb in the project’s /plugin directory and then in Rethoth’s installation /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.

If you have a plugin (or different versions of the same plugin) under your project’s /plugin directory as well as under Rethoth’s, then the one in your project’s directory will be loaded. Remember that there is no versioning in Rethoth plugins, the name is the only identifier.

Writing a Plugin

To write a simple plugin , let’s say myplugin, just create a file in your blog’s /plugin directory named thoth_myplugin.rb and open it in your favourite text editor. Then follow the example structure bellow.

require 'some_deps'

module Thoth 
  module Plugin
    module Myplugin
      
      # example method 
      def self.hello(name)
        "hello #{name}"
      end

    end
  end 
end

It is that simple!

Calling a Plugin from a custom theme

You will typically use a plugin from a custom view of a theme that you may be working on.

If you’ve read the Creating Custom Themes guide, you probably already have some idea of what to do. Let’s break it down once more.

Let say your blog is called myblog and thus the Rethoth home directory to hold your custom views is myblog/view.

You may start by copying the default view/index.rhtml, If you’re not sure where the default views are, run thoth --help to find out.

cp /path/to/default/view/index.rhtml ~/myblog/view/

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

<div class="hfeed">
  <% @posts.all do |post| %>
    <%= Thoth::PostController.render_view('compact', :post => post) %>
  <% end %>
</div>

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

and add a call to the example plugin just above it:

<div id="hi">
<h2><%= Thoth::Plugin::Myplugin.hello("my friend") %></h2>
</div>

<div class="hfeed">
  <% @posts.all do |post| %>
    <%= Thoth::PostController.render_view('compact', :post => post) %>
  <% end %>
</div>

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

Save the file, restart Rethoth, browse to your site and you should see at the top your blog greeting you with “hello my friend”. Easy huh?

The built-in Tags plugin

For a more complete example look into your Rethoth’s installation for lib/thoth/plugin/thoth_tags.rb

Debugging

If you run into an issue with a plugin, or need information on the information coming out of Rethoth, try running in irb. Full instructions are on the Debugging page.

The Sky is the Limit

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

Be creative and let us know about the awesome plugins that you create.