ramaze 0.0.7 → 0.0.8

data/doc/readme_chunks/appendix.txt

@@ -0,0 +1,13 @@
+* Nicer Error-pages
+  * Install coderay (it's a gem)
+
+* Performance
+  * Serving
+  
+    For best performance you should consider using Mongrel to host your
+    application.
+
+  * Caching
+  
+    You can easily cache your pages using the CacheHelper.
+    Also, using MemCache gives you high-end performance and security.

data/doc/readme_chunks/examples.txt

@@ -0,0 +1,38 @@
+There are some examples for your instant pleasure inside the examples-directory
+in the Ramaze-distribution.
+To start up an example, you can use the Ramaze binary located in bin/ramaze 
+for example:
+
+  $ ramaze examples/hello.rb
+
+Or:
+
+  $ cd examples/blog
+  $ ramaze
+
+Since ramaze uses the main.rb by default if you don't pass anything else.
+
+For more information about the usage of ramaze try:
+
+  $ ramaze --help
+
+
+Examples include:
+
+* examples/hello.rb
+  Hello, World!
+
+* examples/simple.rb
+  A bit more advanced than the hello-example, but still very basic.
+
+* examples/blog
+  Not yet fully functional, but coming along.
+
+* examples/whywiki
+  A basic examples of a minimalistic application, based on the Wiki of _why in
+  his camping-framework.
+
+* examples/templates
+  examples of real usage of the templating-engines. Tries to implement the same
+  functionality in each template_*.rb file using a different engine.
+

data/doc/readme_chunks/features.txt

@@ -0,0 +1,82 @@
+Ramaze offers following features at the moment:
+
+* Adapters
+
+   Ramaze takes advantage of the rack library to provide a common way of
+   handling different ways to serve its content.
+
+   Rack supports at the moment:
+
+    * Mongrel
+
+      http://mongrel.rubyforge.org/
+      Mongrel is a fast HTTP library and server for Ruby that is intended for
+      hosting Ruby web applications of any kind using plain HTTP rather than
+      FastCGI or SCGI.
+
+    * WEBrick
+
+      http://www.webrick.org/
+      WEBrick is a Ruby library program to build HTTP servers.
+
+    * CGI
+
+      CGI is the Common Gateway Interface and is one of the most basic ways
+      to integrate into Webservers like Apache, Lighttpd or Nginx.
+
+
+* Templates
+  * Amrita2
+
+    http://amrita2.rubyforge.org/
+    Amrita2 is a xml/xhtml template library for Ruby. It makes html documents
+    from a template and a model data.
+
+  * Erubis
+
+    http://rubyforge.org/projects/erubis
+    Erubis is a fast, secure, and very extensible implementation of eRuby.
+
+  * Haml
+
+    http://haml.hamptoncatlin.com/
+    Haml takes your gross, ugly templates and replaces them with veritable Haiku.
+
+  * Liquid
+
+    http://home.leetsoft.com/liquid
+    Liquid's syntax and parse model are inspired by Django templates, as well
+    as PHP's smarty.
+
+  * Markaby
+
+    http://code.whytheluckystiff.net/markaby/
+    Markaby means Markup as Ruby.
+
+  * Ezamar
+
+    A simple homage to Nitros templating. Please check out http://nitroproject.org
+    for more information.
+
+* Cache
+  * Hash
+  * YAML::Store
+  * MemCache
+
+* Helper
+  * Aspect
+  * Auth
+  * Cache
+  * Feed
+  * Flash
+  * Form
+  * Link
+  * OpenID
+  * Redirect
+  * Stack
+
+* Various
+  * Sessions
+  * Global configuration system
+  * Simple request/response handling
+  * Custom Error-handling

data/doc/readme_chunks/getting_help.txt

@@ -0,0 +1,5 @@
+For help you can:
+
+- Visit us in the channel #ramaze on irc.freenode.net
+
+- Join the Mailinglist at http://ramaze.rubyforge.org

data/doc/readme_chunks/getting_started.txt

@@ -0,0 +1,18 @@
+Now that you have a vague idea of what you're about to get into you might just
+want to get a way to get up and running ASAP.
+Please read below for more information about installation.
+
+Depending on what you are planning to do you can either just go and start
+reading the source or directly get some hands-on experience by trying some of
+the examples.
+Most things will require dependencies though. The basic functionality is
+provided by the WEBrick adapter and the Template::Ramaze, which just run out
+of the box. For more features you will have to install some templating-engines
+and mongrel (_very_ recommended). Ramaze will inform you when it needs further
+dependencies, so just go and try some things.
+
+Some places to get started are:
+- Read the documentation.
+- Run and read the test cases.
+- Look at the examples and run/modify them.
+

data/doc/readme_chunks/installing.txt

@@ -0,0 +1,41 @@
+* via RubyGems
+
+  The simplest way of installing Ramaze is via 
+
+    $ gem install ramaze
+
+  in case you have RubyGems installed.
+  (this will work as soon as I have registered on RubyForge ;)
+
+* via darcs
+
+  To get the latest and sweetest, you can just pull from the repository and run
+  Ramaze that way.
+
+    $ darcs get http://manveru.mine.nu/ramaze
+
+  Please read the man page or `darcs help` for more information about updating
+  and creating your own patches.
+  This is at the moment the premier way to use Ramaze, since it is the way I use
+  it.
+
+  Some hints for the usage of Darcs.
+
+  * use require 'ramaze' from everywhere
+
+    add a file to your site_ruby named 'ramaze.rb'
+    the content should be: "require '/path/to/darcs/repo/ramaze/lib/ramaze'"
+
+  * get the latest version (from inside the ramaze-directory)
+
+    $ darcs pull
+
+  * record a patch
+
+    $ darcs record
+
+  * output your patches into a bundle ready to be mailed (compress it before
+    sending to make sure it arrives in the way you sent it)
+
+    $ darcs send -o ramaze_bundle
+    $ gzip -c ramaze_bundle > ramaze_bundle.gz

data/doc/readme_chunks/introduction.txt

@@ -0,0 +1,18 @@
+Ramaze is a very simple and straight-forward web-framework.
+The philosophy of it could be expressed in a mix of KISS and POLS, trying to
+make simple things simple and complex things possible.
+
+This of course is nothing new to anyone who knows some ruby, but is often
+forgotten in a chase for new functionality and features. Ramaze only tries to
+give you the ultimate tools, but you have to use them yourself to achieve
+perfect custom-tailored results.
+
+Another one of the goals during development of Ramaze was to make every part as
+modular and therefor reuasable as possible, not only to provide a basic
+understanding after the first glance, but also to make it as simple as possible
+to reuse parts of the code.
+
+The original purpose of Ramaze was to act as a kind of framework to build
+web-frameworks, this was made obsolete by the introduction of rack, which
+provides this feature at a better level without trying to enforce any structural
+layout of the resulting framework.

data/doc/readme_chunks/principles.txt

@@ -0,0 +1,41 @@
+There are some basic principles that Ramaze tries to follow:
+
+* Test everything
+
+  What use is a wonderful application if it doesn't work?
+
+
+* Document everything
+
+  Documentation is the glue between the code and the programmers brain
+
+
+* Keep It Super Simple (KISS)
+
+  Most things should be understandable after reading them once
+
+
+* Principle Of Least Surprise (POLS)
+
+  Going the way of ruby
+
+
+* Modular design
+
+  Making it as simple as possible to extract parts
+
+
+* Minimal dependencies
+
+  In case a dependency is not met use a simple fall-back instead
+
+
+* Provide as many examples as possible
+
+  Examples are a superior way of getting a quick start into everything
+
+
+* Open development
+
+  I happily accept all patches or feature-requests that you may have,
+  as long as they comply with these principles

data/doc/readme_chunks/thanks.txt

@@ -0,0 +1,59 @@
+There is a large number of people who made Ramaze possibe by their ongoing
+efforts in the world of open source and by encouraging and helping me.
+
+This list is by no means a full listing of all these people, but I try to
+get a good coverage despite that.
+
+I would like to thank:
+
+* Yukihiro Matsumoto a.k.a matz
+
+    For giving the world Ruby and bringing fun back into programming.
+
+* Zed Shawn a.k.a. zedas
+
+    For developing Mongrel, Ramaze started out as a simple Hello World based
+    on that awesome server.
+
+* Christian Neukirchen a.k.a chris2
+
+    For building rack, which is just what the numerous web-developers had
+    anticipated and which will, with no doubt, change the world.
+
+* Pistos
+
+    For continious encouragment and building the first real webpage on Ramaze.
+    His bugreports were invaluable.
+
+* Jim Weirich
+
+    For Rake, which lifts off a lot of tasks from the shoulders of every
+    developer who uses it.
+
+* Thomas Sawyer a.k.a Trans
+
+    Dragging me deep into the rabbit-hole and showing me how awesome Ruby
+    truely is through his work on facets, ratchets and tons of other projects.
+
+* George Moschovitis a.k.a gmosx
+
+    For his tremendous efforts in the Nitro/Og framework, which is a source of
+    steady inspiration for Ramaze and brought me to Ruby in the first place.
+
+* Rob Levin a.k.a. lilo
+
+    He founded the most excellent Freenode IRC-network, where the most important
+    channels for rubyists are located (as is #ramaze).
+    May he rest in peace.
+
+* The guys (and gals) in the various channels on Freenode
+
+    As the people are way too many to be listed, here the channels that i call
+    my online home.
+    All the people in there deserve special thanks for getting me hooked to Ruby
+    and providing their help in a friendly and patient manner.
+
+    * #nitro
+    * #ruby-de
+    * #ruby-lang
+    * #rubyforce

data/doc/tutorial/todolist.txt

@@ -0,0 +1,546 @@
+= To-do List Tutorial
+
+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.
+
+The tutorial assumes that you have Ramaze installed already. The easiest way to
+do that is `gem install ramaze`, for other ways of installation please see the
+documentation at http://ramaze.rubyforge.org
+
+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 Bug tracker at http://rubyforge.org/projects/ramaze or just
+drop by on IRC ( irc.freenode.org channel: #ramaze ).
+
+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.
+
+Thanks in advance.
+The author of the tutorial, Michael 'manveru' Fellinger
+
+== First Step, Create
+
+We are using `ramaze --create todolist` to create a new application.
+Ramaze will then create the directory and fill it with a skeleton of a quite
+sophisticated hello-world example out of which we will create the actual
+to-do list.
+
+So run:
+
+  $ ramaze --create todolist
+
+done.
+
+
+== Second Step, M, like Model
+
+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.
+
+Instead of 'yaml/store' use:
+
+  require 'ramaze/store/default'
+
+And further:
+
+  TodoList = Store::Default.new 'todolist.yaml'
+
+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
+  end
+
+
+== Third Step, V, like View
+
+Now let's get our hands dirty and just edit the templates for our to-do list.
+
+Start with editing `template/index.xhtml`, it is using the default templating
+of Ramaze, called Ezamar.
+
+Let's put some things in there, I'll explain the syntax as we go, it's quite
+simple.
+
+  <html>
+    <head>
+      <title>TodoList</title>
+    </head>
+    <body>
+      <h1>TodoList</h1>
+      <ul>
+        <?r
+          TodoList.each do |title, parameters|
+            status = parameters[:done] ? 'done' : 'not done'
+          ?>
+          <li>#{title}: #{status}</li>
+        <?r end ?>
+      </ul>
+    </body>
+  </html>
+
+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
+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
+page.
+
+The whole Template would expand to something like this (only showing the
+interesting part)
+
+  <ul>
+    <li>Laundry: not done</li>
+    <li>Wash dishes: not done</li>
+  </ul>
+
+That wasn't too bad, huh?
+
+Now, so we can get our instant pleasure of seeing the result of our (hard) work,
+let's see how to start ramaze.
+
+In the `todolist` directory run `ramaze`.
+
+This will start an instance of Ramaze and run your application on it. You can
+now access it by browsing to http://localhost:7000/
+
+7000 is the default-port Ramaze will run on, to change it you can just run
+`ramaze -p 7070` or similar. Also be sure to look at the output of
+`ramaze --help` to see some other options.
+
+
+== Fourth Step, C, like Controller
+
+The last part of the MVC-paradigm is the Controller.
+
+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 limited.
+
+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
+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. Go on and
+edit the file `src/controller/main.rb`.
+
+The contents of it are like following:
+
+  class MainController < Controller
+    def index
+      "Hello, World"
+    end
+  end
+
+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
+`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[title] = status
+    end
+  end
+
+This will take care of the logic inside the template, which now should be
+changed to do following:
+
+  <html>
+    <head>
+      <title>TodoList</title>
+    </head>
+    <body>
+      <h1>TodoList</h1>
+      <a href="/new">New Task</a>
+      <?r if @tasks.empty? ?>
+        No Tasks
+      <?r else ?>
+        <ul>
+          <?r @tasks.each do |title, status| ?>
+            <li>#{title}: #{status}</li>
+          <?r end ?>
+        </ul>
+      <?r end ?>
+    </body>
+  </html>
+
+The rest of the template can stay the same.
+
+Now, if you browse to http://localhost:7000/ again you will not notice any
+change, which is how it should be. The only change is that if there are no
+Tasks it will say so.
+
+Some things you should know:
+
+* Instance-variables defined in the Controller are available in the View.
+* The return-value of the Controller does not matter (in this case).
+
+== Fifth Step, getting dynamic
+
+We set out to build the ultimate to-do list, but there are still some things
+missing. First off, we want to add new tasks, so let's get that done.
+
+Add a link on the `template/index.xhtml` like this:
+
+  <h1>TodoList</h1>
+  <a href="/new">New Task</a>
+
+Open a new file `template/new.xhtml` with a form to add a new task.
+
+  <html>
+    <head>
+      <title>TodoList</title>
+    </head>
+    <body>
+      <h1>New Task</h1>
+      <a href="/">Back to TodoList</a>
+      <form method="POST" action="create">
+        Task: <input type="text" name="title" /><br />
+        <inpyt type="submit" />
+      </form>
+    </body>
+  </html>
+
+We will not need a method for this on our controller, in fact, actions can
+consist of either method and template or only one of them. The Controller
+can act as a View and the View as Controller (if it returns a String and there
+is no template).
+
+If you try to use this form you will notice that we have not yet defined a way
+to actually create the task.
+
+You will get the default Ramaze error-page instead. Please take your time to
+explore it and see how Ramaze reacted on the error.
+
+It will show you the back trace and what state the application is in at the
+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
+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)
+  end
+
+That's all folks!
+
+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 ;)
+
+
+== Sixth Step, open and close tasks
+
+Since the nature of tasks is to be done eventually
+we will need some way to mark it as done or open tasks again.
+
+Jump into `template/index.xhtml` and do the following:
+
+
+  <?r @tasks.each do |title, status, toggle| ?>
+    <li>
+      #{title}: #{status} - #{toggle}
+    </li>
+  <?r end ?>
+
+We added a new element here, `toggle`, the Controller should give us
+a link to change the status corresponding to the status of the task, so off
+we go and change the index method on the controller once again:
+
+  def index
+    @tasks = []
+    TodoList.original.each do |title, parameters|
+      if parameters[:done]
+        status = 'done'
+        toggle = link( R( self, :open, CGI.escape(title) ), :title => 'Open Task' )
+      else
+        status = 'not done'
+        toggle = link( R( self, :close, CGI.escape(title) ), :title => 'Close Task' )
+      end
+      @tasks << [title, status, toggle]
+    end
+    @tasks.sort!
+  end
+
+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:
+
+  <a href="/open/Wash+dishes">Close Task</a>
+
+R 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,
+which is because we were using an Hash, which are per definition unsorted, so
+now we use an array to hold our tasks and sort it.
+
+Now back again to `template/index.xhtml` and change it as follows:
+
+  <?r @tasks.each do |title, status, toggle| ?>
+    <li>
+      #{title}: #{status} [ #{toggle} ]
+    </li>
+  <?r end ?>
+
+As usual, the things not changed are omitted for terseness.
+
+And as usual since the links for open and close don't lead anywhere, add the
+corresponding methods to the Controller:
+
+  def open title
+    task_status title, false
+    redirect R(self)
+  end
+
+  def close title
+    task_status title, true
+    redirect R(self)
+  end
+
+  private
+
+  def task_status title, status
+    task = TodoList[title]
+    task[:done] = status
+    TodoList[title] = task
+  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 and
+follow the DRY (Don't repeat yourself) paradigm.
+
+Another thing we have not encountered so far is that you can define your public
+methods to take parameters on their own, they will be calculated from requests.
+
+  '/open/Wash+dishes'
+
+will translate into:
+
+  open('Wash dishes')
+
+Which in turn will call task_status('Wash dishes', false)
+
+That's it, go on and try it :)
+
+== Seventh Step, delete tasks
+
+Well, creating, opening and closing work now, one of the things you will
+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' )
+  @tasks << [title, status, toggle, delete]
+
+and an corresponding method while we're at it:
+
+  def delete title
+    TodoList.delete title
+    redirect R(self)
+  end
+
+Now jumping to `template/index.xhtml` again, change it so it shows the link:
+
+  <?r @tasks.each do |title, status, toggle, delete| ?>
+    <li>
+      #{title}: #{status} [ #{toggle} | #{delete} ]
+    </li>
+  <?r end ?>
+
+Voilà, you now have acquired the Certificate of Ramazeness, our accounting-
+section will contact you within the next few days.
+
+Just kidding, but that really are the basics, in the next few steps I will
+explain some more advanced concepts of Ramaze and the templating.
+
+
+== Eight Step, Elements
+
+  <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
+between to that Element.
+
+Sounds weird?
+
+Let us have a look at our templates, they all got some repetitive stuff, like:
+
+  <html>
+    <head>
+      <title>TodoList</title>
+    </head>
+    <body>
+      <h1>some title</h1>
+    </body>
+  </html>
+
+How about replacing that with something short and nice:
+
+  <Page title="TodoList">
+    your other content
+  </Page>
+
+Would be nice of course, and when you start having more templates it makes an
+awful lot of sense to change the enclosing stuff in one place.
+
+So let's apply DRY here as well.
+
+Take a look at the `src/element/page.rb`
+
+  class Page < Element
+    def render
+      %{
+      <html>
+        <head>
+          <title>Welcome to Ramaze</title>
+        </head>
+        <body>
+          #{content}
+        </body>
+      </html>
+      }
+    end
+  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.
+
+Just adopt it to your liking, I'll just use the things we had in our templates
+so far:
+
+  class Page < Element
+    def render
+      %{
+      <html>
+        <head>
+          <title>TodoList</title>
+        </head>
+        <body>
+          <h1>#{@hash['title']}</h1>
+          #{content}
+        </body>
+      </html>
+      }
+    end
+  end
+
+Please note that the @hash is filled with the things you pass as parameters
+to tye Page-tag.
+
+And let's change our templates as well.
+
+First the `template/index.xhtml`
+
+  <Page title="TodoList">
+    <a href="/new">New Task</a>
+    <?r if @tasks.empty? ?>
+      No Tasks
+    <?r else ?>
+      <ul>
+        <?r @tasks.each do |title, status, toggle, delete| ?>
+          <li>
+            #{title}: #{status} [ #{toggle} | #{delete} ]
+          </li>
+        <?r end ?>
+      </ul>
+    <?r end ?>
+  </Page>
+
+and the `template/new.xhtml`
+
+  <Page title="New Task">
+    <a href="/">Back to TodoList</a>
+    <form method="POST" action="create">
+      Task: <input type="text" name="title" /><br />
+      <input type="submit" />
+    </form>
+  </Page>
+
+Alright, now just go and look at the result in the browser, try changing
+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.
+
+So, from what we have right now:
+
+  <ul>
+    <?r @tasks.each do |title, status, toggle, delete| ?>
+      <li>
+        #{title}: #{status} [ #{toggle} | #{delete} ]
+      </li>
+    <?r end ?>
+  </ul>
+
+To something like this:
+
+  <table>
+    <?r @tasks.each do |title, status, toggle, delete| ?>
+      <tr>
+        <td class="title">  #{title}  </td>
+        <td class="status"> #{status} </td>
+        <td class="toggle"> #{toggle} </td>
+        <td class="delete"> #{delete} </td>
+      </tr>
+    <?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:
+
+  <head>
+    <title>TodoList</title>
+    <style>
+      table     { width:       100%;              }
+      tr        { background:  #efe; width: 100%; }
+      tr:hover  { background:  #dfd;              }
+      td.title  { font-weight: bold; width: 60%;  }
+      td.status { margin:      1em;               }
+      a         { color:       #3a3;              }
+    </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.
+
+I will leave this as an exercise to the reader.
+
+To be continued...