ramaze 0.1.0 → 0.1.1

data/doc/tutorial/{todolist.txt → todolist.mkd}

@@ -1,5 +1,7 @@
 # To-do List Tutorial
 
+## Step Zero, Introduction
+
 Welcome to our official tutorial, the mandatory to-do list.
 I'm writing this while doing the steps to assure it will work for you.
 
@@ -20,6 +22,11 @@ There is also a Mailing list available where you can keep yourself updated on
 what is going on with little effort, it is also located on the project-page at
 RubyForge.
 
+Additionally, we now have added tests for the resulting application that you
+can find in spec/examples/todolist.rb
+
+Date of last update: Thu May 24 20:53:49 JST 2007
+
 Thanks in advance.
 The author of the tutorial, Michael 'manveru' Fellinger
 
@@ -41,16 +48,9 @@ done.
 
 Ramaze comes at the moment only with a simple wrapper of the YAML::Store.
 So we are going to base this on the tools available, you can just do the same
-with your ORM or database of choice.
-
-So first, edit the `src/model.rb`, it is filled with the definition of a simple
-YAML::Store already, so we are just gonna modify it a bit to use our wrapper.
+with your ORM or database-library of choice.
 
-Instead of 'yaml/store' use:
-
-    require 'ramaze/store/default'
-
-And further:
+So first, edit the `src/model.rb` to fit better into our application:
 
     TodoList = Store::Default.new 'todolist.yaml'
 
@@ -60,8 +60,8 @@ To have a base to start off of, let's add some items as well.
       'Laundry'     => {:done => false},
       'Wash dishes' => {:done => false},
 
-    }.each do |title, parameters|
-      TodoList[title] = parameters
+    }.each do |title, value|
+      TodoList[title] = value
     end
 
 
@@ -83,8 +83,8 @@ simple.
         <h1>TodoList</h1>
         <ul>
           <?r
-            TodoList.each do |title, parameters|
-              status = parameters[:done] ? 'done' : 'not done'
+            TodoList.each do |title, value|
+              status = value[:done] ? 'done' : 'not done'
             ?>
             <li>#{title}: #{status}</li>
           <?r end ?>
@@ -95,10 +95,10 @@ simple.
 I will assume that you are familiar with basic Ruby already, so let's
 concentrate on the things new here.
 
-<?r ?> defines an area of ruby-code. Late when the template is transformed into
+`<?r ?>` defines an area of ruby-code. Late when the template is transformed into
 pure Ruby it will be evaluated. We iterate over the TodoList model and pass the
-title and parameters into a block. In that block we can just get the values
-of title and status (which we define based on the parameters) displayed on the
+title and value into a block. In that block we can just get the values
+of title and status (which we define based on the value) displayed on the
 page.
 
 The whole Template would expand to something like this (only showing the
@@ -135,7 +135,7 @@ Well, come along, I'll introduce you to Controller.
 
 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 fronted of your
+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.
 
@@ -150,17 +150,17 @@ The contents of it are like following:
       end
     end
 
-The only method right now is #index, with a simple and for the moment quite
+The only method right now is `#index`, with a simple and for the moment quite
 useless "Hello, World". The relationship between the methods on the controller
-and the templates is 1:1, so the method #index is combined with the template
+and the templates is 1:1, so the method `#index` is combined with the template
 `index.xhtml`. This combination is called an `action`.
 
 Let's get back to editing and change the index-method to this:
 
     def index
       @tasks = TodoList.content
-      @tasks.each do |title, parameters|
-        status = parameters[:done] ? 'done' : 'not done'
+      @tasks.each do |title, value|
+        status = value[:done] ? 'done' : 'not done'
         @tasks[title] = status
       end
     end
@@ -174,7 +174,6 @@ changed to do following:
       </head>
       <body>
         <h1>TodoList</h1>
-        <a href="/new">New Task</a>
         <?r if @tasks.empty? ?>
           No Tasks
         <?r else ?>
@@ -219,7 +218,7 @@ Open a new file `template/new.xhtml` with a form to add a new task.
         <a href="/">Back to TodoList</a>
         <form method="POST" action="create">
           Task: <input type="text" name="title" /><br />
-          <inpyt type="submit" />
+          <input type="submit" />
         </form>
       </body>
     </html>
@@ -240,19 +239,19 @@ moment, the request and response and the contents of the session. This is very
 useful for debugging and development, you can provide your own set of
 error-pages before going into production (or deactivate them fully) though.
 
-OK, let's implement the action for #create, all we want to do is take the
+OK, let's implement the action for `#create`, all we want to do is take the
 requests parameters and create a new task for it, this looks like following on
 your MainController.
 
     def create
       title = request['title']
       TodoList[title] = {:done => false}
-      redirect R(self)
+      redirect Rs()
     end
 
 That's all folks!
 
-we get the title from the request-object, put it into our TodoList as undone
+We get the title from the request-object, put it into our TodoList as undone
 and redirect back to the mapping of the current Controller ('/' in this case).
 
 Now you can create as many tasks as you want, please don't get overworked ;)
@@ -268,7 +267,7 @@ Jump into `template/index.xhtml` and do the following:
 
     <?r @tasks.each do |title, status, toggle| ?>
       <li>
-        #{title}: #{status} - #{toggle}
+        #{title}: #{status} - [ #{toggle} ]
       </li>
     <?r end ?>
 
@@ -278,13 +277,13 @@ we go and change the index method on the controller once again:
 
     def index
       @tasks = []
-      TodoList.original.each do |title, parameters|
-        if parameters[:done]
+      TodoList.original.each do |title, value|
+        if value[:done]
           status = 'done'
-          toggle = link( R( self, :open, CGI.escape(title) ), :title => 'Open Task' )
+          toggle = A('Open Task', :href => Rs(:open, title))
         else
           status = 'not done'
-          toggle = link( R( self, :close, CGI.escape(title) ), :title => 'Close Task' )
+          toggle = A('Close Task', :href => Rs(:close, title))
         end
         @tasks << [title, status, toggle]
       end
@@ -294,12 +293,12 @@ we go and change the index method on the controller once again:
 Wow, quite some new stuff here. Let me explain that in detail.
 
 We first decide whether a task is done or not, then go on and provide a link to
-toggle the status, link and R are both methods that help you do that.
-the result will be something like:
+toggle the status, A and Rs are both methods that help you do that.
+The result will be something like:
 
     <a href="/open/Wash+dishes">Close Task</a>
 
-R actually is responsible to build the links href, for more information please
+Rs actually is responsible to build the links href, for more information please
 take a look at the RDoc for LinkHelper.
 
 Also, you might have noticed that the tasks were changing order on every reload,
@@ -321,12 +320,12 @@ corresponding methods to the Controller:
 
     def open title
       task_status title, false
-      redirect R(self)
+      redirect Rs()
     end
 
     def close title
       task_status title, true
-      redirect R(self)
+      redirect Rs()
     end
 
     private
@@ -338,9 +337,9 @@ corresponding methods to the Controller:
     end
 
 Oh, now what have we got here?
-private declares that methods from here on are only to be used within the
-Controller itself, we define an #task_status method that takes the title and
-status to be set so we don't have to repeat that code in _#open_ and _#close_
+`private` declares that methods from here on are only to be used within the
+Controller itself, we define an `#task_status` method that takes the title and
+status to be set so we don't have to repeat that code in `#open` and `#close`
 and follow the DRY (Don't repeat yourself) paradigm.
 
 Another thing we have not encountered so far is that you can define your public
@@ -352,7 +351,7 @@ will translate into:
 
     open('Wash dishes')
 
-Which in turn will call task_status('Wash dishes', false)
+Which in turn will call `task_status('Wash dishes', false)`
 
 That's it, go on and try it :)
 
@@ -364,14 +363,14 @@ consider is to delete a task permanently.
 This is just two little changes away, so let's add the link for deletion in our
 Controller:
 
-    delete = link( R( self, :delete, CGI.escape(title) ), :title => 'Delete' )
+    delete = A('Delete', :href => Rs(:delete, title))
     @tasks << [title, status, toggle, delete]
 
 and an corresponding method while we're at it:
 
     def delete title
       TodoList.delete title
-      redirect R(self)
+      redirect Rs()
     end
 
 Now jumping to `template/index.xhtml` again, change it so it shows the link:
@@ -394,7 +393,7 @@ explain some more advanced concepts of Ramaze and the templating.
     <Page></Page>
 
 This is called an Element, Ramaze will go and search for a class that matches
-the name Page and responds to _#render_. Then it will go and hand the content in
+the name Page and responds to `#render`. Then it will go and hand the content in
 between to that Element.
 
 Sounds weird?
@@ -423,7 +422,7 @@ So let's apply DRY here as well.
 
 Take a look at the `src/element/page.rb`
 
-    class Page < Element
+    class Page < Ezamar::Element
       def render
         %{
         <html>
@@ -439,13 +438,13 @@ Take a look at the `src/element/page.rb`
     end
 
 Alright, most things we need are in place already, the most important thing
-is the _#content_ method that we call with _#{content}_ inside the string in
-_#render_.
+is the `#content` method that we call with `#{content}` inside the string in
+`#render`.
 
 Just adopt it to your liking, I'll just use the things we had in our templates
 so far:
 
-    class Page < Element
+    class Page < Ezamar::Element
       def render
         %{
         <html>
@@ -498,7 +497,8 @@ the things inside the Element and look at how it behaves.
 
 ## Ninth Step, Prettify
 
-Let's structure the data inside the list a little bit, in this case into a table to get it line up properly and look actually structured.
+Let's structure the data inside the list a little bit, in this case into a table
+to get it line up properly and look actually structured.
 
 So, from what we have right now:
 
@@ -523,7 +523,8 @@ To something like this:
       <?r end ?>
     </table>
 
-And, since we have proper classes to address some style sheets, jump into the Page element and add some style sheet like that:
+And, since we have proper classes to address some style sheets, jump into the
+Page element and add some style sheet like that:
 
     <head>
       <title>TodoList</title>
@@ -537,9 +538,208 @@ And, since we have proper classes to address some style sheets, jump into the Pa
       </style>
     </head>
 
-That looks quite a bit nicer, right?
-And yes, if you don't like tables (though this is an entirely legit use in my opinion, you can just do it like you want, using nested lists or divs/spans, replacing the open/close and delete links with nice images and changing the style according to the status.
+That looks quite a bit nicer, right?  And yes, if you don't like tables (though
+this is an entirely legit use in my opinion, you can just do it like you want,
+using nested lists or divs/spans, replacing the open/close and delete links with
+nice images and changing the style according to the status.
 
 I will leave this as an exercise to the reader.
 
+
+## Tenth Step, Configuration
+
+To round up this tutorial a bit, let's introduce you to configuration in Ramaze.
+This will not go into full depth of possibilities or a total coverage of the
+options, since they are bound to change over time.
+
+First of all, the default port Ramaze runs on is 7000, but to make it a usual
+webserver it has to run on port 80.  So, let's add following line in your
+main.rb right after the lines of require you added before:
+
+    Ramaze::Global.port = 80
+
+Alright, that wasn't that hard.
+Let's say now you also want to run Mongrel instead of WEBrick, to get nice a bit
+of performance:
+
+    Ramaze::Global.adapter = :mongrel
+
+To do this in a DRY way you could also do following:
+
+    Ramaze::Global.setup do |g|
+      g.port = 80
+      g.adapter = :mongrel
+    end
+
+It seems to be quite common to put this configuration into separate files so you
+can just require it on demand.  There are other, slightly stronger way to set
+options, which is either using flags on the ramaze executable, or like this:
+
+    Ramaze.start :port => 80, :adapter => :mongrel
+
+We haven't started Ramaze directly as of yet, but this allows you to ignore the
+ramaze executable and just run your application.
+
+
+## Eleventh Step, Refactor with AspectHelper
+
+Now, if you take a closer look at the Controller you will see:
+
+    def create
+      title = request['title']
+      TodoList[title] = {:done => false}
+      redirect R(self)
+    end
+
+    def open title
+      task_status title, false
+      redirect R(self)
+    end
+
+    def close title
+      task_status title, true
+      redirect R(self)
+    end
+
+    def delete title
+      TodoList.delete title
+      redirect R(self)
+    end
+
+We did some refactoring before, by introducing `#task_status`, but here we have
+repetition again: `redirect Rs()` _after_ each method did its job.
+
+However, we can take advantage of one of the helpers Ramaze offers, the
+AspectHelper.
+It allows you to easily wrap actions in your controller with other methods
+
+In your Controller, replace the previous chunk with following:
+
+    def create
+      title = request['title']
+      TodoList[title] = {:done => false}
+    end
+
+    def open title
+      task_status title, false
+    end
+
+    def close title
+      task_status title, true
+    end
+
+    def delete title
+      TodoList.delete title
+    end
+
+    helper :aspect
+    after(:create, :open, :close, :delete){ redirect_index }
+
+    def redirect_index
+      redirect Rs()
+    end
+
+Alright, that looks a lot nicer already and is definitely easier to maintain.
+Please note that the `#redirect_index` method should not be private, as it is a
+usual action that will just run after the others.
+
+There is a symmetrical `#before` aspect that you could take advantage of as well,
+and in case you want to add required authentication for all actions of a
+Controller you could use `#before_all` instead of a list of action-names.
+
+
+## Twelfth Step, Validation and Errors
+
+Right now, all kinds of things could still go wrong when you do things like
+creating tasks with no title at all or try to open/close a task that does not
+exist. So in this step we will add some little checks for these cases.
+
+First we head over to the Controller again and take a look at `#create`:
+
+    def create
+      title = request['title']
+      TodoList[title] = {:done => false}
+    end
+
+Here we just create a new task, no matter what we get. Every seasoned
+web-developer would advise you to be suspicious about all the input you receive
+from your users, so let's apply this advice.
+
+    def create
+      if title = request['title']
+        title.strip!
+        if title.empty?
+          error("Please enter a title")
+          redirect '/new'
+        end
+        TodoList[title] = {:done => false}
+      end
+    end
+
+First of all we check if we got a request with a value for 'title', if we get
+none we just let the aspect kick in that will redirect the browser to the index.
+Next we strip the title of all spaces around it so we can check if it is empty.
+We will talk about the specifics of our error-handling now.
+
+Ramaze has a helper called FlashHelper, that will keep a hash associated with
+the session for one request, afterwards the hash is thrown away. This is
+specifically useful for giving the user feedback while keeping a stateless
+approach.
+
+Let me show you our `#error` method (it goes in the private section to
+`#task_status`):
+
+    def error(message)
+      flash[:error] = message
+    end
+
+Duh, you may say, wouldn't that fit in the one line instead of the call to
+`#error`?
+Indeed, it would, but let me remind you, we have no checks for changing the
+status of a task yet. We will need error-handling there as well, so we just keep
+our code DRY and maintainable by collecting shared behaviour in small pieces.
+
+Now on to the `#task_status`:
+
+    def task_status title, status
+      unless task = TodoList[title]
+        error "No such Task: `#{title}'"
+        redirect_referer
+      end
+
+      task[:done] = status
+      TodoList[title] = task
+    end
+
+That used to look like this:
+
+    def task_status title, status
+      task = TodoList[title]
+      task[:done] = status
+      TodoList[title] = task
+    end
+
+So in fact all we added is a check whether a task already exists, set an
+error-message in case it doesn't and redirect to wherever the browser came from.
+
+But what about actually showing the error-messages we so carefully set? Well,
+where do we change the view? Right, in the templates. But both templates we have
+so far (index and new) share this behaviour, so let's head over to the Element
+and add in the right place:
+
+    <body>
+      <h1>#{@title}</h1>
+      <?r if flash[:error] ?>
+        <div class="error">
+          \\#{flash[:error]}
+        </div>
+      <?r end ?>
+      #{content}
+    </body>
+
+The only thing special about it is the `\\#{flash[:error]}`, we have to escape
+the `#` so it won't evaluate this immediately but wait until it is really
+rendered.
+You can add some nifty style if you like.
+
 To be continued...