= Capcode

Copyright (C) 2009, 2010 Gregoire Lejeune

* home : http://capcode.rubyforge.org
* doc : http://rdoc.info/projects/glejeune/Capcode
* book (fr) : http://www.algorithmique.net/capcode/
  
== DESCRIPTION: 

Capcode is a web microframework

== FEATURES/PROBLEMS:

=== 0.9.6
* More debug trace
* Bug correction in the custom version of Rack::URLmap

=== 0.9.5
* Major bug correction

=== 0.9.4
* You can now create a controler without specifying the root name. If so the name of the class will be used. {see example route.rb}[http://github.com/glejeune/Capcode/tree/master/examples/route.rb].
* Major bug correction in Route
* render :text => ... now really render text 
* rXXX methods in HTTPError can now receive a second optional parameter corresponding to headers
* Huge bug correction in Capcode::Helpers.URL
* Use a custom version of Rack::URLmap

=== 0.9.3
* Major bug correction

=== 0.9.2
* Remove JSON dependency
* Add the "HTTP code" renderer, so you can now use something like this : render 200 => "OK", :server => "Capcode", ...
* Reintroduce before_filter. {See example filter.rb}[http://github.com/glejeune/Capcode/tree/master/examples/filter.rb].
* Remove mime-types dependency

=== 0.9.1
* You don't need to require the renderers. This will be done by Capcode at use time.
* Major bug correction for jRuby

=== 0.9.0

* <b>IMPORTANT</b>
  * THIS VERSION IS A MAJOR ENHANCEMENT : YOU MUST UNINSTALL ALL PREVIOUS VERSIONS !!!
		gem uninstall Capode --version '< 0.9.0'
  * Renderers and database accessors have been extracted and are now in the {plugins repository}[http://github.com/glejeune/Capcode.more]. Each plugin is a gem that's can be installed separately.
* <b>Important, but less!</b>
  * Add {Coffee-Script}[http://jashkenas.github.com/coffee-script/] renderer 
  * Update renderers options
  * Rewrite configuration
  * Bug corrections in all DB modules

=== 0.8.9
* Add Thin support
* Add MongoDB support
* Major bug correction in Markaby renderer

=== 0.8.8
* Add mustache renderer
* Add AcriveRecord support (see example blog-ar.rb)
* Add Sequel support (see example blog-sq.rb)
* Add Binary renderer (see example render-binary.rb)
* Add Mail renderer (see example render-mail.rb)
* Add Redirect renderer (see examples render-redirect.rb and render-mail.rb)
* Add "none" renderer (return a 204 status code)

=== 0.8.7
* Route's captures are now passed to all methods in a controller
* Add :content_type option to renderers (see render-image.rb)
* Add Capcode.set for configuration. So Capcode::Herpers#erb_path=, Capcode::Herpers#sass_path= and Capcode::Herpers#haml_path= are deprecated, you must now use `set :erb, ...', `set :sass, ...' and `set :haml, ...' (see render-erb.rb and render-haml_sass.rb)
* Add Capcode.use to allow usage of Rack middlewares (see render-use.rb)

=== 0.8.6
* HUGE bug correction

=== 0.8.5
* Capcode now work with Phusion Passenger \o/
* Add WebDAV renderer (need rack_dav) (see examples render-webdav.rb and auth-webdav.rb)
* Change default listen host from localhost to 0.0.0.0
* Add require_auth helper for basic or digest HTTP Authentication (see examples auth-basic.rb and auth-digest.rb)

=== 0.8.4
* Major (really MAJOR) bugs corrections in renderers
* Add many renderer' examples
* The static rendere now accept a new option : :exact_path. If :exact_path is set to true, the static rendere redirect you to the exact static url of the file. Else it just give the content of the file. Default is true. (see example render-static.rb) 
* redirect now accept an optional HTTP status code as first parameter

=== 0.8.3
* Add PUT and DELETE actions (see rest example)

=== 0.8.2
* Add XML renderer (see rss example)
* Major bug corrections
* Add Helpers.static
* New example : upload.rb
* The database' configuration file is no more relative to the root directory but to the main file

=== 0.8.1
* Sorry for 0.8.0 !!

=== 0.8.0
* Bugs corrections in haml and text renderer
* Text renderer is now automaticaly included
* Add sass renderer
* :working_directory is no more available
* :root is now the real root directory
* Add :static option to set the directory for static files
* Add -r and -s (for root and static directories) options
* Add static renderer

=== 0.7.1
* You need to include Capcode::Resource in your models !!!!
* Add option --version

=== 0.7.0
* You no more need to include Capcode::Resource in your models
* Capcode.run now accept a block. The content of the block is executed just before the server start.
* Add options support : you can now change the defaults port and host, daemonize or not and run in console mode.

=== 0.6.2
* Add Markaby, Erb and Haml layout see Capcode::Helpers.render for more informations
* Add content_for...
* Major bugs corrections

=== 0.6.1
* Major bugs corrections in haml and erb renderer ($%&! Windows)
* Major bugs corrections in Route.call
* Add Markaby layout support
* Rewrite blog-couchdb example (based on the very sympatic camping example : http://github.com/judofyr/camping/blob/master/examples/blog.rb)

=== 0.6.0
* Add :root option to Capcode.run. This option allow you to specify the root directory for static files
* Add :working_directory option to Capcode.run. This option allow you to specify the working directory
* If '/' route is not defined but /index.html exist, display index
* add mime-types dependency
* Bug correction in erb and haml renderer

=== 0.5.0
* Add Haml and Markaby renderer
* json is deprecated and replaced by render( :json => ... )

=== 0.4.0
* Major bug correction !
* Add views...

=== 0.3.0
* Work with Rack 1.0.0

=== 0.2.0
* Add models with DataMapper and couch_foo
* Add two new options : :daemonize and :pid
* Bug correction in Route.

=== 0.1.0
* First public release
* No models !!!

== SYNOPSIS:

  # file: sample.rb
  require 'rubygems'
  require 'capcode'

  module Capcode
    class Hello < Route '/hello'
      def get
        "Hello World #{Time.now} !"
      end
    end
  end
  
  Capcode.run( )

=== Running Capcode Apps

* Run: <tt>ruby sample.rb</tt>
* Visit http://localhost:3000/

=== Create model

  require 'rubygems'
  require 'capcode'
  require 'capcode/base/dm' # or require 'capcode/base/couchdb'

  class Story < Capcode::Base
    include Capcode::Resource

    property :id, Integer, :serial => true # only with DataMapper !
    property :title, String
    property :body, String
    property :date, String
  end

See <tt>examples/blog-dm.rb</tt> and/or <tt>examples/blog-couchdb.rb</tt> for complete examples.

=== Create View

  # file: sample.rb
  require 'rubygems'
  require 'capcode'
  
  module Capcode
    class Hello < Route '/hello'
      def get
        @t = Time.now
        render :time
      end
    end
  end
  
  module Capcode::Views
    def time
      "Hello world #{@t}"
    end
  end
  
  Capcode.run( )

=== Create Helper

  # file: sample.rb
  require 'rubygems'
  require 'capcode'
  
  module Capcode
    class Hello < Route '/hello'
      def get
        @t = Time.now
        render :time
      end
    end
  end
  
  module Capcode::Helpers
    def bold( &b )
      "<b>"+yield+"</b>"
    end
  end
  
  module Capcode::Views
    def time
      "Hello world " + bold { @t }
    end
  end
  
  Capcode.run( )
  
=== Render with Markaby

  # file: sample.rb
  require 'rubygems'
  require 'capcode'
  
  module Capcode
    class Hello < Route '/hello'
      def get
        @t = Time.now
        
        # This implies that capcode-render-markaby is installed !
        render :markaby => :time
      end
    end
  end
  
  module Capcode::Views
    def time
      # We use Markaby in Capcode::Views.time
      html do
        body do
          p {
            text "Hello World "
            b @t
          }
        end
      end
    end
  end

  Capcode.run( )

=== Render with Haml

  # file: sample.rb
  require 'rubygems'
  require 'capcode'

  module Capcode
    set :haml, "./my_haml_views"
  
    class Hello < Route '/hello'
      def get
        @t = Time.now
        
        # This implies that capcode-render-haml is installed !
        render :haml => :time
      end
    end
  end
  
  Capcode.run( )
  
  # ./my_haml_views/time.haml
  %html
    %body
      %p 
        Hello World 
        = @t

=== Render with JSON

  # file: sample.rb
  require 'rubygems'
  require 'capcode'

  module Capcode
    class Hello < Route '/hello'
      def get
        @t = Time.now

        # This implies that capcode-render-json is installed !
        render :json => { :time => @t }
      end
    end
  end

  Capcode.run( )

=== Render with WebDAV

  # file: sample.rb
  require 'rubygems'
  require 'capcode'
  
  module Capcode
  
    # !!! Render file from /Users/greg/temp !!!
    class WebDav < Route '/temp'
      def get
        # This implies that capcode-render-webdav is installed !
        render :webdav => "/Users/greg/temp"
      end
      
      def method_missing(id, *a, &b)
        get
      end
    end  
    
    class Index < Route '/'
      def get
        render "WebDav server acces : <a href='#{URL(Capcode::WebDav)}'>#{URL(Capcode::WebDav)}</a>"
      end
    end
    
  end

  Capcode.run( )

=== HTTP Authentication

  # file: sample.rb
  require 'rubygems'
  require 'capcode'

  module Capcode
    class Public < Route '/public'
      def get
        render "This page is not protected"
      end
    end

    class Private < Route '/private'
      def get
        http_authentication( :type => :digest, :realm => "Private part" ) { 
          { "greg" => "p4ssw0rd" }
        }
      
        render "This page is private - Hello #{request.env['REMOTE_USER']}"
      end
    end
  end

  Capcode.run( )

Second example :

  # file: sample.rb
  require 'rubygems'
  require 'capcode'
  
  module Capcode

    http_authentication( :type => :digest, :realm => "Private part", :routes => ['/admin', '/private'] ) { 
      { "greg" => "p4ssw0rd" }
    }

    class Public < Route '/public'
      def get
        render "This page is not protected"
      end
    end
  
    class Private < Route '/private'
      def get
        render "This page is private - Hello #{request.env['REMOTE_USER']}"
      end
    end

    class PrivateAgain < Route '/private/again'
      def get
        render "This page is also private - Hello #{request.env['REMOTE_USER']}"
      end
    end

    class Admin < Route '/admin'
      def get
        render "This page is private - Hello #{request.env['REMOTE_USER']}"
      end
    end
  end
  
  Capcode.run( )

== DEPLOYMENT

=== With Passenger

First create the directory structure :

  my_app/
  my_app/tmp
  my_app/public
  
Then put your app in <tt>my_app/</tt> and comment or remove the line with <tt>Capcode.run</tt>

Create a rack configuration file (<tt>config.ru</tt>) in <tt>my_app/</tt>

  require 'app'
  run Capcode.application()

<tt>Capcode.application</tt> take the same parameters as <tt>Capcode.run</tt> (and block too). Be carefull, if you use
static files (with the static renderer) you must set the <tt>:root</tt> option (<tt>:root => File.expand_path(File.dirname(__FILE__))</tt> is probably good)

You can now deploy your application like a {"Rack-based Ruby application"}[http://www.modrails.com/documentation/Users%20guide.html#_deploying_a_rack_based_ruby_application]

== REQUIREMENTS:

* rack

== INSTALL:

  sudo gem install capcode

== LICENSE:

Capcode is freely distributable according to the terms of the
GNU General Public License.

This program is distributed without any warranty. See the file
'COPYING' for details.