root/tags/0.4.0/README

= Merb
<em>Lightweight MVC Ruby app server. For high performance dynamic pages.</em>

==== Dependencies
Install these gems first:

* mongrel
* json
* json_pure
* erubis
* mime-types
* rspec
* hpricot
* mocha
* rubigen
* haml
* markaby
* mailfactory
* activerecord (if you want to store sessions in a database)

Then you can build the merb gem from svn trunk like so:

  $ sudo gem install mongrel json json_pure erubis mime-types rspec hpricot mocha rubigen haml markaby mailfactory -y
  $ 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

To run your application, simply type +merb+ in the project directory.

== Features 

=== Mongrel handler
Merb has a Mongrel handler built in that parses incoming requests
including multipart uploads and post as well as <tt>?query=strings</tt>. 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_ RESTful Routes

Note the <tt>r.resource :posts</tt> macro. That makes it possible to use a RESTful CRUD style controller for the posts resource

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

The <tt>r.default_routes</tt> routes adds the standard routes:

        /controller/action/id.xml
        /controller/action/id
        /controller/action.xml
        /controller/action
        /controller.xml  # index action
        /controller      # index action

=== 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.html.erb if no layout exists named after your
controller. You can use render <tt>:layout => :none</tt>.

Merb does not automatically render for you in your controller actions, you have
to call render yourself. I consider this a big advantage over the way rails does 
it for a few reasons. The main reason is that in rails you can only render once 
per action, so it knows if you haven’t rendered it shoudl auto render. Merb on 
the other hand, returns to the browser whatever the return value of your 
controller’s action method is. This opens up more possibilities imho because
now you can return any string from your action and that will be sent down 
the pipe. So Merb’s render method just returns a string and needs to be the 
last thing you call in your action. You can render multiple times and capture 
the results into @ivars and then render a master template with many embeded 
templates. Also if you return a handle on a File or IO object from your action 
then merb will hand that over to mongrel to be streamed out to the client. And 
if you return a Proc object from your action, it will be called and the 
return value sent to the client.

That last point has some cool connotations if you think about it. Merb does 
have a mutex lock around the call to your controller’s action anywhere that
you can call AR objects. Merb’s lock is way smaller then rails giant lock 
though and allows for many more concurrent requests to be handled by one 
process. By returning a Proc object from your action, you allow merb to 
release the lock and the proc is called in multi threaded way. This allows 
for all kinds of cool streaming and ‘futures’ where you return the proc and 
release the mutex. It’s basically like handing over the proc to mongrel and 
mongrel handles calling it in a thread safe manner.


        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 <tt>_comments.rhtml</tt> 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>   

The .jerb template is used for this purpose.

==== RESTful Controllers

RESTful controllers use a different dispatch system based on the request method verbs. Merb
supports multi return values based on the accept header via +respond_to+.

        class Posts < Merb::Controller
          # GET /posts
          # GET /posts.xml
          def index
            @posts = Post.find :all
            respond_to {|format|
              format.html { render }
              format.js   { render :js => :index }
              format.xml  { render :xml => @posts.to_xml }
            }
          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
        
Learn more about this in the controller documentation.

==== Before and after filters

Use the before method in your controllers. before accepts either a symbol, string 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 dude!</h1>"

        or even render templates:

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

After filters accept a symbol, string or Proc and call that proc with the controller:

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

=== Sessions

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

app/helpers/global_helper.rb will be available to all of your views.
 Helpers named after 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/config/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.
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

A file upload will have a hash of params like this:

        { 
        :filename => File.basename(filename),  
        :content_type => content_type,  
        :tempfile => <Tempfile>, 
        :size => File.size(body) 
        }

== Merb app layout

        merb_app:

          app
            controllers
            models
            views
            parts
            mailers
          config
          lib
          public
          schema
          Rakefile
          scripts
          test
            spec
            unit
          plugins