rjspotter-ramaze 2009.06.29

data/doc/tutorial/todolist.txt

@@ -0,0 +1,920 @@
+The official Ramaze Todo-list tutorial
+=====================================
+Michael 'manveru' Fellinger <m.fellinger@gmail.com>
+revision 2.0, March 2009
+
+== Abstract
+
+Welcome to the official tutorial for http://ramaze.net[Ramaze], the mandatory
+Todo-list.
+
+I also assume that you have some experience with HTML and some other basics in
+web-development already (you want to learn a web-framework after all).
+
+The tutorial assumes a working installation of http://ruby-lang.org[Ruby] and
+http://rubygems.org/[Rubygems].
+
+For more information on how to install these please read the introductory
+documentation of Ramaze, this is not in the scope of this tutorial.
+
+To install Ramaze you can `gem install ramaze`, other ways of installation are
+covered by the http://wiki.ramaze.net/[Ramaze Wiki].
+
+Should you encounter any problems while doing this tutorial, this might either
+be because Ramaze changed (which happens very often while it is still young)
+or I actually made some mistake while writing it.
+
+In either case it would make me (and all other poor fellows who happen to try
+this tutorial) very happy if you could spare some time and report the issue
+either on the http://github.com/manveru/ramaze/issues[Bug tracker] , or just
+drop by on IRC on `irc.freenode.org` in the channel `#ramaze`.
+
+If you have trouble with some of the terms used in this tutorial you can
+consult the <<glossary, Glossary>> at the end of this document.
+
+We are also working on a book that describes Ramaze in more depth, called
+'Journey to Ramaze', it is still very much work in progress, but some of the
+contents might interest you.
+
+The repository for the book is at http://github.com/manveru/ramaze-book. Every
+once in a while, updates for the book will be put in HTML and PDF form at
+http://book.ramaze.net.
+
+
+== First Step, Create
+
+The last version of this tutorial assumed a generator to produce a skeleton in
+which we do the work. This time around we will do everything from scratch to
+give you a better experience of how exactly the pieces fit together.
+
+You can also skip all the boring learning-by-doing part and play around with
+the source of the todo-list example shipping with Ramaze.
+
+NOTE: The example and this tutorial differ in some points, it is recommended to
+actually work through the tutorial first and read the example afterwards, it
+takes the basics taught here one step further by utilizing the Model.
+
+You can find the example it in the `examples/app/todolist/` directory of your
+Ramaze distribution.
+To find out where that is located (as this differs widely between systems), you
+can follow these steps in `irb`:
+
+[source,ruby]
+--------------------------------------------------------------------------------
+require 'rubygems'
+# => true
+require 'ramaze'
+# => true
+File.expand_path(Ramaze::BASEDIR + '/../examples/app/todolist')
+# => "/home/manveru/c/ramaze/examples/app/todolist"
+--------------------------------------------------------------------------------
+
+To start things off, we will create a basic directory structure looking like this:
+
+--------------------------------------------------------------------------------
+.
+|-- controller
+|-- layout
+|-- model
+|-- public
+|   |-- css
+`-- view
+--------------------------------------------------------------------------------
+
+Doing that is quite simple: `mkdir -p controller layout model public/css view`
+
+Alright, done? Let's go to the next step.
+
+== Second Step. Hello, World!
+
+To make sure Ramaze is installed, and working correctly we will follow an old
+tradition, we create a file at the root of your application directory called
+'start.rb' with following content:
+
+[source,ruby]
+--------------------------------------------------------------------------------
+require 'rubygems'
+require 'ramaze'
+
+class MainController < Ramaze::Controller
+  def index
+    "Hello, World!"
+  end
+end
+
+Ramaze.start
+--------------------------------------------------------------------------------
+
+Now we run it:
+
+--------------------------------------------------------------------------------
+delta ~/tmp/tutorial % ruby start.rb
+D [2009-03-30 14:15:01 $2124] DEBUG | : Using webrick
+I [2009-03-30 14:15:01 $2124]  INFO | : WEBrick 1.3.1
+I [2009-03-30 14:15:01 $2124]  INFO | : ruby 1.9.2 (2009-03-02) [i686-linux]
+D [2009-03-30 14:15:01 $2124] DEBUG | : TCPServer.new(0.0.0.0, 7000)
+D [2009-03-30 14:15:01 $2124] DEBUG | : Rack::Handler::WEBrick is mounted on /.
+I [2009-03-30 14:15:01 $2124]  INFO | : WEBrick::HTTPServer#start: pid=2124 port=7000
+--------------------------------------------------------------------------------
+
+The logging output tells us that a server was started, listening to all
+connections at port 7000. If you open your browser and go to
+http://localhost:7000/ you should be able to see 'Hello, World!'.
+
+
+== Third Step. M, like Model
+
+Model is a term from the MVC paradigm, meaning the representation of data
+within your application.
+Ramaze doesn't promote a particular way for this part of your application, and
+how you are supposed to integrate it. Since there are quite a number of ways to
+represent data and none is clearly superior to another, this would be both
+futile and short-sighted.
+
+For the purpose of this tutorial we will use a lightweight database access
+toolkit for Ruby called http://sequel.rubyforge.org/[Sequel].
+
+Sequel is designed to take the hassle away from connecting to databases and
+manipulating them. Sequel deals with all the boring stuff like maintaining
+connections, formatting SQL correctly and fetching records so you can
+concentrate on your application.
+
+Being familiar with it is not a requirement for this tutorial, but will help
+you tremendously when it comes to writing your own applications.
+
+Installing Sequel is as simple as installing Ramaze: `gem install sequel`.
+
+In this tutorial we are going to use the light-weight
+http://www.sqlite.org/[sqlite] database.
+This requires the http://rubyforge.org/projects/sqlite-ruby[sqlite-ruby]
+bindings.
+
+You can try to `gem install sqlite`, which will complain if your system doesn't
+provide bindings, in which case I have to refer you to http://sqlite.org.
+
+In order to use Sequel we also need a database connection.
+
+So we create a new file at 'model/init.rb' with following content:
+
+[source,ruby]
+--------------------------------------------------------------------------------
+require 'sequel'
+
+Sequel::Model.plugin(:schema)
+
+DB = Sequel.sqlite('todolist.db')
+--------------------------------------------------------------------------------
+
+The `:schema` plugin is required since Sequel 3.0, if you run a version prior
+to 2.12 you may remove this line if it gives you any problems.
+
+Next we edit 'start.rb', remove the `Hello` class, and add a require for the
+file, 'start.rb' should look like this now:
+
+[source,ruby]
+--------------------------------------------------------------------------------
+require 'rubygems'
+require 'ramaze'
+
+require 'model/init'
+
+Ramaze.start
+--------------------------------------------------------------------------------
+
+This should hook us up with a database, but anyone familiar with SQL will now
+ask how we are going to create our schema.
+
+So our next step is to create the actual model for our data, for this we create another file at 'model/task.rb':
+
+[source,ruby]
+--------------------------------------------------------------------------------
+class Task < Sequel::Model
+  set_schema do
+    primary_key :id
+    
+    varchar :title, :unique => true, :empty => false
+    boolean :done, :default => false
+  end
+
+  create_table unless table_exists?
+
+  if empty?
+    create :title => 'Laundry'
+    create :title => 'Wash dishes'
+  end
+end
+--------------------------------------------------------------------------------
+
+For this tutorial we will not bother with migrations, although Sequel does have
+very good support for them as well, but seriously, this is a really simple
+schema that probably won't change much over the next few years.
+
+Finally, add a line to your 'model/init.rb' that requires 'model/task.rb':
+
+[source,ruby]
+--------------------------------------------------------------------------------
+require 'sequel'
+
+Sequel::Model.plugin(:schema)
+
+DB = Sequel.sqlite('todolist.db')
+
+require 'model/task'
+--------------------------------------------------------------------------------
+
+
+== Fourth Step, V, like View
+
+To see anything of the data in your Model we will have to add the second
+element in MVC, the View.
+
+We are going to use the templating engine shipping with Ramaze, called Etanni.
+It has a very simple syntax compatible with SGML and XML documents.
+
+When handling a request to '/', Ramaze will automatically try to find an Action
+called 'index'. Don't bother too much about what Action means just yet, we will
+explain that in more detail later when we come to layouts.
+
+To start we put some contents into 'view/index.xhtml' (xhtml is the default
+filename-extension for Etanni templates)
+
+[source,html]
+--------------------------------------------------------------------------------
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
+<html>
+  <head>
+    <title>TodoList</title>
+    <meta http-equiv="content-type" content="text/html; charset=UTF-8" />
+  </head>
+  <body>
+    <h1>TodoList</h1>
+    <ul>
+      <?r Task.each do |task| ?>
+        <li>#{ h(task.title) }: #{ task.done }</li>
+      <?r end ?>
+    </ul>
+  </body>
+</html>
+--------------------------------------------------------------------------------
+
+The '<?r ?>' and '\#{ }' elements enclose ruby code that will be executed when
+the template is being rendered (on every request to 'index').
+Code within '<?r ?>' is only executed and will not show up in the resulting
+document, while code within '#{ }' will be interpolated. 
+
+In this template we iterate over all the data stored in the Task model,
+yielding a list of task titles and the respective status of the task.
+
+That wasn't too hard, right?
+
+Now, so we can get our instant pleasure of seeing the result of our (hard)
+work, let's see how this looks like in a browser, start your application like above with `ruby start.rb` and open http://localhost:7000/.
+
+The template expanded to something like (only showing the interesting part):
+
+[source,html]
+--------------------------------------------------------------------------------
+<ul>
+  <li>Laundry: false</li>
+  <li>Wash dishes: false</li>
+</ul>
+--------------------------------------------------------------------------------
+
+That wasn't too bad, huh?
+
+
+== Fifth Step, C, like Controller
+
+The last part of the MVC paradigm is the Controller. As the name indicates it
+gives you control over the interaction between Model and View.
+
+Wouldn't it be nice to have a way to add and remove items on our to-do list?
+Editing the model every time would be quite tiresome and problematic to do
+remotely.
+
+Well, come along, I'll give you a short intro to the concept of controllers.
+
+In the way MVC is structured, the Controller provides the data in a nice way
+for the View, removing all of the data-preparation and most of the logic from
+the templates. This makes it firstly simple to change the front end of your
+application and secondly provides excellent ways of changing the complete
+Structure of the Model or View independent from each other.
+
+OK, enough of the theory, you will see the benefits in an instant, first of all
+we will implement marking a task as done.
+
+Go on and create the file 'controller/task.rb' with following contents:
+
+[source,ruby]
+--------------------------------------------------------------------------------
+class Tasks < Ramaze::Controller
+  map '/'
+
+  def close(title)
+    task = Task[:title => title]
+    task.done = true
+    task.save
+
+    redirect_referrer
+  end
+end
+--------------------------------------------------------------------------------
+
+That does following:
+
+* Define a `Tasks` class as a subclass of `Ramaze::Controller`.
+* Tell Ramaze that a request to '/' goes to this Controller.
+* Define a `#close` method that requires a `title` argument.
+* Query for a task that has the given title.
+* Set the status of the task to done and store the change to the database.
+* Redirect the client to where it came from.
+
+And we add a require to 'controller/task.rb' to our 'start.rb':
+
+[source,ruby]
+--------------------------------------------------------------------------------
+require 'rubygems'
+require 'ramaze'
+
+require 'model/init'
+require 'controller/task'
+
+Ramaze.start
+--------------------------------------------------------------------------------
+
+Next we will have to modify the 'view/index.xhtml' to contain a link that will
+change the status of a task:
+
+[source,html]
+--------------------------------------------------------------------------------
+<ul>
+  <?r Task.each do |task| ?>
+    <li>
+      #{ h(task.title) }: #{ task.done },
+      (#{ anchor('close', 'close', task.title) })
+    </li>
+  <?r end ?>
+</ul>
+--------------------------------------------------------------------------------
+
+Now we have an additional link next to each task that allows us to set it to
+done.
+
+An even shorter way of writing that line using default aliases, that you will
+encounter in other applications, is:
+
+[source,ruby]
+--------------------------------------------------------------------------------
+a('close', 'close', task.title)
+--------------------------------------------------------------------------------
+
+But for the purpose of this tutorial we'll try to be as explicit as possible.
+
+Now that's a lot of things at once, but I'm sure you will be able to keep up,
+the hardest part is behind us.
+
+Don't forget to try the new functionality in your browser, wash your dishes and
+do your laundry and come back for the next episode.
+
+== Sixth Step, Clean, Rinse, Repeat
+
+Now that you have closed (and hopefully done) all of your chores, it's time to
+open them again, so you won't be without work tomorrow.
+
+Let's add a method to our Controller that will let us open a closed task:
+
+[source,ruby]
+--------------------------------------------------------------------------------
+class Tasks < Ramaze::Controller
+  map '/'
+
+  def close(title)
+    task = Task[:title => title]
+    task.done = true
+    task.save
+
+    redirect_referrer
+  end
+
+  def open(title)
+    task = Task[:title => title]
+    task.done = false
+    task.save
+
+    redirect_referrer
+  end
+end
+--------------------------------------------------------------------------------
+
+And add a link to that action:
+
+[source,html]
+--------------------------------------------------------------------------------
+<ul>
+  <?r Task.each do |task| ?>
+    <li>
+      #{ h(task.title) }: #{ task.done },
+      (#{ anchor('close', 'close', task.title) })
+      (#{ anchor('open', 'open', task.title) })
+    </li>
+  <?r end ?>
+</ul>
+--------------------------------------------------------------------------------
+
+OK, nothing new here, move along.
+
+Oh, wait!
+
+Rumor has it that some mad Japanese scientist got screwed by his company (they
+produce dishwashers), so he filed a patent for the ultimate dish washing robot
+that will take care of that for you.
+
+Time to get rid of that task once and for all. No more dish washing yay!
+
+A little modification to Controller, using destructive force.
+
+[source,ruby]
+--------------------------------------------------------------------------------
+class Tasks < Ramaze::Controller
+  map '/'
+
+  def close(title)
+    task = Task[:title => title]
+    task.done = true
+    task.save
+
+    redirect_referrer
+  end
+
+  def open(title)
+    task = Task[:title => title]
+    task.done = false
+    task.save
+
+    redirect_referrer
+  end
+
+  def delete(title)
+    task = Task[:title => title]
+    task.destroy
+
+    redirect_referrer
+  end
+end
+--------------------------------------------------------------------------------
+
+And a link to the `delete` action.
+
+[source,html]
+--------------------------------------------------------------------------------
+<ul>
+  <?r Task.each do |task| ?>
+    <li>
+      #{ h(task.title) }: #{ task.done },
+      (#{ anchor('close', 'close', task.title)})
+      (#{ anchor('open', 'open', task.title)})
+      (#{ anchor('delete', 'delete', task.title)})
+    </li>
+  <?r end ?>
+</ul>
+--------------------------------------------------------------------------------
+
+And dish-washing begone!
+
+
+== Seventh Step, More Tasks
+
+Sure, it would be nice if life was so simple and you only have to do your
+laundry, but that would mean a premature end for this tutorial and an obstacle
+for GTD evangelists (not that they couldn't overcome it).
+
+So now you got a smart new robot that washes your dishes, but unfortunately it
+wasn't programmed to recharge once in a while and buy soap, no biggie, we can
+do that with little effort, but since reddit takes up all your time you keep
+forgetting about it.
+
+No problem, I say, adding following code to our 'view/index.xhtml' will give us
+a nice little form that we can fill out in the few seconds between proving
+people on the internet wrong.
+
+[source,html]
+--------------------------------------------------------------------------------
+<form method="post" action="#{ route('create') }">
+  <fieldset>
+    <legend>Add a task by entering a title.</legend>
+    <label for="form-title">Task title:</label>
+    <input id="form-title" name="title" type="text" />
+    <input type="submit" value="Create" />
+  </fieldset>
+</form>
+--------------------------------------------------------------------------------
+
+Unfortunately, you see, this references the `create` action, and we have none
+yet. Trying to create a task will result in an error.
+
+So what we have to do is adding one more method to our Controller that will
+take care of actually creating the Task.
+
+[source,ruby]
+--------------------------------------------------------------------------------
+def create
+  if request.post? and title = request[:title]
+    title.strip!
+
+    unless title.empty?
+      Task.create :title => title
+    end
+  end
+
+  redirect route('/')
+end
+--------------------------------------------------------------------------------
+
+What is going on here?
+
+* Check whether the request was using the HTTP POST method and actually sent a
+  title with it.
+* Strip all whitespace from beginning and end of the title.
+* If the title still has something in it we go on and create a task with that
+  title.
+* Redirect back to the `index`
+
+== Eighth Step, Eep, Exceptions!
+
+So far, so good, but remember, when we defined the schema for `Task` we said we
+really want to have unique titles.
+
+So once you created the task 'recharge DishBot9000' and try to create another
+one with the same title, you will get a nice error:
+
+ Sequel::DatabaseError: SQLite3::SQLException column title is not unique
+
+OK, programmers ignore warnings and hide errors, let's rescue the exception and
+just act as if nothing has happened.
+
+[source,ruby]
+--------------------------------------------------------------------------------
+class Tasks < Ramaze::Controller
+  map '/'
+
+  def create
+    if request.post? and title = request[:title]
+      title.strip!
+
+      unless title.empty?
+        Task.create :title => title
+      end
+    end
+
+    redirect route('/')
+  rescue Sequel::DatabaseError
+    redirect route('/')
+  end
+
+  def close(title)
+    # ...
+--------------------------------------------------------------------------------
+
+Easy as pie, we can try to create as many identical tasks as we want, all we
+get is the same old set.
+
+
+== Ninth Step, Curing your RSI
+
+Something you might notice is that every time you hit the submit button and you are redirected to `index`, the title you just input is gone.
+What a waste of our honest effort to create a duplicate task, we all know if we
+try often enough it will eventually have to work, so let's save us some typing.
+
+In our 'view/index.xhtml' we modify the form input to have a default value:
+
+[source,html]
+--------------------------------------------------------------------------------
+<form method="post" action="#{ route('create') }">
+  <fieldset>
+    <legend>Add a task by entering a title.</legend>
+    <label for="form-title">Task title:</label>
+    <input id="form-title" name="title" type="text" value="#{ @title }"/>
+    <input type="submit" value="Create" />
+  </fieldset>
+</form>
+--------------------------------------------------------------------------------
+
+The `@title` is an instance-variable, those are shared between the Controller
+and View.
+We didn't set any such variable in the Controller yet, so do it now:
+
+[source,ruby]
+--------------------------------------------------------------------------------
+class Tasks < Ramaze::Controller
+  map '/'
+
+  def index
+    @title = 'recharge DishBot9000'
+  end
+
+  def create
+    # ...
+--------------------------------------------------------------------------------
+
+Yes, that wasn't too bad, but is there a way to change the value of the
+`@title` without editing the source all the time?
+
+Turns out we have to revisit the `create` method to give us a hint in form of a
+GET parameter and change `index` to pick it up.
+
+[source,ruby]
+--------------------------------------------------------------------------------
+  def index
+    @title = request[:title]
+  end
+
+  def create
+    if request.post? and title = request[:title]
+      title.strip!
+
+      unless title.empty?
+        Task.create :title => title
+      end
+    end
+
+    redirect route('/', :title => title)
+  rescue Sequel::DatabaseError
+    redirect route('/', :title => title)
+  end
+--------------------------------------------------------------------------------
+
+And that's it.
+Endless hours of fun hitting the submit button lie before us!
+
+
+== Tenth Step, Laying out a different View of things
+
+We have one template, it's a nice one, but unfortunately we've got ourselves
+into quite a mess here after creating hundreds of tasks.
+
+Our way out of this is to provide some visual feedback -- when a task is done,
+it's gone.
+Not forever, but at least it will not show up anymore on the `index` action.
+
+So we filter out all tasks that haven't been done yet in the
+'view/index.xhtml':
+
+[source,html]
+--------------------------------------------------------------------------------
+<ul>
+  <?r Task.filter(:done => false).each do |task| ?>
+    <li>
+      # ...
+--------------------------------------------------------------------------------
+
+
+So off we go and add a new template at 'view/done.xhtml'.
+
+[source,html]
+--------------------------------------------------------------------------------
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
+<html>
+  <head>
+    <title>TodoList</title>
+    <meta http-equiv="content-type" content="text/html; charset=UTF-8" />
+  </head>
+  <body>
+    <h1>TodoList</h1>
+
+    <form method="post" action="#{ route('create') }">
+      <fieldset>
+        <legend>Add a task by entering a title.</legend>
+        <label for="form-title">Task title:</label>
+        <input id="form-title" name="title" type="text" value="#{ @title }"/>
+        <input type="submit" value="Create" />
+      </fieldset>
+    </form>
+
+    <h2>Tasks done</h2>
+
+    <ul>
+      <?r Task.filter(:done => true).each do |task| ?>
+        <li>
+          #{ h(task.title) }: #{ task.done },
+          (#{ anchor('open', 'open', task.title) })
+          (#{ anchor('delete', 'delete', task.title) })
+        </li>
+      <?r end ?>
+    </ul>
+  </body>
+</html>
+--------------------------------------------------------------------------------
+
+Having a déjà vu?
+
+Yes, me too, must be an error in the matrix.
+
+If we want one thing from a web-framework, it's to spare us writing repetitive
+code like this (I hope you did copy&paste).
+
+What we actually wanted to do is _sharing_ the boilerplate around our listing
+of tasks, that's what we call 'layout'.
+
+Every action can have a layout associated with it, remember that empty 'layout'
+directory in your application? That's exactly where we will put it.
+
+[source,html]
+--------------------------------------------------------------------------------
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
+<html>
+  <head>
+    <title>TodoList</title>
+    <meta http-equiv="content-type" content="text/html; charset=UTF-8" />
+  </head>
+  <body>
+    <h1>TodoList</h1>
+    <form method="post" action="#{ route('create') }">
+      <fieldset>
+        <legend>Add a task by entering a title.</legend>
+        <label for="form-title">Task title:</label>
+        <input id="form-title" name="title" type="text" value="#{ @title }"/>
+        <input type="submit" value="Create" />
+      </fieldset>
+    </form>
+    #{ @content }
+  </body>
+</html>
+--------------------------------------------------------------------------------
+
+And to tell Ramaze which layout to use for our `Tasks` we'll have to add a line
+to the Controller.
+
+[source,ruby]
+--------------------------------------------------------------------------------
+class Tasks < Ramaze::Controller
+  map '/'
+  layout 'default'
+end
+--------------------------------------------------------------------------------
+
+And finally, since we are fond of valid HTML and just love to get rid of boring
+boilerplate we can delete the slack from our templates.
+
+'view/index.xhtml' becomes:
+
+[source,html]
+--------------------------------------------------------------------------------
+<h2>Done Tasks</h2>
+
+#{ anchor('Pending tasks', 'done') }
+
+<ul>
+  <?r Task.filter(:done => false).each do |task| ?>
+    <li>
+      #{ h(task.title) },
+      (#{ anchor('close', 'close', task.title) })
+      (#{ anchor('delete', 'delete', task.title) })
+    </li>
+  <?r end ?>
+</ul>
+--------------------------------------------------------------------------------
+
+'view/done.xhtml' becomes:
+
+[source,html]
+--------------------------------------------------------------------------------
+<h2>Pending Tasks</h2>
+
+#{ anchor('Done tasks', 'done') }
+
+<ul>
+  <?r Task.filter(:done => true).each do |task| ?>
+    <li>
+      #{ h(task.title) },
+      (#{ anchor('open', 'open', task.title) })
+      (#{ anchor('delete', 'delete', task.title) })
+    </li>
+  <?r end ?>
+</ul>
+--------------------------------------------------------------------------------
+
+Well, that's so much better, we even included links between the actions.
+
+
+== Eleventh Step, not all that is gold glitters...
+
+You have to admit, it's a lot of fun having such a sophisticated application,
+but what good is it if it's too ugly to show it even to your closest friends?
+They will never become addicted enough to your fancy todo-list to actually do
+all the work for you.
+
+Let's do things with style, with a style-sheet.
+
+Now is the time to fire up your editor, point it at 'public/css/screen.css' and
+churn out something of your liking.
+
+We will not cover this part in the tutorial, an example style-sheet is located
+in the example todo-list.
+
+What we do cover is adding it to your application, or the `<head>` in
+'layout/default.xhtml' to be exact:
+
+[source,html]
+--------------------------------------------------------------------------------
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
+<html>
+  <head>
+    <title>TodoList</title>
+    <meta http-equiv="content-type" content="text/html; charset=UTF-8" />
+    <link rel="stylesheet" type="text/css" href="/css/screen.css" />
+  </head>
+--------------------------------------------------------------------------------
+
+Voilà, you now have acquired the Certificate of Ramazeness and all your friends
+and enemies envy you.
+
+
+== Twelfth Step, configuring configurable configurability
+
+To round up this tutorial a bit, let's introduce you to configuration in Ramaze.
+There are a number of ways to configure Ramaze, but here we'll just see the
+most common ones with some options you'll most likely want to change.
+
+First of all, you have been running your ramaze application always on the same
+port, `7000`, which prevents you from starting more than one instance or other
+applications.
+
+To change the port, you can, for example:
+
+[source,ruby]
+--------------------------------------------------------------------------------
+Ramaze.options.adapter.port = 80
+--------------------------------------------------------------------------------
+
+NOTE: Running a server on a port below 1024 will require root privileges and is
+      generally not advised for applications that don't drop their privileges
+      after establishing a connection.
+      Please have a look at http://wiki.ramaze.net/Deployment for better ways
+      to deploy your site using a reverse proxy like apache, lighttpd, or
+      nginx.
+
+OK, a different port is fine, but how about some speed-boost? For this we will
+need a faster server like http://mongrel.rubyforge.org[Mongrel] or
+http://thin.rubyforge.org[Thin].
+
+You can install either one via:
+
+--------------------------------------------------------------------------------
+gem install thin
+gem install mongrel
+--------------------------------------------------------------------------------
+
+Now to the configuration:
+
+[source,ruby]
+--------------------------------------------------------------------------------
+# The default is WEBrick
+Ramaze.options.adapter.adapter = :webrick
+
+# How about using Mongrel instead?
+Ramaze.options.adapter.adapter = :mongrel
+
+# Or maybe Thin?
+Ramaze.options.adapter.adapter = :thin
+--------------------------------------------------------------------------------
+
+For the full performance, switch Ramaze into `:live` mode:
+
+[source,ruby]
+--------------------------------------------------------------------------------
+# The default is :dev
+Ramaze.options.mode = :live
+
+# And here comes :live
+Ramaze.options.mode = :live
+--------------------------------------------------------------------------------
+
+The major differences between `:dev` and `:live` are that in `:live` mode your
+code won't be automatically reloaded if it has changed and we don't run every
+request through `Rack::Lint`, which helps you to stay within the
+request/response specifications required by Rack.
+
+
+[[glossary]]
+== Glossary
+
+[glossary]
+RDBMS::
+  Relational Database Management System
+ORM::
+  Object Relationship Mapper: Maps data into objects and assists in querying
+  and manipulation 
+MVC::
+  Model, View, Controller: one of the patterns traditionally used for GUIs in Smalltalk.
+Etanni::
+  Innate spelled backwards.
+Innate::
+  Core of Ramaze.
+Rack::
+  HTTP abstraction layer and interface used by the majority of Ruby web-frameworks.
+Templating engine::
+  Used to process so-called templates with inlined source code or instructions
+  to produce dynamic resulting documents. Examples for traditional templating
+  engines are XSLT, SSI, ERB.
+RSI::
+  Repetive Strain Injury, prevalent among the members of the church of Emacs.