ramaze 0.0.9 → 0.1.0

data/doc/meta/announcement.txt

@@ -0,0 +1,47 @@
+This is a one-time post to announce the creation of the Ramaze project, an open
+source web framework with the aim to be light and modular.
+Ramaze is already relatively stable and we decided that it is time to give it
+broader exposure to find new users and contributors.
+
+Home page: http://ramaze.rubyforge.org
+IRC: #ramaze on irc.freenode.net
+
+Features:
+  - Builds on top of the recently released Rack library, which provides easy use
+    of adapters like Mongrel, WEBrick, CGI or FCGI.
+
+  - Supports a wide range of templating-engines like:
+      Amrita2, Erubis, HAML, Liquid, Markaby and its own engine called Ezamar.
+
+  - Highly modular structure, you can just use the parts you like. This also
+      means that it's very simple to add your own customizations.
+
+  - A variety of helpers is already available, giving you things like advanced
+      caching, OpenID-authentication or aspect-oriented programming for your
+      controllers.
+
+  - 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.
+      There are a variety of examples and a tutorial available.
+
+  - Friendly community: lastly, but still quite important, there are people from
+      all over the world using Ramaze, so you can get almost instant help and
+      info.
+
+
+Features planned:
+  - Unified FormHelper for ORMs, making the framework mostly independent of the
+      underlying model.
+
+  - Improved configuration system, providing an way to totally change options
+      during runtime and link that with the CLI-parameter automatically.
+
+
+For more information please come to http://ramaze.rubyforge.org or ask directly
+on IRC (irc://irc.freenode.net/#ramaze)
+
+Thank you,
+Michael 'manveru' Fellinger and the Ramaze community

data/doc/meta/configuration.txt

@@ -0,0 +1,179 @@
+This chapter covers how to do configuration in Ramaze for your application.
+
+
+### Global
+
+The object holding most configuration is called Global. It resides in the Ramaze
+module/name space.
+
+Global is a subclass of OpenStruct and behaves mostly like it, so you can assign
+your own key/value pairs to do your own configuration. Just ensure you don't
+change key/value pairs by accident that Ramaze itself uses (doing it intentional
+is OK of course).
+
+Before covering some of the available options let us see how to actually use it.
+
+For the examples shown here we will assume that you did include Ramaze
+into your main into your main name space. If you don't do that, just prefix
+Global with Ramaze so it is written Ramaze::Global.
+
+
+#### Basic assignment:
+
+  Global.ports = (7000..7010)
+
+if you do that before calling Ramaze::start Ramaze will spawn one server on each
+port in that Range. The first value of this Range is also assigned to
+Global.port during the startup procedure.
+
+
+#### Multiple assignment:
+
+  Global.setup :adapter => :mongrel,
+               :cache   => MemcachedCache
+
+So you can pass a Hash of all the options you want to change.
+In this case you would use Mongrel as the adapter and use memcached for your
+sessions and general caching.
+
+
+#### Block assignment:
+
+  Global.setup do |g|
+    g.error_page = false
+    g.host = '127.0.0.1'
+    g.port = 7070
+  end
+
+This method is similar to the hash-assignment, but may be preferred for some
+applications.
+
+
+#### Pass on Ramaze.start
+
+  Ramaze.start :run_loose => true
+
+This way you can save a line or two in a small script.
+Please note that the values passed here have precedence over the ones directly
+set on Global and will overwrite them if you set them before, that is mostly
+useful to quickly test some configuration.
+
+
+### Global options
+
+Since this document is especially prone to be outdated at times make sure you
+check lib/ramaze/global.rb in case you run into trouble, we will try to keep at
+least the RDocs up to date. This update is from 2007/04/16.
+
+This listing is here to provide you with descriptions of the most common
+configurations in alphabetical order per section showing the default value next
+to the key.
+
+
+#### General Configuration:
+
+:autoreload => 5
+
+Autoreload is a nifty mechanism that takes advantage of the dynamics of Ruby,
+it's basically a Thread that runs in the background and polls for files in the
+application and framework that have changed (using mtime). The value specifies
+roughly how fast your changes are going to be loaded and should be a usual
+Fixnum.
+
+
+:adapter => :webrick
+
+The adapter is the server Ramaze runs to serve your application. This can be any
+of mongrel/webrick/fcgi/cgi, please note that so far neither fcgi nor cgi have
+received the necessary testing, but, as they are only wrappers around the
+underlying Rack library, should work fine. Both fcgi and mongrel require
+additional libraries to be installed, webrick and cgi run out of the box.
+Generally the most supported and recommended for deployment is Mongrel.
+
+
+:backtrace_size => 10
+
+This option doesn't have a large impact and is most likely left on its default
+value, it controls how long the backtrace shown in your log and on the error
+page should be.
+
+
+:cache => MemoryCache
+
+The cache is one of the more important things for deployment, the default for
+this is MemoryCache, a simple Hash.
+The class you specify here is used throughout Ramaze to cache various things,
+like sessions, page- and value-caching.
+Included in Ramaze are the MemoryCache and YAMLStoreCache, after you install
+'memcached' you can also use the much more performant MemcachedCache that also
+makes it easy to use the same cache between different applications (sharing
+sessions is one of the most obvious uses).
+
+
+:cache_all => false
+
+Setting this value to true would enable caching for all pages served from the
+Controller (all actions).
+This is a very powerful setting and you might want to enable it if all pages
+you serve are only built once and have no further dynamics, the key for this
+cache consists of the controller and parameters, when repeated requests are
+made it will always serve the same (now static) page.
+
+
+:cookies => true
+
+Enables sending cookies by setting this to false.
+Please note that many functionalities of Ramaze depend on an intact session and
+you will have to be careful not to use these.
+This is most likely useful in combination with `cache_all`
+
+
+:error_page => true
+
+Enables the default Error page of Ramaze which is mostly useful for manual
+testing and faster debugging. In most deployment-scenarios you will however
+want to use your own Error page and so you can safely disable this setting.
+
+:host => '0.0.0.0'
+
+Tell the adapter where it accepts requests from, 0.0.0.0 says that every
+IP will be accepted, 127.0.0.1 would accept only requests from loopback.
+
+
+:logger => Ramaze::Informer
+
+The logger is used during startup to set Ramaze::Inform, you may set this
+to Ramaze::Syslog or in case you have 'analogger' installed, you can use
+ Ramaze::Analogger.
+
+
+:mapping => {}
+
+This is a very central and special setting, it contains key/value pairs
+that define routes to your controllers, the keys are simple strings and
+start with '/', which means http://yourhost.com/ - '/foo/bar' would point
+to http://yourhost.com/foo/bar.
+The value is the class of your controller.
+
+
+:port => 7000
+
+The port Ramaze runs on, if you can think of more information about this feel
+free to tell us.
+
+
+:run_loose => false
+
+This option is mostly used to run the specs, it means that Ramaze will not
+join the adapter-threads and therefor you are free to run any code you want
+afterwards. You won't have to use this in most cases, example usage is in
+spec/spec_helper.
+
+
+:template_root => 'template'
+
+The template_root is the point your templates are located relative to the
+location of the entry-file (usually main.rb)
+It is also worth to mention that inside this directory the `mapping` is used
+to locate templates for each controller, only the controller mapped to '/' uses
+the templates directly from the `template_root`

data/doc/meta/internals.txt

@@ -0,0 +1,111 @@
+This document is a humble attempt to explain the internal workings of Ramaze and
+how the different parts fit into the big picture.
+
+It does not try to describe every little detail, as you will be better off
+reading the actual source instead. But you will at least get an idea of where to
+look.
+
+### Ramaze
+
+Ramaze is a web framework and therefor tries to make it simple to deploy your
+own applications on top of it.
+Let's outline the realms that Ramaze works in as to show what the current
+limitations and features are.
+
+
+#### The Ramaze module
+
+Ramaze is also the main module or so-called namespace that the framework lives
+in. It has 
+
+startup
+shutdown
+initial tasks
+exiting tasks
+
+
+#### Global configuration
+
+Any serious application or framework needs to be configured.
+Yes, I wished there was a silver bullet to serve all your needs as well, but at
+the current stage of programming development there is no such thing.
+So, since we need to configure, we should make it as simple and painless as
+possible, and, thanks to Ruby, it is actually quite enjoyable to do that.
+You can find a very detailed description about Global in the section about
+Configuration, for now just the basics.
+
+The basis of Ramaze::Global, the instance that is holding most part of your
+configuration or at least links to the actual places, is the
+Ramaze::GlobalStruct (ramaze/global.rb), which is a subclass of OpenStruct. If
+you are not yet familiar with OpenStruct, I very much recommend to read its
+documentation and play around a bit, it is basically just a wrapper around a
+normal Hash where you can access the keys instead of ostruct[:foo] with
+ostruct.foo.
+It simply defines a new accessors on assignment by catching things in
+method_missing. I won't go into more details here, I hope you got the principle.
+
+Now, based on this technique, GlobalStruct adds things like defaults and a
+couple of convenience methods like they are common in Ruby, giving you more
+power by tapping to the internal Hash of the GlobalStruct and adding
+update/setup methods so you can assign many key/value pairs at once.
+The RDocs will give you a very good overview of what is available and how one is
+supposed to work with it.
+
+Now back to the big picture.
+
+Ramaze accesses Global all over the place, there have been made several choices
+as to why using something like Global is considered beneficial against choosing
+for example global variables, which would be considered as a fatal choice by
+any respected Rubyist anyway.
+
+Now to something more subtle, which has to do with Global. I speak about traits,
+which is a very different concept in most of its implementations, but it is
+something that basically fits this name. It is configuration of single Objects
+and whole ancestries.
+You can give an object a trait, and most likely will use it along the lines of
+something like MyController.trait(:map => '/'), which would be picked up on
+startup and used to create Global.mapping - where we are at configuration again.
+Choosing this style of configuration complementary to a central place to put all
+your configuration was made very early in the development of Ramaze, and the
+basic code of how traits are implemented and used has proven very efficient both
+in understanding and using them.
+
+There is a basic distinction when to use Global and when to use traits and when
+to generate or assume one based on the other.
+
+If something affects your whole application and is either used directly in the
+Ramaze module or throughout the framework it is considered to be put into Global
+to gain benefits of better documentation and accessibility.
+
+On the other hand - if something is used in a configuring manner by a class that
+is instantiated often (like Controller is for example), or a module that cannot
+hold instance variables in a nice manner and is also not a constant - then it is
+configured using traits.
+
+
+Ramaze
+Global
+Adapter
+Dispatcher
+Controller
+Action
+
+Session
+Helper
+Tool
+
+
+#### The Web
+
+The so called web consists of a plethora of data, most of it is browsable
+through a web browser that just about every toaster has installed these days.
+The browser is the target of a web author, trying to utilize common standards
+like HTML and CSS which are means for data and layout to be combined, giving the
+browser a way to display the data.
+Ramaze works on the URI-scale web, meaning that addresses like
+http://someserver.com/blog/article/1 have a unique representation on your
+server.
+If we stay with this example, we see already everything Ramaze needs to see to
+serve a page based on your instructions.
+We assume that blog/article is a Controller named ArticleController in the blog
+application.

data/doc/readme_chunks/features.txt

@@ -7,16 +7,14 @@ Ramaze offers following features at the moment:
 
    Rack supports at the moment:
 
-    * Mongrel
+    * [Mongrel](http://mongrel.rubyforge.org/)
 
-      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
+    * [WEBrick](http://www.webrick.org/)
 
-      http://www.webrick.org/
       WEBrick is a Ruby library program to build HTTP servers.
 
     * CGI
@@ -26,37 +24,31 @@ Ramaze offers following features at the moment:
 
 
 * Templates
-  * Amrita2
+  * [Amrita2](http://amrita2.rubyforge.org/)
 
-    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
+  * [Erubis](http://rubyforge.org/projects/erubis)
 
-    http://rubyforge.org/projects/erubis
     Erubis is a fast, secure, and very extensible implementation of eRuby.
 
-  * Haml
+  * [Haml](http://haml.hamptoncatlin.com/)
 
-    http://haml.hamptoncatlin.com/
     Haml takes your gross, ugly templates and replaces them with veritable Haiku.
 
-  * Liquid
+  * [Liquid](http://home.leetsoft.com/liquid)
 
-    http://home.leetsoft.com/liquid
     Liquid's syntax and parse model are inspired by Django templates, as well
     as PHP's smarty.
 
-  * Markaby
+  * [Markaby](http://code.whytheluckystiff.net/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.
+    A simple homage to [Nitro](http://nitroproject.org)s templating.
 
 * Cache
   * Hash

data/doc/readme_chunks/installing.txt

@@ -7,12 +7,13 @@
   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
+    $ darcs get --partial http://manveru.mine.nu/ramaze
 
   Please read the man page or `darcs help` for more information about updating
   and creating your own patches.
@@ -39,3 +40,8 @@
 
     $ darcs send -o ramaze_bundle
     $ gzip -c ramaze_bundle > ramaze_bundle.gz
+
+
+* via install.rb
+
+  Support for install.rb has been canceled and the file removed.

data/doc/tutorial/todolist.txt

@@ -453,7 +453,7 @@ so far:
             <title>TodoList</title>
           </head>
           <body>
-            <h1>#{@hash['title']}</h1>
+            <h1>#{@title}</h1>
             #{content}
           </body>
         </html>
@@ -461,8 +461,7 @@ so far:
       end
     end
 
-Please note that the @hash is filled with the things you pass as parameters
-to tye Page-tag.
+Please note that instance variables reflecting the parameters are set.
 
 And let's change our templates as well.
 

data/examples/blog/main.rb

@@ -1,16 +1,17 @@
-#          Copyright (c) 2006 Michael Fellinger m.fellinger@gmail.com
-# All files in this distribution are subject to the terms of the Ruby license.
+$DBG = true # turn on debugging in Og
 
-require 'yaml'
-require 'bluecloth'
 require 'ramaze'
-
-require 'src/model'
+require 'og'
 
 include Ramaze
+
+require 'src/model'
+require 'src/view'
 require 'src/controller'
-require 'src/element'
 
-Global.setup
+Og.setup :evolve_schema => :full
+
+Entry.create "Blog created", "Exciting news today, this blog was created!" if
+  Entry.count == 0
 
 start