root/tags/0.5.2/README

= Merb

Like Ruby on Rails, Merb (Mongrel + ERB) is an MVC framework. Unlike Rails, Merb is ORM-agnostic, JavaScript library agnostic, and template language agnostic, preferring plugins that add in support for a particular feature rather than trying to produce a monolithic library with everything in the core. In fact, this is a guiding principle of the project, which has led to third-party support for the ActiveRecord, DataMapper, and Sequel ORMs.

In addition, it means that the core code in Merb is kept simple and well organised. This has multiple benefits. It means it's faster for one thing. It's also easier to understand, maintain and extend.

=== Get Merb

The simplest way to get Merb is to install the gem:

  $ sudo gem install merb --include-dependencies
  
If you want to contribute (or just use the latest code), you can build the gem from the svn trunk:

  $ 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

==== Dependencies

Currently, Merb itself depends on the following gems:

* mongrel
* json_pure
* erubis
* mime-types
* rspec
* rubigen 
* ruby2ruby 
* rake 
 
** If you are on windows see this blog post oj how to get up and running:
http://www.ghostonthird.com/2007/11/17/merb-on-windows-it-works/
 
You must also have either the json or json_pure gem installed. Note that the json gem 
provides a faster library but will not work with jRuby. 
 
Optionally, merb can take advantage of the following gems: 
 
* mailfactory (if you wish to use merb's mailers)
* haml 1.8 or greater (if you wish to use HAML templates, i.e. .haml files)
* markaby (if you wish to use Markaby template, i.e. .mab files) 
* builder (if you wish to use Builder templates, i.e. .rxml, .rerb or .builder files) 
* memcache-client (for use with Danga Interactive's memcached) 
* swiftiply 
* eventmachine 
* rcov
* ruby-debug (if you want to use debugging functionality)

You will also probably need to install your ORM of choice as well as any gem plugins you want to use (see below).

=== 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 enable ruby-debug support, start Merb with

  $ merb -D

Now you can use the +debugger+ method everywhere in your code to open an rdebug session.
        
To see all the available command line flags use:

        $ merb -h
                
        
== Using Merb

Merb uses the Model-View-Controller (MVC) pattern.  Incoming requests are matched in the Router and
directed to an appropriate controller action.

=== Model

Merb does not come with its own model layer.  While you are free to use whatever data system you like,
the merb core team does maintain plugins for the following Object Relational Mappers (ORM's):

ActiveRecord:: The same ORM that Rails uses. (<tt>sudo gem install merb_activerecord</tt>)
DataMapper:: Fairly new ORM. (<tt>sudo gem install merb_datamapper</tt>)
Sequel:: Fairly new ORM. (<tt>sudo gem install merb_sequel</tt>)

To use your choice ORM, install the appropriate gem and uncomment the appropriate +use_orm+ line in
Merb.root/config/dependencies.rb

=== Controllers

(Merb.root/app/controllers/*)

Merb controllers inherit from Merb::Controller and contain built in view/template rendering.
Incoming requests are usually mapped to a specific method in a controller.  For example, using
the default routes, a request to http://www.yourapp.com/posts/show/1 would call the the #show
method of your PostsController (and params[:id] would = 1.)

The return value of your action function gets sent back to the client as the view.  In most cases,
you are going to want to end your functions with a call to +render+.  By default, +render+ will
render the view template associated with your action (in default merb that would be 
Merb.root/app/views/<controller>/<action>.html.erb - see the View section for more info.)

Controllers can be generated by calling Merb.root/script/generate controller ControllerName.
By default, generated controllers inherit from the Application class (Merb.root/app/controllers/application.rb)
which itself inherits from Merb:Controller.  Application is a good place to put code pertinent to all controllers.
An example would be setting a filter to check if a user is logged in or to preload user data for each controller.

==== +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 actions from 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


=== Views

(Merb.root/app/views/*)

A view can be loosely defined as any data sent back to the client (a "view" of your data.)
By default, Merb controllers send the return value of your controller action as the view.
The Controller#render method simply renders the specified view and returns it as a string.
By default, a call to +render+ without any options renders the view template associated
with that controller action.  Using the default ERB templating system, this means that a
call to +render+ in Posts#index would render the file Merb.root/app/views/posts/index.html.erb

==== Layouts

(Merb.root/app/views/layout/*)

Layouts are generic templates in which your specific view templates are rendered.  A sample
layout could look like:

  <html>
    <head><title>My Application Layout</title></head>
    <body>
      <img src="header" />
      <div id="content">
        <%= catch_content :layout %>
      </div>
    </body>
  </html>

By default, +render+ will look for a corresponding layout for your controller in the form
of Merb.root/app/views/layout/<controller>.html.erb .  If no specific layout is present,
+render+ will attempt to use Merb.root/app/view/layout/application.html.erb

<i>See #render for more details/options, as well as how to use different templating systems
in your app.</i>

You can return several different types of values from your controller actions:

* String: Any string will get sent to the browser as standard text/html
* File/IO: Any file descriptor will get handed over to mongrel to be streamed to the client.
* Proc Object: The object 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.

=== Helpers

(Merb.root/app/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
            helpers
            mailers         
            models
            parts
            views
          config
          gems
          lib
          log
          public
          Rakefile
          script
          spec
          test
            unit