nitro 0.20.0 → 0.21.0

data/INSTALL

@@ -2,37 +2,37 @@
 
 1. Download and install RubyGems: 
 
-	http://rubygems.rubyforge.org
+  http://rubygems.rubyforge.org
 
 2. Install the distribution:
 
-	gem install nitro
-	
-	If you wish to install Og only:
+  gem install nitro
+  
+  If you wish to install Og only:
 
-	gem install og
+  gem install og
 
-	(make sure you have the latest stable versions of Ruby and RubyGems
-	installed)
+  (make sure you have the latest stable versions of Ruby and RubyGems
+  installed)
 
-	When asked about the dependencies to include, only accept
-	the dependencies for the RDBMS backends you are planning
-	to use.
+  When asked about the dependencies to include, only accept
+  the dependencies for the RDBMS backends you are planning
+  to use.
 
 3. Set environment variable (required to load RubyGems):
 
-	export RUBYOPT=-rubygems
+  export RUBYOPT=-rubygems
 
-	You can add this in you .bashrc in Unix.
+  You can add this in you .bashrc in Unix.
 
-	Alternatively you can run your applications with the -rubygem 
-	option:
+  Alternatively you can run your applications with the -rubygem 
+  option:
 
   ruby -rubygem xxx.rb
 
 4. To verify that everything works ok, run the command
 
-	nitro
+  nitro
 
 = Installation without RubyGems using script.
 
@@ -42,13 +42,13 @@ a standard installation script is provided.
 
 1. Switch to an administrator account 
 
-	For example in Unix:
+  For example in Unix:
 
-	$ su -
+  $ su -
 
 2. Run the installation script.
 
-	$ ruby install.rb
+  $ ruby install.rb
 
 This installation script also installs some vendor libraries
 that you possibly have allready installed. Use with caution.
@@ -82,37 +82,37 @@ list for your reference. Please not that most of these
 libraries are optional.
 
 * PostgreSQL 
-	http://www.postgres.org
-	Used for Database driven web applications.
-	
+  http://www.postgres.org
+  Used for Database driven web applications.
+  
 * MySQL 
-	http://www.mysql.org
-	Used for Database driven web applications.
+  http://www.mysql.org
+  Used for Database driven web applications.
 
 * Ruby-psql 
-	http://www.postgresql.jp/interfaces/ruby/archive/ruby-postgres-0.7.1.tar.gz
-	Ruby interface to the PostgreSQL RDBMS.
+  http://www.postgresql.jp/interfaces/ruby/archive/ruby-postgres-0.7.1.tar.gz
+  Ruby interface to the PostgreSQL RDBMS.
 
 * Ruby-mysql 
-	http://tmtm.org/ja/ruby/mysql/README_en.html
-	Ruby interface to the MySQL RDBMS.
-	
+  http://tmtm.org/ja/ruby/mysql/README_en.html
+  Ruby interface to the MySQL RDBMS.
+  
 * Ruby-XSLT 
-	http://gregoire.lejeune.free.fr/ruby-xslt_0.4.0.tar.gz
-	Used for XSLT based templates.
+  http://gregoire.lejeune.free.fr/ruby-xslt_0.4.0.tar.gz
+  Used for XSLT based templates.
 
 * Apache 2.0 
-	http://www.apache.org
-	Used to host application in production environments.	
+  http://www.apache.org
+  Used to host application in production environments.  
 
 * Lighttpd
-	http://www.lighttpd.net/
-	A lean and efficient web server. A perfect companion to Nitro.
+  http://www.lighttpd.net/
+  A lean and efficient web server. A perfect companion to Nitro.
 
 * Ruby-fcgi 
-	http://www.moonwolf.com/ruby/archive/ruby-fcgi-0.8.5.tar.gz
-	Used for FCGI based applications.
+  http://www.moonwolf.com/ruby/archive/ruby-fcgi-0.8.5.tar.gz
+  Used for FCGI based applications.
 
 * FastCGI development kit
-	http://www.fastcgi.com/dist/fcgi.tar.gz
-	Needed to compile the C-version of the ruby fcgi library.
+  http://www.fastcgi.com/dist/fcgi.tar.gz
+  Needed to compile the C-version of the ruby fcgi library.

data/README

@@ -1,14 +1,24 @@
-= Nitro 0.20.0 README
+= Nitro 0.21.0 README
 
-Nitro is an efficient, yet simple engine for developing professional Web 
-Applications using the Ruby language. Nitro aims to provide a robust 
-infrastructure for scalable web applications that can be distributed 
-over a server cluster. However, Nitro can also power simple web 
-applications for deployment on intranets or even personal computers.
-Nitro integrates the powerful Og Object-Relational mapping library.
+Nitro provides everything you need to develop professional Web
+applications using Ruby and Javascript. 
 
-Nitro is a multiparadigm application framework and will incorporate ideas
-from Rails, Wee, PHP, JSP and Microsoft.NET.
+Nitro redefines Rapid Application Development by providing a 
+clean, yet efficient API, a layer of domain specific languages 
+implemented on top of Ruby and the most powerful and elegant 
+object relational mapping solution available everywhere. 
+
+Nitro is Web 2.0 ready, featuring excellent support for AJAX, 
+XML, Syndication while staying standards compliant.
+
+Nitro gives choice to the developer: Multiple paradigms are 
+implemented, incorporating ideas from Rails, CherryPy, Catalyst, 
+Wee, PHP, JSP and Microsoft.NET and more. The developer is free
+to choose the pattern that better fits his application. This 
+kind of freedom makes Nitro applicable to a wide range of 
+applications, spanning from big, scalable web sites with thousands
+of concurrent users to simple solutions for deployment on intranet
+desktops.
 
 
 == Features
@@ -17,228 +27,256 @@ A short summary of the major features:
 
 * Multiparadigm web applications.
 
-	You can write applications in the ASP/JSP/PHP style, ie by writting
-	server pages that are automatically translated to Ruby code by
-	Nitro.
+  You can write applications in the ASP/JSP/PHP style, ie by 
+  writting server pages that are automatically translated to Ruby 
+  code by Nitro.
 
-	Alternatively, you can write MVC style applications (like Rails) by 
-  utilizing the powerfull Controller mechanism.
+  Or, you can write MVC style applications (like Rails) by 
+  utilizing the powerfull Object publishing/Controller mechanism.
+  
+  Alternatively, you can use stateful components and/or programmatic
+  rendering: Nitro is the premium container for Wee applications.
 
 * Advanced Code generation.
 
-	Nitro in essence writes the Web application for you. The system
-	provides a number of domain spefic language extensions (meta-languages)
-	to automate generate of common code (OR mapping, validation,
-	forms generation, syndication, markup and more).
+  Nitro in essence writes the Web application for you. The system
+  provides a number of domain spefic language extensions (meta-languages)
+  to automate the generation of common code (OR mapping, validation,
+  forms generation, syndication, markup and more).
 
 * Object-Relational Mapping 
 
-	Nitro integrates the Og (ObjectGraph) object-relational mapping 
-	library. Og	provides transparent serialization of object graphs to a RDBMS 
-	backend. Unlike other similar libraries Og maps standard Ruby
-	objects to SQL tables and not vice versa. Og provides a meta language
-	to describe the relations between objects, a flexible	and intuitive api 
-	for querieng the database, raw access to the SQL language if needed 
-	(for example to fine tune the automatically generated SQL tables, or 
-	for custom queries), provides automatic validation, suports deserialization 
-	to Ruby objects or tuples, automatically generates join tables for 
-	many_to_many relations and provides a collection of usefull Mixins to 
-	synthesize common Entities.
-	
-	Og is a combination of the best features of Active Record and the
-	former O-R mapping library included in Nitro (NDB). Adapters for
-	PostgreSQL, MySQL, SQLite3, Oracle and SQL Server are included.
+  Nitro integrates the Og (ObjectGraph) object-relational mapping 
+  library. Og manages the lifecycle of Ruby objects and  provides 
+  transparent serialization of object graphs to stores (typically
+  RDBM systems)/.
+  
+  Unlike other similar solutions Og maps standard Ruby objects 
+  to SQL tables and not vice versa. Og provides a domain specific 
+  language to describe the relations between objects, a flexible 
+  and intuitive api for querieng the database, raw access to the 
+  SQL language if needed (for example to fine tune the automatically 
+  generated SQL tables, or for custom queries), provides automatic 
+  validation, suports deserialization to Ruby objects or tuples, 
+  automatically generates join tables for many_to_many relations 
+  and provides a collection of usefull Mixins to synthesize 
+  common Entities.
+  
+  Adapters for PostgreSQL, MySQL, SQLite3, Memory, Filesystem,
+  Oracle and SQL Server are included.
 
 * XML server pages (.xhtml)
 
-	Nitro uses standard, fully xml compliant xhtml pages with logic
-	code, thus combining the	power of embededed Ruby (like erb, eruby) 
-	with the xml compliance	of Amrita. Even though it is a 'Callback' 
-	style templating system it is flexible enough to run as 'Pipeline' 
-	style system if the developer prefers this mode of operation.
-	
-	<?xml version="1.0"?>
-	
-	<!-- example page -->
-	<html>
-
-	<?r	
-		title = 'Example'
-		version = params['version']
-	?>
-	
-	<h1>#{title}</h1>
-	
-	<?r if version > 1 ?>
-		<b>Version:</b> #{version}
-	<?r	end ?>
-	
-	</html>
+  Nitro uses standard, fully xml compliant xhtml pages with logic
+  code, thus combining the  power of embededed Ruby (like erb, eruby) 
+  with the xml compliance  of Amrita. Even though it is a 'Callback' 
+  style templating system it is flexible enough to run as 'Pipeline' 
+  style system if the developer prefers this mode of operation.
+  
+  <?xml version="1.0"?>
+  
+  <!-- example page -->
+  <html>
+
+  <?r  
+    title = 'Example'
+    version = params['version']
+  ?>
+  
+  <h1>#{title}</h1>
+  
+  <?r if version > 1 ?>
+    <b>Version:</b> #{version}
+  <?r  end ?>
+  
+  </html>
 
 * Action / Fragment Synthesis
 
-	Nitro actions and templates can include other actions or templates
-	to allow for component-based development.
-
-	Here is an example of including an action from a template:
-
-	<render href="list" />
-
-	or
-
-	<inject href="list" />
-
-	or from an action:
-
-	list()
-
-	Nitro server pages can include fragments at 'Compile' time or at
-	'RunTime' time.
-	
-	<!-- compile time include (static include) -->
-	<?include href="myfile.inc" />
-	
-	<!-- run time include (dynamic include) -->
-	<include href="myfile.inc" />
-	
-* Shaders, XSLT templates
-
-	Nitro features a fully programmable source transformation pipeline.
-	A transformation stage in this pipeline is called a Shader. An example 
-	shader transforms an XHTML document with embeded ruby-code processing 
-	instructions to a Ruby method. Another shader might be an XSLT stage.
-
-	Nitro promotes the usage of XSLT for web templates. The functional
-	nature of XSL is ideal for the Web. Moreover, the engine efficiently
-	precompiles the xsl transformation along with other transformations
-	(for example localization) essentially providing a computationally
-	free transformation step.
-
+  Nitro actions and templates can include other actions or templates
+  to allow for component-based development.
+
+  Here is an example of including an action from a template:
+
+  <render href="list" />
+
+  or
+
+  <inject href="list" />
+
+  or from an action:
+
+  list()
+
+  Nitro server pages can include fragments at 'Compile' time or at
+  'RunTime' time.
+  
+  <!-- compile time include (static include) -->
+  <?include href="myfile.inc" />
+  
+  <!-- run time include (dynamic include) -->
+  <include href="myfile.inc" />
+  
+* Nitro provides full support for Aspect Oriented programming. 
+  You can use aspects to intercept and customize any component 
+  of the Nitro system.
+
+* Fully customizable Compile time and Render time pipeline.
+  Nitro features a fully programmable source transformation pipeline.
+  For example a pipeline component transforms a standard XHTML 
+  document with embeded ruby-code processing instructions to Ruby 
+  code. Another component could apply XSLT transformation at compile
+  time to avoid the performance hit. Using the advanced AOP features
+  or standard OOP practice you can customize the pipeline to your
+  needs.
+  
+  The same is true for the run time render pipeline. Nitro makes
+  it exteremely easy to add filters or customize the behaviour
+  of actions. Example filters are the autologin filter, 
+  a gzip filter etc.
+
+* Excellent support for AJAX and Javascript. Nitro integrates 
+  a set of powerful javascript libraries:
+  
+  Prototype
+  Script.aculo.us
+  Behaviour
+  
+  These libraries are transparently integrated in the rendering
+  pipeline.
+
+* Elements subsystem. This is Tag libraries on steroids. You can 
+  define xhtml tags that generate calls to associated Ruby classes
+  to handle rendering special fx, skins and more.
+  
 * Multiple Platforms
 
-	Runs on Linux, Windows and Mac OSX. It will probably run on other
-	Unix based system with minor modifications. 
+  Runs on Linux, Windows and Mac OSX. It will probably run on other
+  Unix based system with minor modifications. 
 
 * Multiple Adapters
 
-	Nitro supports multiple web server configurations. Out of the box
-	it supports WEBrick (pure ruby), Lighttpd (fastcgi), Apache (fastcgi).
-	More options will be available in the future.
-	
+  Nitro supports multiple web server configurations. Out of the box
+  it supports WEBrick (pure ruby), Lighttpd (fastcgi), Apache (fastcgi).
+  More options will be available in the future.
+  
 * Minimum configuration
 
-	Configuration files are kept to the absolute minimum. The target
-	is to have no configuration files at all.
+  Configuration files are kept to the absolute minimum. The target
+  is to have no configuration files at all.
 
 * Scaffolding
 
-	This enables the developer to get started as fast as possible.
+  This enables the developer to get started as fast as possible.
 
 * Distributed State
 
-	Nitro provides a powerfull distributed state mechanism that utilizes
-	the DRb library. A typicall use of this infrastructure is to provide
-	distributed sessions when running your application over a server 
-	cluster. Distributed sessions are fully transparent to the developer.
-
-	Support for Memcached will be available soon.
-	
-* Request Filters
-
-	The develpoper has full access to the request handling pipeline.
-	Request filters are a powerfull mechanism for customized processing
-	of special requests. Example filters are the autologin filter, 
-	a gzip filter etc.
+  Nitro provides a powerfull distributed state mechanism that utilizes
+  the DRb library. A typicall use of this infrastructure is to provide
+  distributed sessions when running your application over a server 
+  cluster. Distributed sessions are fully transparent to the developer.
 
-	Moreover, Nitro provides the fine-grained filtering method pioneered
-	by Rails where you can attach single methods, blocks, objects or
-	modules, before, after or arrounf actions.
+* Scalability.
 
+  Nitro promotes the 'share-nothing' architecture pioneered in sites
+  like Yahoo, LiveJournal, Slashdot, etc to facilate easy scaling
+  through hardware.
+  
 * Parts
 
-	Parts are organized modules of web services. A Web Framework that
-	integrates a large collection of parts (User management, Blog,
-	Fora, CMS, Personalization, ..) will be released by Navel.
-	
-	Other libraries of parts are expected from the Ruby community when
-	the Part API is finalized.
-	
-* Fine-grained Caching
-
-	Nitro provides a well designed and efficient caching mechanism. Caching
-	will be provided at the following levels:
-	
-	* Object Cache (deserialized objects) (coming soon)
-	* Fragment Caching (cache generated sub-parts of a page, or a page)
-	* Action Caching (full pages)
-	* Output Caching (the whole page is stored as html and served by
-    the front web server, thus completely bypassing Nitro)
-	* HTTP 1.1 Caching (downstream caching of whole pages)
+  Parts are organized modules of web services. A Web Framework that
+  integrates a large collection of parts (User management, Blog,
+  Fora, CMS, Personalization, ..) will be released by Navel.
+    
+* Web services
 
-	The engine calculates intra-page dependencies automatically. A variety
-	of invalidation strategies can be implemented.
+  Nitro automates the process of web service development. Just let
+  Nitro's advanced scaffolding algorithms to generate the boilerplate
+  code for you.
+  
+* Fine-grained Caching
 
-* Multi phase evaluation
+  Nitro provides a well designed and efficient caching mechanism. Caching
+  will be provided at the following levels:
+  
+  Object Cache (deserialized objects) (coming soon)
+  Fragment Caching (cache generated sub-parts of a page, or a page)
+  Action Caching (full pages)
+  Output Caching (the whole page is stored as html and served by
+  the front web server, thus completely bypassing Nitro)
+  HTTP 1.1 Caching (downstream caching of whole pages)
 
-	Experimental, facilitates efficient HTTP1.1 caching.
+  A variety of invalidation strategies can be implemented.
 
 * Programmatic xhtml rendering.
 
-	options = ['Male', 'Female']
-	o.select(:name => 'sex') { 
-		o.options(options, selected = 1) 
-	}
-
- 	or
-
-	options = { 'Male' => 'm', 'Female' => 'f' }
-	o.select(:name => 'sex') { 
-		o.options(options, selected = 1) 
-	}
+  labels = ['George', 'Stella', 'Renos']
+  html {
+    head {
+      title 'A simple test'
+    }
+    body {
+      10.times {
+        strong 'Hello World'
+        i 'Hello World222'
+      }
+      select(:id => 'names') {
+        options :labels => labels, :selected => 1
+      }
+    }
 
 * Automatic validation.
 
-	class User
-		prop_accessor :name, :password, String
-		validate_confirmation :password
-		validate_length :name, :range => 2..12
-	end
-
-	u = User.new(...)
-	unless u.valid?
-		p u.errors.on(:name)
-		p u.errors[:password]
-	end
-	
-* Routing 
-
-	This enables portable rewrites and 'nice' urls.
-	
+  class User
+    prop_accessor :name, :password, String
+    validate_confirmation :password
+    validate_length :name, :range => 2..12
+  end
+
+  u = User.new(...)
+  unless u.valid?
+    p u.errors.on(:name)
+    p u.errors[:password]
+  end
+  
+* Implicit nice urls. Nitro automatically generates nice urls
+  for your actions. However, if you want to customize the defaults,
+  a powerful routing mechanism is provided.
+  
 * Advanced debuging features
 
-	* When running in debug mode, all exceptions raised are logged
-	to a special debug panel in the current page. Find out the offending
-	file and line from the exception dump, fix the bug, refresh the page.
-	
-	* in-process console: inject an irb session to a running application
-	server. You can use the irb console to investigate all variables
-	and code in your running server process.
-
-	* integrates the 'breakpoint' library by Florian Gross. The Breakpoint 
-	library provides the convenience of being able to inspect and modify 
-	state, diagnose bugs all via IRB by simply setting breakpoints in
-	your applications by the call of a method.
-
-* UI Components
-
-	Nitro is distributed with a collection of usefull UI components
-	to make form based application development easier (for example
-	an efficient, database-aware Pager component).
-	
+  When running in debug mode, all exceptions raised are logged
+  to a special debug panel in the current page. Find out the offending
+  file and line from the exception dump, fix the bug, refresh the page.
+  
+  in-process console: inject an irb session to a running application
+  server. You can use the irb console to investigate all variables
+  and code in your running server process.
+
+  integrates the 'breakpoint' library by Florian Gross. The Breakpoint 
+  library provides the convenience of being able to inspect and modify 
+  state, diagnose bugs all via IRB by simply setting breakpoints in
+  your applications by the call of a method.
+
+* Helper mixins
+
+  Nitro is distributed with a collection of usefull mixins
+  to make form based application development easier (for example
+  an efficient, database-aware Pager component).
+  
 * Localization
 
-	Nitro supports efficient and fully transparent localization of 
-	web applications.
+  Nitro supports efficient and fully transparent localization of 
+  web applications.
+  
+* Mailer 
+
+  Nitro provides excellent support for handling emails in your
+  Web application.
+  
+* Wee integration.
+
+  Nitro is the premium container for Wee stateful components.
 
 
 == What's new
@@ -255,6 +293,7 @@ The latest version of Nitro can be found at
 
 * http://www.nitrohq.com
 
+
 == Documentation
 
 Documentation for Nitro can be found at
@@ -271,53 +310,53 @@ the test directory for examples of usage.
 Nitro requires the following applications or libraries:
 
 * Ruby 1.8.1 and greater 
-	http://www.ruby-lang.org
-	Version 1.8.2 is recomended
+  http://www.ruby-lang.org
+  Version 1.8.2 is recomended
 
 * Facets
-	http://rubyforge.org/frs/?group_id=483
-	
+  http://rubyforge.org/frs/?group_id=483
+  
 The following applications or libraries are OPTIONAL:
 
 * PostgreSQL 
-	http://www.postgres.org
-	Used for Database driven web applications.
-	
+  http://www.postgres.org
+  Used for Database driven web applications.
+  
 * MySQL 
-	http://www.mysql.org
-	Used for Database driven web applications.
+  http://www.mysql.org
+  Used for Database driven web applications.
 
 * Ruby-psql 
-	http://www.postgresql.jp/interfaces/ruby/archive/ruby-postgres-0.7.1.tar.gz
-	Ruby interface to the PostgreSQL RDBMS.
+  http://www.postgresql.jp/interfaces/ruby/archive/ruby-postgres-0.7.1.tar.gz
+  Ruby interface to the PostgreSQL RDBMS.
 
 * Ruby-mysql 
-	http://tmtm.org/ja/ruby/mysql/README_en.html
-	Ruby interface to the MySQL RDBMS.
-	
+  http://tmtm.org/ja/ruby/mysql/README_en.html
+  Ruby interface to the MySQL RDBMS.
+  
 * Ruby-XSLT 
-	http://gregoire.lejeune.free.fr/ruby-xslt_0.4.0.tar.gz
-	Used for XSLT based templates.
+  http://gregoire.lejeune.free.fr/ruby-xslt_0.4.0.tar.gz
+  Used for XSLT based templates.
 
 * Apache 2.0 
-	http://www.apache.org
-	Used to host application in production environments.	
+  http://www.apache.org
+  Used to host application in production environments.  
 
 * Lighttpd
-	http://www.lighttpd.net/
-	A lean and efficient web server. A perfect companion to Nitro.
+  http://www.lighttpd.net/
+  A lean and efficient web server. A perfect companion to Nitro.
 
 * Ruby-fcgi 
-	http://www.moonwolf.com/ruby/archive/ruby-fcgi-0.8.5.tar.gz
-	Used for FCGI based applications.
+  http://www.moonwolf.com/ruby/archive/ruby-fcgi-0.8.5.tar.gz
+  Used for FCGI based applications.
 
 * FastCGI development kit
-	http://www.fastcgi.com/dist/fcgi.tar.gz
-	Needed to compile the C-version of the ruby fcgi library.
+  http://www.fastcgi.com/dist/fcgi.tar.gz
+  Needed to compile the C-version of the ruby fcgi library.
 
 * RedCloth
-	http://rubyforge.org/projects/redcloth/
-	
+  http://rubyforge.org/projects/redcloth/
+  
 Please install the required applications and libraries before continuing
 with the installation of Nitro.
 
@@ -384,9 +423,9 @@ if you wan to run this application with MySQL
 edit the configuration file to include
 
 {
-	...
-	:backend => "mysql"
-	...
+  ...
+  :backend => "mysql"
+  ...
 }
 
 instead.
@@ -418,20 +457,20 @@ browser when running in debug mode.
 == Description of contents
 
 bin
-	Commands and wizards.
+  Commands and wizards.
 
 examples/
-	Various examples. 'tiny' is a minimal example, 'blog' is a 
-	fully working and nice looking Blog implementation, 'no_xsl_blog'
-	is the same example without using XSLT, 'og' contains some Og 
-	examples and 'flash' is an example for generating binary content 
-	for a Nitro response.
+  Various examples. 'tiny' is a minimal example, 'blog' is a 
+  fully working and nice looking Blog implementation, 'no_xsl_blog'
+  is the same example without using XSLT, 'og' contains some Og 
+  examples and 'flash' is an example for generating binary content 
+  for a Nitro response.
 
 lib/nitro
-	Nitro library source files.
+  Nitro library source files.
 
 test
-	Unit and functional tests.
+  Unit and functional tests.
 
 
 == Running Tests