root/tags/0.3.0/README

<pre>
Copyright (c) 2006 Ezra Zygmuntowicz

Merb. Mongrel+Erb

Little bitty lightweight ruby app server. For when you really need performance
for simple dynamic pages.

** Dependencies **
mongrel
erubis
json or fjson
mime-types
archive-tar-minitar
rspec

Install these gems first then you can build the merb gem from svn trunk like so:
$ sudo gem install mongrel erubis json mime-types archive-tar-minitar rspec --include-dependencies
$ svn co http://svn.devjavu.com/merb/trunk merb
$ cd merb
$ rake install

To generate a new merb app after the gem is installed:
$ merb -g myapp


**FEATURES** 

*Mongrel handler* 
built in that parses incoming requests
including multipart uploads and post as well as ?query=strings. Puts the
params into params and the cookies into cookies when it instantiates your
controller class.

*RouteMatcher and route compiler* 
Reads your route definition and compiles
a method on the fly that will match the request path against each route and do the right thing.

*** NEW RESTFULL ROUTES ***

note the r.resource :posts macro. That makes it possible to use a restfull crud style controller for the posts resource

Merb::RouteMatcher.prepare do |r|
  r.resources :posts
  r.add '/:controller/:action/:id'
  r.add '/', :controller => 'files', :action => 'index'
end

Will be compiled and defined as a method with this lambda as the body:

lambda{|path| 
  case path
  when Regexp.new('/posts/([^/,?]+)[;]edit')
    @sections[:id] = $1
    return {:rest=>true, :controller=>"posts", :allowed=>{:get=>"edit"}}.update(@sections)
  when Regexp.new('/posts/new[;]([^/,?]+)')
    @sections[:action] = $1
    return {:rest=>true, :controller=>"posts", :allowed=>{:post=>"new", :get=>"new", :delete=>"new", :put=>"new"}}.update(@sections)
  when Regexp.new('/posts/new')
    return {:rest=>true, :controller=>"posts", :allowed=>{:get=>"new"}}.update(@sections)
  when Regexp.new('/posts/([^/,?]+)\.([^/,?]+)')
    @sections[:id] = $1
    @sections[:format] = $2
    return {:rest=>true, :controller=>"posts", :allowed=>{:get=>"show", :delete=>"destroy", :put=>"update"}}.update(@sections)
  when Regexp.new('/posts\.([^/,?]+)')
    @sections[:format] = $1
    return {:rest=>true, :controller=>"posts", :allowed=>{:post=>"create", :get=>"index"}}.update(@sections)
  when Regexp.new('/posts/([^/,?]+)')
    @sections[:id] = $1
    return {:rest=>true, :controller=>"posts", :allowed=>{:get=>"show", :delete=>"destroy", :put=>"update"}}.update(@sections)
  when Regexp.new('/posts/?')
    return {:rest=>true, :controller=>"posts", :allowed=>{:post=>"create", :get=>"index"}}.update(@sections)
  when /\A\/([^\/;.,?]+)(?:\/?\Z|\/([^\/;.,?]+)\/?)(?:\/?\Z|\/([^\/;.,?]+)\/?)\Z/
      @sections[:controller] = $1
      @sections[:action] = $2 || 'index'
      @sections[:id] = $3 if $3
      return @sections
  when Regexp.new('/')
    return {:controller=>"files", :action=>"index"}.update(@sections)
  else
    return {:controller=>'Noroutefound', :action=>'noroute'}
  end
}


*Restful Controller*

restful controllers use a different dispatch system based on the request method verbs.

class Posts < Merb::Controller
  # GET /posts
  # GET /posts.xml
  def index
  end

  # GET /posts/1
  # GET /posts/1.xml
  def show
  end

  # GET /posts/new
  def new
  end

  # GET /posts/1;edit
  def edit
  end

  # POST /posts
  # POST /posts.xml
  def create
  end

  # PUT /posts/1
  # PUT /posts/1.xml
  def update
  end

  # DELETE /posts/1
  # DELETE /posts/1.xml
  def destroy
  end
end


*Simple Controllers*
classes with built in render method and template handling
with instance vars available in the views automatically. Merb also supports 
layouts. It will look for a layout named after your controller class first and
then fall back to application.herb if no layout exists named after your controller.
You can use render_no_layout or do render :layout => :none


class Test < Merb::Controller 
  def hello
    # params, headers and cookies are available here.
    @name = params[:name]
    render 
  end 
end

You can also render partials like so:
<%= partial(:comments) %>
This assumes a _comments.rhtml file in the same view dir as the current 
controller/view

Partials compile the template ands returns a string. So you can also call
them and assign them to a var if you want:

def someaction
  @one = partial(:one)
  @two = partial(:two)
end

partials can also render views from other controllers by specifying the path

partial('/shared/foo')


Merb also allows for returning javascript instead of html for ajax actions
You have to use the render_js instead of normal render

def ajax_action
  @posts = Post.find :all
  render_js
end

# ajax_action.jerb
$('comments').update('<%=js partial(:posts) %>');

# _posts.herb
<ul>
  <% @posts.each do |p| %>
    <li>
    <%= p.title %><br />
    <%= p.body %>
    </li>
  <% end %>
</ul>   


*Controllers have powerful before and after filters*

Use the before method in your controllers. before accepts either a symbol 
or a Proc/lambda object. If you give it a symbol it will call a method with
the same name as the symbol. If you give it a proc that takes one argument 
it will call the proc with the current controller as that argument. You can 
use :only and :exclude as options to your filters to exclude or include actionsfrom certain filters. :only and :exclude take :symbols or [:sym, :sam]
array of symbols.

class Foo < Merb::Controller
 
  before :setup_user, :only => :foo
  before lambda {|c| c.headers['X-Foo] = 'bar' }, :exclude => [:foo, :baz]

  def setup_user
    # blah blah
  end

  def foo
    # blah
  end

  def regular_action
    # blah
  end

end

To stop the before filter chain you use throw :halt with a few options:

# halts the filter chain and calls filters_halted which you can override 
# in your controller to specialize it.

throw :halt

# halts the filters and calls the method named after the symbol:

throw :halt, :other_action

# halts the filter chain and returns the result of the Proc being called

throw :halt, Proc.new{ |c| c.redirect "/foo" }

# halts the chain and returns whatever is in the string

throw :halt, "<h1>You don't have permissions IDIOT!</h1>"

or even render templates:

throw :halt, render 'foo'
throw :halt, partial 'foo'

After filters only accept a Proc and call that proc with the controller:

after Proc.new {|c| Tidy.new(c.body) }, :only => :index

Sessions are available when you start merb with the sql_session set to true or the memory_session set to true. See generated app for migration too add session table.

Helpers: dist/app/helpers/global_helper.rb will be available to all of your views. Helpers named afdter your controller plus _helper.rb will be included in the views for that controller only.


*The merb server*
right now you add your routes in
the appdir/dist/conf/router.rb file. So by default it runs on port 4000

$ cd /path/to/your/merb/app
$ merb  

Or to start merb on a different port:
$ merb -p 3500

To start a cluster of merb servers you specify the first port and then how many 
servers you want spawned. SO this command will start a merb instance on ports
3000, 3001, 3002

$ merb -p 3000 -c 3

To start a Merb IRB console where all your models and other classes are pre loaded
use the -i flag

$merb -i

*File uploads* 
This is one of the things that Merb was written for. Rails doesn't allow 
multiple concurrent file uploads at once without blocking an entire rails backend for each file upload. Merb allows multiple file uploads at once.
progress bar. When a file is uploaded with Merb, it gets put in a Tempfile. So 
you just want to copy it to the right place on the filesystem.

def upload
  puts params[:file].inspect
  
  FileUtils.mv params[:file][:tempfile].path, MERB_ROOT+"/uploads/#{params[:file][:filename]}"

  render
end


*Merb app layout* 

A Merb app contains everything it needs to run in production in the 
MERB_ROOT/dist directory. So for deployment you only need to deploy the dist dir. This
keeps your test code and development plugins separate from your main app and lets you
not deploy them to the live server. You deal with two things with this setup, MERB_ROOT
and DIST_ROOT. MERB_ROOT is the root of the whole tree. And DISTROOT is MERB_ROOT+/dist
You will cd into MERB_ROOT to run the merb command line. ANd when you deploy live you
will put the dist dir into another empty MERB_ROOT on the production server.

merb_app:
  Rakefile
  README
  scripts
  test
    spec
    unit
  plugins
  dist
    app
      controllers
      models
      views
    conf
    lib
    public
    plugins
    schema
</pre>