ramaze 0.1.2 → 0.1.3

data/doc/meta/announcement.txt

@@ -1,45 +1,41 @@
-This time we are proud to announce Version 0.1.2 of the Ramaze framework, an
-open source web framework with the aim to be light and modular.
+This time we are proud to announce Version 0.1.3 of the Ramaze framework, a
+light and modular open source web framework.
 
-Since the 0.1.0 release we have made a lot of progress and the overall API has
-mostly settled down. An extensive set of tests is covering almost every detail
-of the implementation and usage.
+Since the last release some polishing and improvments have been made, it seems
+like Ramaze is now mostly feature-complete.
 
-It is developed by by several people and already in production-use at some
-companies.
+An extensive set of specs is covering almost every detail of the implementation
+and usage. It is developed by several people and already in production-use at
+some companies.
 
 
 Home page: http://ramaze.rubyforge.org
 IRC: #ramaze on irc.freenode.net
 
 
-New Features in Version 0.1.2:
+Short summary of changes from 0.1.2 to 0.1.3:
 
- - Restructuring of Ramaze internals, featuring a cleaner overall layout.
+  - Better error handling
 
- - Add Ramaze::Record to easily record requests fitting particular patterns.
+  - Many bugs fixed
 
- - Support for the Remarkably templating engine.
+  - Some speedup
 
- - Adapted for Rack 0.2
+  - Lots of docs added
 
- - Easier caching.
+  - Smoother sourcereload
 
- - replacing autoreload with a general SourceReload class.
+  - New Wiki example
 
- - tiny DSL for settings.
+  - jQuery 1.1.3.1
 
- - Reviewed and largely improved tutorial and tested examples.
 
- - Even less patches to the Ruby core, mostly for compatibility with the
-   upcoming Ruby 1.9 and tested with older versions down to 1.8.2.
+A complete Changelog is available at http://manveru.mine.nu/ramaze/doc/CHANGELOG
 
- - Largely improved Spec-framework for any kind of web-application.
 
- - Through some benchmarking and refactoring the overall speed has improved
-   around the factor 2-3.
+Known issues:
 
-A complete Changelog is available at http://manveru.mine.nu/ramaze/doc/CHANGELOG
+  - Haml: either use Haml version 1.5.2 or require ActionPack.
 
 
 Features:
@@ -47,7 +43,7 @@ Features:
     of adapters like Mongrel, WEBrick, CGI or FCGI.
 
   - Supports a wide range of templating-engines like:
-      Amrita2, Erubis, HAML, Liquid, Markaby, Remarkably and its own engine
+      Amrita2, Erubis, Haml, Liquid, Markaby, Remarkably and its own engine
       called Ezamar.
 
   - Highly modular structure, you can just use the parts you like. This also
@@ -60,8 +56,9 @@ Features:
   - It is possible to use the ORM you like, be it ActiveRecord, Og, Kansas or
       something more simplistic like a wrapper around YAML::Store.
 
-  - Good documentation: although we don't have 100% documentation right now,
-      just about every part of Ramaze is covered with basic and advanced docs.
+  - Good documentation: although we don't have 100% (dcov says around 75%)
+      documentation right now, just about every part of Ramaze is covered with
+      basic and advanced docs.
       There are a variety of examples and a tutorial available.
 
   - Friendly community: lastly, but still quite important, there are people from

data/doc/meta/internals.txt

@@ -13,6 +13,119 @@ Let's outline the realms that Ramaze works in as to show what the current
 limitations and features are.
 
 
+#### Life of a request/response cycle
+
+This is a small summary of how a request creates a response in the
+examples/hello.rb and webrick (to keep it simple and short).
+All files referenced here are in lib/ramaze/ unless indicated otherwise.
+We don't explain the startup/shutdown process, only what happens from request to
+the eventual response.
+
+Browser sends request, webrick receives it and hands the ENV over to our rack
+handler (adapter/webrick.rb and adapter/base.rb).
+There it gets converted into a Ramaze::Request (trinity/request.rb) and
+a new blank Ramaze::Response (trinity/response.rb) is created.
+These two objects are then sent to Dispatcher::handle (dispatcher.rb).
+
+This all happens inside a new Thread, which is what Ramaze takes advantage of by
+assigning Thread-variables. You can see this now in
+Dispatcher::setup_environment which sets :request/:session/:response in
+Thread.current.
+
+After that, Dispatcher::dispatch is called with the path from request.path_info
+which in turn takes every class/module set in Dispatcher::FILTER and calls
+::process with the path.
+
+
+##### First, `/favicon.ico` (for most browsers)
+
+The first in FILTER is Dispatcher::File (dispatcher/file.rb) which searches
+Global.public_root and afterwards Global.public_proto for a matching file on
+this path. In our example the file found is a favicon.ico from
+Global.public_proto.
+
+The contents of FILTER have to return a Ramaze::Response, either the (possibly
+modified) original (Dispatcher::build_response helps with that) or a totally new
+one.
+
+In our case, Dispatcher::File uses build_response with an opened filehandler as
+body, '200 OK' as status and the Content-Type set to what Tool::MIME.type_for
+tells it is the correct mimetype for this file.
+
+
+##### Second, `/hello`
+
+We start in the processing of FILTER, since the previous steps are the same for
+every request.
+
+Here we now get only a nil value back from Dispatcher::File since no file in our
+two public directories exists for the given path.
+
+So, this time, Dispatcher::Action is called via ::process and the first thing
+this dispatcher does is trying to set the body of the request to the answer of
+Controller.handle (controller.rb) for the given path.
+
+Controller::handle doesn't do much either, but calls Controller::resolve
+(controller/resolve.rb) for the path.
+
+Here we get now into the guts of Ramaze, despite our efforts it's no easy
+reading since the underlying theory is a bit complex and many edge-cases have to
+be solved.
+
+Let me try to quickly sketch what happens here, maybe we can add a chapter about
+this aspect of Ramaze later.
+
+First we generate a pattern of how the requested path could fit into our
+controller and template structure. `/hello` only has 3 possible outcomes:
+
+Controller on '/', template or method `hello`
+Controller on '/', method `index` with parameter `hello`
+Controller on '/hello', method or template `index`
+
+After matching (in the order we wrote here) these possibilities against your
+application we get only one possibility, MainController on '/' with method
+`index`.
+
+The result is stored into an instance of Action and cached for repeated lookups,
+then passed back into Dispatcher::handle which subsequently calls Action#render
+(action/render.rb) on it.
+
+From here, Thread.current[:action] gets set and #uncached_render is called. This
+calls #before_process which only has effects if you have the AspectHelper
+activated and next on comes engine.transform with self as parameter.
+#engine is a method that figures out which engine this Action has to be rendered
+with, according to things like trait[:engine] in your controller and the
+extension of a template. In this case we have neither and the default engine
+Template::Ezamar (template/ezamar.rb) is used.
+
+So off we go, to Template::Ezamar::transform with the current instance of Action
+as parameter.
+
+::transform first calls ::wrap_compile which is inherited from Template
+(template.rb) and manages caching of compiled templates, calling ::compile with
+the action and template.
+
+The template again is retrieved through two attempts, firstly, we always call
+the method (if specified from Controller::resolve) on the controller, we
+temporarily store its result and replace it if a path for a template is set with
+the contents of the file on this path. The result of this is the final template
+that is ready for compilation.
+
+In the case of Ezamar, we first walk the TRANSFORM_PIPELINE (only
+Ezamar::Element (template/ezamar/element.rb) with ::transform and pass each the
+template for manipulation. In the example we don't have any elements, so we get
+back what we gave and generate a new instance of Ezamar::Template
+(template/ezamar/engine.rb) with the template and a path that indicates eval
+where we currently are supposed to be (templates path or the transformer).
+
+This instance is passed back to Ezamar::transform and we call #result with the
+actions binding (retrieved from earlier instantiation of the controller and
+subsequently eval `binding` inside of it).
+
+Now it's all done, we have got our body for the response which will be sent back
+to our handler as body.
+
+
 #### The Ramaze module
 
 Ramaze is also the main module or so-called namespace that the framework lives
@@ -26,31 +139,55 @@ Tasks on require
   * GlobalStruct.new
 
 
-Tasks on startup
+Tasks on startup as defined in Ramaze.trait[:internals] in lib/ramaze.rb
 
-* Global.startup
+* Global::startup
   * passed options to Ramaze.start
   * CLI options from bin/ramaze (treat as passed.merge)
   * Global options set before startup (fake Global?)
 
-* Controller.startup
+* Cache::startup
+  * adds the following caches via Cache.add:
+    * compiled
+      If Global.compile is set true this cache is used to store the compiled
+      templates.
+
+    * actions
+      Caching compiled actions.
+      
+    * patterns
+      This is used in Controller::resolve to cache the generated patterns for a
+      path.
+
+    * resolved
+      Caching the resolved but not yet compiled actions by their path.
+
+    * shield
+      Caching the generated errors for the path, so on repeated erronous
+      requests no new error-page has to be generated.
+
+* Controller::startup
   * mapping of all subclassed Controller
   * validation of mapping
   * validation of template_root
 
-* Adapter.startup
-  * interpret Global.adapter
-  * add every created adapter to Global.adapters
+* Session::startup
+  * adds Cache.sessions if Global.sessions is true
+    This cache is used to store all sessions with their session-id as key.
 
-* SourceReload.startup
+* SourceReload::startup
   * start with Global.reload_interval
   * assign Global.sourcereload
 
+* Adapter::startup
+  * interpret Global.adapter
+  * add every created adapter to Global.adapters
+
 
 Tasks on shutdown
 
-* Adapter.shutdown (iterates Global.adapters)
-* Inform.shutdown (iterates all in LogHub)
+* Adapter::shutdown (iterates Global.adapters)
+* Inform::shutdown (iterates all in LogHub)
 
 
 

data/examples/blog/template/index.xhtml

@@ -1,12 +1,15 @@
 <Blog title="bl_Og">
-  <div id="actions">#{link self, :new, :title => 'new entry'}</div>
+  <div id="actions">#{A 'new entry', :href => Rs(:new)}</div>
   <div id="entries">
     <?r @entries.each do |entry| ?>
     <div class="entry">
       <div class="header">
         <div class="title">#{entry.title}</div>
         <div class="created">Created: #{entry.created}</div>
-        <ul><li>#{link self, :edit, entry.oid, :title => 'edit'}</li><li>#{link self, :delete, entry.oid, :title => 'delete'}</li></ul>
+        <ul>
+					<li>#{A 'edit', :href => Rs(:edit, entry.oid)}</li>
+					<li>#{A 'delete', :href => Rs(:delete, entry.oid)}</li>
+				</ul>
       </div>
       <div class="content">#{entry.content}</div>
       <div class="updated">Last updated: #{entry.updated}</div>

data/examples/fcgi.rb

@@ -0,0 +1,13 @@
+#!/usr/bin/ruby
+require "rubygems"
+require "rack"
+require "ramaze"
+
+class MainController < Ramaze::Controller
+  def index
+    "Hello, World!"
+  end
+end
+
+Ramaze::Global.adapter = :fcgi
+Ramaze.start

data/examples/wiktacular/main.rb

@@ -0,0 +1,8 @@
+require 'ramaze'
+require 'bluecloth'
+
+require 'src/page'
+require 'src/model'
+require 'src/controller'
+
+Ramaze.start :adapter => :mongrel

data/examples/wiktacular/mkd/link/2007-07-20_19-45-51.mkd

@@ -0,0 +1 @@
+Links are basically files, far down under

data/examples/wiktacular/mkd/link/current.mkd

@@ -0,0 +1 @@
+Links are basically [[markdown]] files, far down under

data/examples/wiktacular/mkd/main/2007-07-20_16-31-33.mkd

@@ -0,0 +1 @@
+# Hello, World

data/examples/wiktacular/mkd/main/2007-07-20_19-21-12.mkd

@@ -0,0 +1 @@
+# Hello, World

data/examples/wiktacular/mkd/main/2007-07-20_19-23-10.mkd

@@ -0,0 +1,2 @@
+# Hello, World
+## This is the first test of this most awesome wiki

data/examples/wiktacular/mkd/main/2007-07-20_19-45-07.mkd

@@ -0,0 +1,2 @@
+# Hello, World
+## This is the first test of this most awesome [[rawiki]]

data/examples/wiktacular/mkd/main/current.mkd

@@ -0,0 +1,2 @@
+# Hello, World
+This is the first test of this most awesome [[wiktaculous]]

data/examples/wiktacular/mkd/markdown/current.mkd

@@ -0,0 +1,3 @@
+# Markdown
+
+Markdown is a engine for converting plain text to [[HTML]]. You can find more information at [markdown homepage](http://daringfireball.net/projects/markdown/)

data/examples/wiktacular/mkd/testing/2007-07-20_16-43-46.mkd

@@ -0,0 +1,2 @@
+# Just a test
+## nothing serious

data/examples/wiktacular/mkd/testing/2007-07-20_19-43-50.mkd

@@ -0,0 +1,3 @@
+# Just a test
+## nothing serious
+### Even less serious

data/examples/wiktacular/mkd/testing/2007-07-21_18-46-01.mkd

@@ -0,0 +1,11 @@
+# Just a test
+
+Some more text
+
+## nothing serious
+
+And some text
+
+### Even less serious
+
+Here is a [[link]]

data/examples/wiktacular/mkd/testing/2007-07-21_18-46-32.mkd

@@ -0,0 +1,13 @@
+# Just a test
+
+Some more text
+
+## nothing serious
+
+And some text
+
+### Even less serious
+
+Here is a [[link]]
+
+  <a href="foo">foo</a>

data/examples/wiktacular/mkd/testing/2007-07-21_18-47-08.mkd

@@ -0,0 +1,17 @@
+# Just a test
+
+Some more text
+
+## nothing serious
+
+And some text
+
+### Even less serious
+
+Here is a [[link]]
+
+  <html>
+    <head>
+      <a href="foo">foo</a>
+    </head>
+  </html>

data/examples/wiktacular/mkd/testing/2007-07-21_18-47-54.mkd

@@ -0,0 +1,17 @@
+# Just a test
+
+Some more text
+
+## nothing serious
+
+And some text
+
+### Even less serious
+
+Here is a [[link]]
+
+    <html>
+      <head>
+        <a href="foo">foo</a>
+      </head>
+    </html>

data/examples/wiktacular/mkd/testing/current.mkd

@@ -0,0 +1,17 @@
+# Just a test
+
+Some more text
+
+## nothing serious
+
+And some text
+
+### Even less serious
+
+Here is a [[link]]
+
+    <html>
+      <head>
+        <a href="foo">foo</a>
+      </head>
+    </html>

data/examples/wiktacular/public/screen.css

@@ -0,0 +1,72 @@
+body {
+  background: #dff;
+}
+
+a {
+  text-decoration: none;
+  color: #224;
+}
+a:hover {
+  text-decoration: underline overline;
+  color: #335;
+}
+
+a:before { content:"[ "; }
+a:after { content:" ]"; }
+
+h1 { font-size: 1.5em; }
+h2 { font-size: 1.4em; }
+h3 { font-size: 1.3em; }
+h4 { font-size: 1.2em; }
+h5 { font-size: 1.1em; }
+
+div#manipulate {
+  text-align: right;
+}
+
+div#navigation {
+  background: #fff;
+  padding: 0.5em;
+}
+
+div#text {
+  border: 1px black dashed;
+  padding: 1em;
+  margin: 1em;
+}
+
+div#menu {
+  height: 2em;
+  font-size: 1.1em;
+}
+
+form {
+  background: #cee;
+  padding: 2em;
+}
+
+input {
+  border: 1px solid #699;
+  background: #eee;
+}
+
+input:focus {
+  border: 1px solid green;
+}
+
+textarea {
+  width: 100%;
+  height: 35em;
+  border: 1px solid #699;
+  background: #eee;
+  padding: 5px;
+}
+
+textarea:focus {
+  border: 1px solid green;
+}
+
+#copyright {
+  text-align: center;
+  font-size: 0.9em;
+}