root/tags/0.4.1/README

= Merb

==== FrameWork Development Dependencies

Install these gems first:

* mongrel
* json
* json_pure
* erubis
* mime-types
* rspec
* hpricot
* mocha
* rubigen
* haml
* markaby
* mailfactory
* Ruby2Ruby

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 Ruby2Ruby -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  myapp

=== 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
        
To see all the available command line flags use:
 
  $ merb -h     

=== 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.


==== 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

=== 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.

=== File uploads
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