Kontrol - a micro framework

December 28, 2008

Kontrol is a small web framework written in Ruby, which runs directly on Rack. It provides a simple pattern matching algorithm for routing and uses GitStore as data storage.

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

Kontrol has its own project page now! Please look for current information there.

Quick Start

Create a file named hello_world.ru:

  1. require 'kontrol'
  3. class HelloWorld < Kontrol::Application
  4.   map do
  5.     get '/' do
  6.       "Hello World!" 
  7.     end
  8.   end
  9. end
  11. run HelloWorld.new

Now run:

rackup hello_world.ru

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

Features

Kontrol is just a thin layer on top of Rack. It provides a routing algorithm, a simple template mechanism and some convenience stuff to work with GitStore.

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

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:

  1. require 'kontrol'
  3. class Routing < Kontrol::Application
  4.   map do
  5.     get '/pages/(.*)' do |name|
  6.       "This is the page #{name}!"
  7.     end
  9.     get '/(\d*)/(\d*)' do |year, month|
  10.       "Archive for #{year}/#{month}"
  11.     end
  12.   end
  13. end
  15. 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 Archive for 2008/12.

Nested Routes

Routes can be nested. This way you can avoid repeating patterns and define handlers for a set of HTTP verbs. Each handler will be called with the same arguments.

  1. require 'kontrol'
  3. class Nested < Kontrol::Application
  4.   map do
  5.     map '/blog' do
  6.       get '/archives' do
  7.         "The archives!"
  8.       end
  9.     end
  11.     map '/(.*)' do
  12.       get do |path|
  13.         "<form method='post'><input type='submit'/></form>"
  14.       end
  16.       post do |path|
  17.         "You posted to #{path}"
  18.       end
  19.     end
  20.   end
  21. end
  23. run Nested.new

Now run this app like:

rackup nested.ru

The second route catches all paths except the /blog route. Inside the second route there are two different handlers for GET and POST actions.

So if you browse to /something, you will see a submit button. After submitting you will see the result of the second handler.

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:

  1. <html>
  2.   <body>
  3.     <%= @content %>
  4.   </body>
  5. </html>

And now another template named templates/page.rhtml:

  1. <h1><%= @title %></h1>
  2. <%= @body %>

Create a templates.ru file:

  1. require 'kontrol'
  3. class Templates < Kontrol::Application
  4.   map do
  5.     get '/(.*)' do |name|
  6.       render "page.rhtml", :title => name.capitalize, :body => "This is the body!"
  7.     end
  8.   end
  9. end
  11. 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 and Grit by:

$ gem sources -a http://gems.github.com (you only have to do this once)
$ sudo gem install mojombo-grit georgi-git_store

We create a Markdown file name pages/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:

  1. require 'kontrol'
  2. require 'bluecloth'
  4. class GitApp < Kontrol::Application
  5.   map do
  6.     get '/(.*)' do |name|
  7.       BlueCloth.new(store['pages', name + '.md']).to_html
  8.     end
  9.   end
  10. end
  12. run GitApp.new

Add all these files to your repo:

git init
git add pages/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 delete all files except the rackup file and the app will still serve the page from your repo.

Posted in category Ruby by Matthias Georgi. Tagged with framework, kontrol.
Similar Posts

Subscribe

About

Matthias Georgi Berlin, Germany

Archives

Recent posts

Blogroll