sinatra-mvc 0.0.1

data/bin/sinatra-mvc

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby1.9.1
+
+# Determine the location of our project
+PROJECT = ENV['PROJECT'] ? ENV['PROJECT'] : '.'
+
+Dir.chdir PROJECT do
+  require 'sinatra-mvc'
+end

data/bin/sinatra-mvc-project

@@ -0,0 +1,24 @@
+#!/usr/bin/env ruby1.9.1
+# Creates a new project.
+
+require 'fileutils'
+require 'rubygems'
+
+unless ARGV[0]
+  $stderr.puts 'Please supply the name of the new project'
+  exit 1
+end
+
+skel = File.join File.dirname(Gem.bin_path('sinatra-mvc')), '..', 'skel'
+
+begin
+  FileUtils.cp_r skel, ARGV[0]
+  Dir.chdir ARGV[0] do
+    system 'bundle install --path vendor --binstubs'
+  end
+rescue
+  $stderr.puts $!
+  exit 1
+end
+
+puts "Finished. Your project is located in %s." % File.expand_path(ARGV[0])

data/lib/sinatra-mvc.rb

@@ -0,0 +1,44 @@
+# Sinatra MVC Web Application
+# Based on Sinatra and Common Sense (tm)
+# 
+# Joris van Rooij <jorrizza@jrrzz.net>
+# http://www.jrrzz.net/
+
+# Check if we've got a PROJECT defined.
+raise RuntimeError, 'PROJECT is not defined!' unless defined? PROJECT
+
+# A hack for now, but at least it's better than nothing.
+Encoding.default_external = 'UTF-8'
+
+# Project include path.
+$:.push PROJECT
+
+# Guess what. We need these.
+require 'rubygems'
+require 'sinatra'
+require 'erubis'
+
+# i18n using R18n.
+require 'sinatra/r18n'
+
+# Load all of the core modules, in order.
+require 'sinatra-mvc/settings'
+require 'sinatra-mvc/view_prefix'
+require 'sinatra-mvc/render_params'
+require 'sinatra-mvc/database_connection'
+require 'sinatra-mvc/session_store'
+require 'sinatra-mvc/flash_messages'
+require 'sinatra-mvc/post_handler'
+require 'sinatra-mvc/conditional_form_field'
+require 'sinatra-mvc/escaping'
+
+# We use Bundler to manage the rest of the deps.
+require 'bundler/setup'
+
+# Load the application.
+require 'conf/environment'
+require 'sinatra-mvc/load_app'
+require 'sinatra-mvc/load_utils'
+
+# Start the classic mode.
+set :run, true

data/lib/sinatra-mvc/conditional_form_field.rb

@@ -0,0 +1,14 @@
+# Simple helper to display form field data when available.
+# It prefers params, but when unavailable it'll use the supplied object (if available).
+
+helpers do
+  def c(field, object = nil)
+    if params.has_key? field.to_s
+      h params[field.to_s]
+    elsif object.respond_to? field
+      h object.send(field)
+    else
+      ""
+    end
+  end
+end

data/lib/sinatra-mvc/database_connection.rb

@@ -0,0 +1,15 @@
+require 'dm-core'
+require 'dm-types'
+require 'dm-validations'
+
+# Add translations to models
+require 'r18n-core/translated'
+
+# When we're developing, some DataMapper debug would be nice.
+if development?
+  DataMapper::Logger.new $stdout, :debug
+  #DataMapper::Model.raise_on_save_failure = true
+end
+
+# Set up our database connection.
+DataMapper.setup :default, Settings.settings['database_connection']

data/lib/sinatra-mvc/escaping.rb

@@ -0,0 +1,7 @@
+# Like rails, make h() escape HTML characters.
+
+helpers do
+  def h(s)
+    Rack::Utils.escape_html s
+  end
+end

data/lib/sinatra-mvc/flash_messages.rb

@@ -0,0 +1,4 @@
+# Flash messages on redirect
+require 'rack-flash'
+use Rack::Flash
+require 'sinatra/redirect_with_flash'

data/lib/sinatra-mvc/load_app.rb

@@ -0,0 +1,12 @@
+# Loads the app recursively.
+# It does this by first loading all of the models and then
+# the controllers (app components if you will).
+
+def load_app(dir)
+  Dir.glob(File.join PROJECT, dir, '**', '*.rb').sort.each do |file|
+    load file
+  end
+end
+
+load_app 'models'
+load_app 'app'

data/lib/sinatra-mvc/load_utils.rb

@@ -0,0 +1,13 @@
+# Loads the proper utility from the utils directory
+# when that utility is called as a command line option.
+
+if ARGV[0] && !defined? RACKUP
+  util = File.join(PROJECT, 'utils', "#{ARGV[0]}.rb")
+  if File.exists? util
+    printf "Running util %s.\n", ARGV[0]
+    require util
+    exit
+  else
+    printf ">> Util %s does not exist. Continue as normal.\n", ARGV[0]
+  end
+end

data/lib/sinatra-mvc/post_handler.rb

@@ -0,0 +1,67 @@
+# Utility functions to handle POST data.
+# TODO: Write post_object_multi for field[] input fields
+
+helpers do
+  # Makes fetch more readable
+  def n
+    :n
+  end
+  
+  # Create or modify a single object from POST data.
+  # We assume the programmer isn't stupid, and actually provided a DataMapper
+  # class or object as the first argument.
+  # The second and third arguments supply a redirection mechanism on succes
+  # and failure. By default it's the referer. When nil, no redirection will
+  # take place.
+  def fetch(mode, input,
+            the_way_forward = request.env['HTTP_REFERER'],
+            the_way_back = request.env['HTTP_REFERER'])
+
+    # Get the proper object and class.
+    if input.is_a? DataMapper::Resource
+      the_object = input
+      the_class = the_object.class
+    else
+      the_class = input
+      the_object = the_class.new
+    end
+
+    # fetch 1, ...
+    if mode == 1
+      # Check for each parameter if we've got a model field
+      # and call the setter for that field and redirect.
+      params.each do |field, value|
+        method = (field + '=').to_sym
+        if the_object.respond_to? method
+          the_object.send(method, value)
+        end
+      end
+
+      # If the object's valid, save and redirect. If not, show all
+      # the errors to the user at the way back location. We also make
+      # sure the same error doesn't show twice.
+      if the_object.valid?
+        the_object.save
+        redirect the_way_forward unless the_way_forward.nil?
+      else
+        flash[:error] = []
+        found_errors = []
+        the_object.errors.each_pair do |field, error|
+          field = field.to_s
+          field.gsub! /_id$/, ''
+          error.each do |e|
+            unless found_errors.include? [field, error]
+              flash[:error] << t[the_class.inspect.downcase.to_sym][field.to_sym] + ': ' + e
+              found_errors << [field, error]
+            end
+          end
+        end
+        redirect the_way_back unless the_way_back.nil?
+      end
+    elsif mode == :n
+      raise NotImplementedError, 'Sorry, fetch n, ... is not implemented yet.'
+    else
+      raise ArgumentError, 'No such mode: ' + mode.inspect
+    end
+  end
+end

data/lib/sinatra-mvc/render_params.rb

@@ -0,0 +1,18 @@
+# This will enable neat parameters like Rails and PHP have.
+# You know, the variable[key] things.
+# From the Sinatra book.
+
+before do
+  new_params = {}
+  params.each_pair do |full_key, value|
+    this_param = new_params
+    split_keys = full_key.split(/\]\[|\]|\[/)
+    split_keys.each_index do |index|
+      break if split_keys.length == index + 1
+      this_param[split_keys[index]] ||= {}
+      this_param = this_param[split_keys[index]]
+   end
+   this_param[split_keys.last] = value
+  end
+  request.params.replace new_params
+end

data/lib/sinatra-mvc/session_store.rb

@@ -0,0 +1,13 @@
+# Sessions for Sinatra
+# Both cookie based as Memcache based sessions are supported
+
+case settings.session_backend
+when :cookie
+  use Rack::Session::Cookie, :expire_after => settings.session_max_age, :key => 'sinatra.mvc.session', :secret => (0..50).map do
+    65 + rand(25).chr
+  end.join
+when :memcache
+  use Rack::Session::Memcache, :expire_after => settings.session_max_age, :key => 'sinatra.mvc.session', :namespace => 'sinatra:mvc:session', :memcache_server => settings.session_store
+else
+  raise 'Unknown session backend: ' + settings.session_backend.inspect
+end

data/lib/sinatra-mvc/settings.rb

@@ -0,0 +1,29 @@
+# Loads the settings
+
+require 'psych'
+
+class Settings
+  def self.load(filename)
+    begin
+      @@settings = Psych.load_file filename
+    rescue
+      raise 'Could not load configuration! Psych said: ' + $!.to_s
+    end
+  end
+
+  def self.settings
+    @@settings
+  end
+end
+
+Settings.load File.join(PROJECT, 'conf', 'settings.yml')
+
+# Now we have to feed the Sinatra settings
+Settings.settings.each_pair do |setting, value|
+  case setting
+  when 'views_root', 'translations', 'public'
+    set setting.to_sym, File.join(PROJECT, value)
+  else
+    set setting.to_sym, value
+  end
+end

data/lib/sinatra-mvc/view_prefix.rb

@@ -0,0 +1,17 @@
+# Set the view prefix right if the
+# first part of the URL exists as a subdir
+# of our main view directory.
+
+before do
+  first_dir = request.env['REQUEST_URI'].split('/')[1]
+
+  if first_dir
+    if File.directory? File.join(settings.views_root, first_dir)
+      set :views, File.join(settings.views_root, first_dir)
+    else
+      set :views, settings.views_root
+    end
+  else
+    set :views, settings.views_root
+  end
+end

data/skel/.gitignore

@@ -0,0 +1,4 @@
+*~
+vendor
+bin
+.bundle

data/skel/.hgignore

@@ -0,0 +1,7 @@
+# use glob syntax.
+syntax: glob
+
+*~
+vendor
+bin
+.bundle

data/skel/Gemfile

@@ -0,0 +1,17 @@
+source :rubygems
+
+# A faster web server.
+gem 'thin'
+
+# Markdown rendering support for R18n and Tilt.
+gem 'rdiscount'
+gem 'maruku'
+
+# Datamapper is nowhere without this.
+gem 'dm-migrations'
+gem 'dm-aggregates'
+
+# Some often used template utilities. Add/enable at will.
+# gem 'RedCloth'
+# gem 'liquid'
+# gem 'less'

data/skel/app/index.rb

@@ -0,0 +1,3 @@
+get '/' do
+  erubis :index
+end

data/skel/app/not_found.rb

@@ -0,0 +1,5 @@
+# The 404 page.
+
+not_found do
+  erubis :not_found
+end

data/skel/conf/environment.rb

@@ -0,0 +1,10 @@
+# Environment File
+# Require all the libraries used in your project here.
+
+# Datamapper Modules
+require 'dm-aggregates'
+require 'dm-migrations'
+
+# Templating Engines
+#require 'redcloth'
+#require 'liquid'

data/skel/conf/settings.yml

@@ -0,0 +1,18 @@
+---
+# Sessions
+session_max_age: 86400
+session_backend: :memcache
+session_store: localhost:11211
+
+# Views
+views_root: views
+
+# Public directory
+public: public
+
+# i18n
+default_locale: en
+translations: i18n
+
+# Database
+database_connection: mysql://sinatra:sinatra@localhost/sinatra_mvc

data/skel/config.ru

@@ -0,0 +1,8 @@
+# Rackup file for Sinatra-MVC
+
+::RACKUP = true
+::PROJECT = File.expand_path(File.dirname(__FILE__))
+Dir.chdir ::PROJECT do
+  require 'sinatra-mvc'
+  run Sinatra::Application
+end

data/skel/i18n/en.yml

@@ -0,0 +1,5 @@
+---
+errors:
+  pagenotfound: !!markdown
+    The page at _%1_ can not be found.
+

data/skel/utils/initdb.rb

@@ -0,0 +1,12 @@
+# Initializes the database if asked to.
+
+# Are you sure?
+print "\nWarning, this will DESTROY EVERYTHING YOU HAVE!\nAnd probably more...\n\nAre you sure? (y/N)"
+STDOUT.flush
+answer = STDIN.gets
+exit unless answer == "y\n"
+
+# Rebuild the database structure.
+DataMapper.auto_migrate!
+
+# Add custom things to do after an init here

data/skel/utils/upgradedb.rb

@@ -0,0 +1,3 @@
+# Uogrades the database if asked to.
+
+DataMapper.auto_upgrade!

data/skel/views/docs.md

@@ -0,0 +1,463 @@
+Sinatra MVC
+===========
+
+Sinatra MVC is a simple attempt to get some kind of MVC structure on top
+of Sinatra, without losing much of the original Sinatra _"feeling"_. It
+uses Datamapper for it's model layer and custom software for the other
+two.
+
+It's recommended to read the [Sinatra README][6] first before continuing
+with this document.
+
+A rule of thumb: In command line examples, a `$` prefix means your own
+user and a `#` prefix is a root terminal.
+
+System Dependencies
+-------------------
+
+Your system needs to have a working Ruby 1.9.2 installation (or later,
+but I haven't tested that). You'll also need some kind of database. The
+currently supported databases are:
+
+* MySQL
+* PostgreSQL
+* Sqlite3
+
+Sinatra MVC also has the possibility to use Memcache as a session storage
+system. This is the default. It's recommended as well.
+
+The framework has been developed on a Debian Sid platform, and as such
+Debian is the preferred platform of choice. If you encounter problems
+caused by Debian-specific hacks, please let me know. The interpreter
+string has been set to `ruby1.9.1`, but you can easily change that in
+the `bin` directory  if you wish. Don't worry, that's the only place the 
+"weird" interpreter string is used.
+
+Throughout the documentation Debian-specific help will be provided. Other
+operating systems might be added later.
+
+Installing
+----------
+
+Installing Sinatra MVC is reasonably simple. All you need is Mercurial,
+some development headers (distributed by your operating system) and
+a terminal.
+
+For Debian users, the following command will suffice (or ask your system
+administrator to install the packages for you):
+
+    # apt-get install ruby1.9.1-full libmysqlclient-dev libpq-dev libsqlite3-dev build-essential
+
+You'll have to make sure the Ruby gem path is in your terminal's `$PATH`.
+For Debian, adding the following line to your `~/.bashrc` will do just
+fine. Don't forget to restart your shell to enable this!
+
+    PATH="/var/lib/gems/1.9.1/bin/:$PATH"
+
+The simplest method is using Rubygems. For Debian, use `gem1.9.1` instead
+of `gem`.
+
+    # gem install sinatra-mvc
+
+Or for the latest and greatest, you can need to download the source tree.
+It's available on both [Github][8] and [Bitbucket][9], but both are only
+mirrors of the development tree at wasda.nl.
+
+    $ cd $HOME/src
+    $ hg clone https://bitbucket.org/jorrizza/sinatra-mvc
+    - or if you prefer github -
+    $ git clone git://github.com/jorrizza/sinatra-mvc.git
+    $ cd sinatra-mvc
+    $ rm sinatra-mvc-*.gem
+    $ gem build sinatra-mvc.gemspec
+    # gem install sinatra-mvc-*.gem
+
+Now we've got sinatra-mvc installed, let's start our own project.
+
+    $ cd $HOME/src
+    $ sinatra-mvc-project my_project
+    $ cd my_project
+
+Yay! A project!
+
+Using bundler, we can install all of our gems without getting in the way of
+your host Ruby installation. The `sinatra-mvc-project` utility has already
+installed the bundler files in your project with the default set of gems.
+
+Updating gems is pretty easily done. Now you've got your bundle complete,
+you'll just have to run:
+
+    $ bundle update
+
+When you need more gems to be added to your project, simply edit the
+`Gemfile` and run
+
+    $ bundle update
+
+again. This will make sure the dependencies of your application, as supplied
+in the `Gemfile`, will be available to your project. For further
+documentation about the `Gemfile`, read the [Bundler documentation about
+the `Gemfile`][17]
+
+Updating
+--------
+
+For a Rubygems installation simply run:
+
+    # gem update
+
+To get the latest updates from the repository, just pull (and merge if needed).
+
+    $ cd $HOME/src/sinatra-mvc
+    $ hg pull
+    $ hg update
+    - or when using github -
+    $ git pull
+    $ gem build sinatra-mvc.gemspec
+    # gem install sinatra-mvc-0.0.1.gem
+
+Configuration
+-------------
+
+The main configuration is defined in `conf/settings.yml`. It's the place
+where you can use the Sinatra `set` method to change Sinatra's behaviour.
+Nothing keeps you from setting configuration parameters in controllers,
+but please keep things nicely tucked away in this file. Every field will
+be translated to a `set :field, value` call.
+
+For sessions there are three configuration parameters you can set. The
+`session_max_age` determines the age of the session cookie in seconds.
+After this amount of time, the cookie is denied and browsers should
+automatically discard it. There are two session backends you can choose
+from. If you set `session_backend` to `:cookie`, all the session values
+will be stored in the cookie itself. Even though it will be encrypted,
+this is not a very safe thing to do. It also limits your storage to the
+maximum allowed cookie size, which varies from browser to browser. The
+preferred setting is `:memcache`, which will use memcache as a session
+backend. It doesn't limit your session size that much, and can scale
+pretty well. Set the `session_store` to either a string or an array of
+strings for a single server or a memcached cluster. The format is
+`hostname:port`. This value will be ignored for the `:cookie`
+`session_backend` setting. So for a single memcache server you define:
+
+    session_store: hostname:11211
+
+And for a memcache cluster:
+
+    session_store:
+      - hostname1:11211
+      - hostname2:11211
+      - hostname3:11211
+
+If you want to change the path to the views root directory, you can change
+the `views_root` setting. It's `views` by default. This is interpreted as
+a subdirectory of your project.
+
+The same applies to the `public` setting, which should point to the
+directory within your project from which static content is being served.
+
+For i18n you can set the default locale using `default_locale`. This is
+the name of the file in the `translations` directory, without the `.yml`
+file extension. Just like `views_root`, `translations` is a subdirectory
+of your project.
+
+The database connection is defined by `database_connection`.  The value is
+a string, following the syntax:
+
+* `sqlite::memory:` for in-memory Sqlite3 storage
+* `sqlite:///path/to/file.db` for file-based Sqlite3
+* `mysql://user:pass@server/database` for the MySQL RDBMS
+* `postgres://user:pass@server/database` for the PostgreSQL RDBMS
+
+You can read the settings file using the `Settings.settings` call, which
+will return a Hash of your settings. Alternatively you can read the
+configuration Sinatra received by using the `settings` object like explained
+in the [Sinatra settings documentation][15]. These two differ slightly,
+mainly in the fact that Sinatra isn't aware of the project directory.
+
+Running your Application
+------------------------
+
+Sinatra is built on top of Rack, so every method that can run Rack will
+be able to run your Sinatra MVC application. That even includes things
+like [Shotgun][2], [Phusion Passenger][3] and [Heroku][4].
+
+There are basically two ways to run your application. During development,
+it's okay to run your application using the built-in thin server. This
+will serve all the static files and handle the application calls at the
+same time. Just simply run:
+
+    $ cd my_project
+    $ sinatra-mvc
+
+This will run your application in development mode, allowing you to see
+the access log in the terminal and tracebacks when you've made an _oops_.
+It also enables nicely formatted error pages, generated by Sinatra.
+
+Another method is using the `PROJECT` environment variable.
+
+    $ PROJECT=~/src/my_project sinatra-mvc
+
+In production, there are several ways you can use Rack to serve your app.
+I suggest using thin, proxied by Nginx for the static files. The
+supplied `config.ru` Rackup file will handle things for you. Be sure to
+configure your server to run in production mode. This will disable the
+helpful error messages and other development coolness.
+
+An example using Shotgun:
+
+    # gem1.9.1 install shotgun
+    $ shotgun ~/src/my_project/config.ru
+
+Or:
+
+    $ cd ~/src/my_project
+    $ shotgun
+
+Static Files
+------------
+
+By default, static files are served from the `public/` directory. If you
+create a file at `public/css/site/main.css`, the HTTP request to 
+`/public/css/site/main.css` will serve that file. You're completely free
+to specify your own directory structure.
+
+Controllers
+-----------
+
+Controllers are vastly simplified and are not at all linked to models.
+If you want to make it so, you're free to do so. The controller files
+reside under `app/`. All of the files are read recursively in order during
+application startup. This means you can apply a sane directory structure
+to the app directory to make your controllers easier to understand. Since
+only the application's startup time is slightly influenced by the
+complexity of the directory structure and the amount of files in them,
+you're encouraged to split up your controllers as much as needed.
+
+The code that goes into these files ends up in Sinatra's [application
+scope][5]. You can fully use Sinatra's DSL to get things done. To keep
+the original Sinatra _vibe_ alive, there's no central routing method.
+Instead, you're required to use Sinatra's DSL to specify what happens
+after what request.
+
+Let's assume you've got a blog with posts, and you want to edit a certain
+post. In this case, you might choose for the following file:
+`app/post/modify.rb`.
+
+    get '/post/modify/:id'
+      @post = Post.get id
+      halt 404 unless @post
+
+      erubis :post_modify
+    end
+
+    post '/post/modify/:id'
+      @post = Post.get id
+      halt 404 unless @post
+
+      fetch 1, @post, '/post/read/' + id, nil
+
+      erubis :post_modify
+    end
+
+As you can see, not much has been changed from the original concept.
+The post itself is a Datamapper model, and is used a such.
+
+In the post bit of the controller there's an awesome little function call,
+allowing you to populate your model with incoming POST data. The `fetch`
+function is designed to tackle most, but not all, handling of incoming
+request data. It's built on top op Datamapper and expects either an object
+or a class of a Datamapper model as it's second parameter. The spec:
+
+    fetch [1|n], [object|class], url_on_success = referer, url_on_failure = referer
+
+The first parameter (`1` or `n`) switches functionality between fetching
+a single object, or multiple objects of the same type. _Only single
+object fetching is supported for now_. The second argument accepts both
+classes and objects of Datamapper models. If it's a class, it will create
+a new object using the received values and saves it to the database. If it's
+an existing object, it will modify the object using the received fields.
+Be sure to have your form field name attributes match the Datamapper field
+names. If you have any other fields that end up in the `params` hash, make
+sure the fields do not overlap. Both URL filters (like `get '/my/:id' do
+... end`) and normal HTTP GET parameters (like `/my/?id=1`) interfere with
+the `params` variable `fetch` uses. Internally the function will handle
+Datamapper validation and will only write to the database when everything
+checks out. The errors will be displayed using flash messages after a 
+redirect. That's what the last two parameters are for. Both are optional.
+When excluded, they'll have the value of the current referer. The first
+is the redirect on success URL. This will keep the back button from
+resending the POST data. The second one is the redirect on failure URL.
+When nil is given, no redirection will take place and control will be given
+back to the controller, allowing you to have the conditional form fields
+(`c` function) in your view display the sent data.
+
+The flash messages aren't only available to the `fetch` function, but
+you're allowed to set them yourself as well. There are two methods of using
+the flash messages. You can alter the `flash` variable itself. The variable
+is a hash with two possible fields. `:info` contains information, in either
+and array or a string. `:error` contains the same, but for errors. If you
+set the flash message, the first view that is rendered will display the
+values. Take a look at `views/flash_message.erubis` for the markup. The
+second method uses an extention to the `redirect` function, allowing you
+to supply a message to be displayed after a redirect. Example:
+
+    redirect '/naked/horses', :info => 'Stand the f*ck back!'
+
+Or more messages:
+
+    redirect '/naked/penguins', :info => ['This is unfunny', 'This kind of turns me on']
+
+Or several types:
+
+    redirect '/naked/cows', :flash => {:info => 'Horny, get it?', :error => 'Not funny!'}
+
+Views
+-----
+
+Sinatra MVC has all the [view options][1] Sinatra has. Some things differ
+though, since this framework supports an URL-directory mapping for views.
+
+Using _erubis_ is recommended, but you might as well use other templating
+methods. Any template method supported by the tilt library, included by
+Sinatra, can be used. Just make sure you've added the library to the
+`Gemfile` and included it in the `conf/environment.rb`.
+
+Some sidemarks with this selection of templating solutions:
+
+* You can use less. Sinatra MVC wants to keep things speedy, so please use
+  `bin/lessc` to compile your less templates. Unless you've got a proper
+  cache of course.
+* Markdown support in R18n is done using Maruku, but Sinatra (tilt) prefers
+  rdiscount. Both are included in the default `Gemfile`. One of the future
+  things that will be done is removing one of the two. This will have to do
+  for now.
+
+Normally, you have to do weird stuff in Sinatra like using
+`:'directory/my_view.erubis'` for rendering views in sub directories. Sinatra
+MVC has added automatic view prefixes. The former method of using hardcoded
+prefixes still works, but now there's URI-based mapping as well. In short,
+it uses the views from the directory path in the view directory if that
+path matches the URI prefix. For example, if you have a controller like
+this:
+
+    get '/my/little/pony/pink'
+      erubis :pink
+    end
+
+It will render a page using `views/my/little/pony/pink.erubis`, but only
+if that directory exists. This directory will be used as the new view
+prefix, so make sure every directory has at least the following files:
+
+* `layout.erubis`
+* `not_found.erubis`
+* `flash_message.erubis` (only if layout requires it)
+
+This construction allows you to create prefix-based sub sites, each with
+it's own look and feel. Originally this has been created to allow for
+admin areas and the like.
+
+Views have a neat little function for displaying form values. It's called
+conditional form field (`c` for short). The `c` function will take two
+parameters, here's the spec:
+
+    c field, object = nil
+
+The field is a symbol of the field from your Datamapper model. This
+function will check if your field is found in POST data, and will display
+that value. If it's not, it will return an empty string. Unless you've
+supplied the second parameter, which is a Datamapper object. If the
+object contains a value for that field, that will be displayed in stead
+of an empty string. Here's a practical example for the `c` function for
+handling a post's content.
+
+    <td><textarea name="content"><%=c :content, @post %></textarea></td>
+
+The `c` function will automatically call `h` when creating output. The
+`h` function escapes HTML, just like in Rails.
+
+Models
+------
+
+Sinatra MVC uses Datamapper for it's models. Just like the controllers, 
+the models are included recursively so you are allowed to create your own
+structure in the `models` directory.
+
+For documentation regarding Datamapper, please visit de [Datamapper
+documentation][7]. Some popular plugins are provided:
+
+* [dm-migrations][12]: Adds migration support. Used by provided utils.
+* [dm-aggregates][13]: Adds aggregation support (COUNT() and the like).
+* [dm-validations][14]: Adds validation. Used extensively.
+
+If you want to add more `dm-*` modules, just add them to your `Gemfile`
+and include them in the `conf/environment.rb` file.
+
+The classed defined in the models are automatically available in the
+controllers.
+
+When you've created your models, you can check and initialize them by
+running:
+
+    $ cd my_project
+    $ sinatra-mvc initdb
+
+This will initialize your database, but beware, it'll purge every model
+defined in your `models` directory. If you just want to migrate your models
+(e.g. update the database to reflect your models), just run:
+
+    $ cd my_project
+    $ sinatra-mvc upgradedb
+
+This will only update the tables in such a way it can't modify any of the
+data already present. To do that, you'll have to write migrations. This
+functionality is lacking at the moment. Datamapper is able to run migrations,
+but nobody bothered documenting how they work.
+
+Internationalisation
+--------------------
+
+Internationalisation is done using R18n. This method allows for neat
+integration into Sinatra. The documentation is complete and available on
+[their site][16].
+
+Utilities
+---------
+
+Utilities are scripts you can run within the Sinatra MVC environment. It's
+pretty much what Rails does using `rake`, but without the complexity. Just
+add a file in the `utils` directory and do whatever you want to do.
+You can use the database like you're used to. The utils are meant to
+function as cron jobs or management processes. As you can see, the database
+scripts are already provided.
+
+To run a script, simply call:
+
+    $ cd my_project
+    $ sinatra-mvc <scriptname without .rb>
+
+Single Character Reserved Variables
+-----------------------------------
+
+Just don't use these as variables within controllers and views, mkay?
+
+* `h - ` HTML escaping function.
+* `t - ` Translation function (R18n).
+* `c - ` Conditional form field.
+* `n - ` Just meaning "n" of something.
+
+[1]: http://rubydoc.info/gems/sinatra/1.1.0/file/README.rdoc#Views___Templates
+[2]: http://rtomayko.github.com/shotgun/
+[3]: http://www.modrails.com/
+[4]: http://heroku.com/
+[5]: http://www.rubydoc.info/gems/sinatra/1.1.0/file/README.rdoc#Application_Class_Scope
+[6]: http://www.rubydoc.info/gems/sinatra/1.1.0/file/README.rdoc
+[7]: http://rubydoc.info/gems/dm-core/1.0.2/frames
+[8]: https://github.com/jorrizza/sinatra-mvc
+[9]: https://bitbucket.org/jorrizza/sinatra-mvc
+[12]: http://www.rubydoc.info/gems/dm-migrations/1.0.2/frames
+[13]: http://www.rubydoc.info/gems/dm-aggregates/1.0.2/frames
+[14]: http://www.rubydoc.info/gems/dm-validations/1.0.2/frames
+[15]: http://www.sinatrarb.com/configuration.html
+[16]: http://r18n.rubyforge.org/sinatra.html
+[17]: http://gembundler.com/man/gemfile.5.html