A collection of useful modules for Cuba
Latest commit b7f1222 Feb 26, 2013 @cyx Merge pull request #10 from inkel/mote-dependency
Add mote as a runtime dependency
Failed to load latest commit information.
test Update to mote v1.0.0 integration. Jul 23, 2012
.gems Fix gem manifest file. Jul 24, 2012
.gitignore Ignore /pkg folder. Jun 29, 2012
LICENSE Add initial gemspec. Nov 4, 2011
README.markdown Add example of layout using {{ content }} tag Oct 13, 2012
cuba-contrib.gemspec Add mote as a runtime dependency Feb 26, 2013
rakefile Add rake test task. Nov 4, 2011



Cuba is probably one of the tiniest rack-based micro frameworks around. Weighing in at only 138 LOC, it has proven itself to be a very resilient tool in various web application domains. Check the list of sites built using Cuba in order to grasp the endless possibilities.

STEP 1: Cuba::Prelude

Cuba does one thing, and it does it well. Cuba-contrib, on the other hand, layers requirement-specific functionality on top of it. This allows us to build simpler and lighter solutions.

To get started with Cuba::Contrib, install it using RubyGems:

$ gem install cuba          # if you haven't already done so
$ gem install cuba-contrib

For the remainder of the examples below, we'll assume you always put your main cuba application in app.rb and your views in views.

$ touch app.rb
$ mkdir views

Now you can require it in your application

require "cuba"
require "cuba/contrib"

Cuba.plugin Cuba::Prelude

Cuba::Prelude adds the basic stuff you'll need:

Cuba.define do
  on "about" do
    # same as encodeURIComponent in javascript land
    res.write urlencode("http://www.google.com")

    # basically an alias for Rack::Utils.escape_html
    res.write h("Cuba & Cuba Contrib")

STEP 2: Choose your templating

Here comes a new challenger: Mote

We prefer to use our home-grown templating engine called Mote. We do that by simply loading the plugin Cuba::Mote:

require "cuba"
require "cuba/contrib"
require "mote"

Cuba.plugin Cuba::Mote

Cuba.define do
  on "home" do
    res.write view("home")

  on "about" do
    res.write partial("about")

  # Or you can use `render` as a shortcut to `res.write view(...)`.
  on "contact" do

This assumes that you have a views folder, containing a home.mote and an about.mote. Your layout defaults to layout.mote. You can render the inner content into the layout using the {{content}} tag, for example:

    <title>Mote Layout</title>
    <h1>Hello, mote!</h1>
    {{ content }}

Classic templating needs

Note: as of Cuba 3.0, the plugin architecture of cuba-contrib has been merged into the core codebase. The following example should work with Cuba 3.0 without even requiring cuba-contrib.

require "cuba"
require "cuba/render"

Cuba.plugin Cuba::Render
Cuba.settings[:render][:template_engine] = "haml"

Cuba.define do
  on "home" do
    res.write view("home") # renders views/home.haml

  on "about" do
    res.write partial("about") # renders views/about.haml

STEP 3: Make your own plugins

Authoring your own plugins is pretty straightforward.

require "bluecloth"

module MyOwnHelper
  def markdown(str)

Cuba.plugin MyOwnHelper

that's the simplest kind of plugin you'll write. In fact, that's exactly how the markdown helper is written in Cuba::TextHelpers.

A more complicated plugin for example, will make use of Cuba.settings to provide default values:

module MarkdownView
  def self.setup(app)
    app.settings[:markdown_view] ||= {}
    app.settings[:markdown_view][:views] = "markdown"

  def markdown_view(template)
    data = File.read("#{settings[:markdown_view][:views]}/#{template}.markdown")

    res.write Markdown.new(data).to_html

Cuba.plugin MarkdownView