Kontrol - a micro framework

Kontrol is a small web framework written in Ruby, which runs directly on Rack. Basically you can mount a class as rack handler and attach a set of named routes, which will be used for route recognition and generation.

All examples can be found in the examples folder of the kontrol project, which is hosted on github.

Quick Start

We will create a simple Kontrol application with exactly one route named 'root'. Routes are defined within a block insider your application class. Each route has a name, a pattern and a block. The name must be defined to generate paths pointing to this route.

hello_world.ru:

class HelloWorld < Kontrol::Application
  
  def time
    Time.now.strftime "%H:%M:%S"
  end
 
  map do
    root '/' do
      text "<h1>Hello World at #{time}</h1>"
    end
  end
end
    
run HelloWorld.new

Now run:

rackup hello_world.ru

Browse to http://localhost:9292 and you will see "Hello World".

Basics

A Kontrol application is a class, which provides some context to the defined actions. You will probably use these methods:

request: the Rack request object
response: the Rack response object
params: union of GET and POST parameters
cookies: shortcut to request.cookies
session: shortcut to request.env['rack.session']
redirect(path): renders a redirect response to specified path
render(file, variables): render a template with specified variables
text(string): render a string

Routing

Routing is just as simple as using regular expressions with groups. Each group will be provided as argument to the block.

Create a file named routing.ru:

require 'kontrol'

class Routing < Kontrol::Application
  map do
    pages '/pages/(.*)' do |name|
      text "The path is #{ pages_path name }! "
    end
 
    archive '/(\d*)/(\d*)' do |year, month|
      text "The path is #{ archive_path year, month }! "
    end
  end
end

run Routing.new

Now run this application:

rackup routing.ru

You will now see, how regex groups and parameters are related. For example if you browse to localhost:9292/2008/12, the app will display The path is /2008/12.

The inverse operation to route recognition is route generation. That means a route with one or more groups can generate a url, which will be recognized this very route.

For example the route /page/(.*) named page will recognize the path /page/about, which can be generated by using page_path('about').

Templates

Rendering templates is as simple as calling a template file with some parameters, which are accessible inside the template as instance variables. Additionally you will need a layout template.

Create a template named templates/layout.rhtml:

<html>
  <body>
    <%= @content %>
  </body>
</html>

And now another template named templates/page.rhtml:

<h1><%= @title %></h1>
<%= @body %>

Create a templates.ru file:

require 'kontrol'

class Templates < Kontrol::Application
  map do
    page '/(.*)' do |name|
      render "page.rhtml", :title => name.capitalize, :body => "This is the body!"
    end
  end
end

run Templates.new

Now run this example:

rackup templates.ru

If you browse to any path on localhost:9292, you will see the rendered template. Note that the title and body parameters have been passed to the render call.

Using GitStore

GitStore is another library, which allows you to store code and data in a convenient way in a git repository. The repository is checked out into memory and any data may be saved back into the repository.

Install [GitStore][] by:

$ gem sources -a http://gems.github.com
$ sudo gem install georgi-git_store

We create a Markdown file name index.md:

Hello World
===========

This is the **Index** page!

We have now a simple page, which should be rendered as response. We create a simple app in a file git_app.ru:

require 'kontrol'
require 'bluecloth'
require 'git_store'

class GitApp < Kontrol::Application
 
  def initialize(path)
    super
    @store = GitStore.new(path)
  end
  
  map do
    page '/(.*)' do |name|
      text BlueCloth.new(@store[name + '.md']).to_html
    end
  end
end

run GitApp.new

Add all the page to your git repository:

git init
git add index.md
git commit -m 'init'

Run the app:

rackup git_app.ru

Browse to http://localhost:9292/index and you will see the rendered page generated from the markdown file.

This application runs straight from the git repository. You can even delete the page and it will still show up over the web.