merb 0.3.4 → 0.3.7

data/README

@@ -1,68 +1,68 @@
+= Merb
+<em>Lightweight MVC Ruby app server. For high performance dynamic pages.</em>
 
-Copyright (c) 2006 Ezra Zygmuntowicz
+==== Dependencies
+Install these gems first:
 
-Merb.
+* mongrel
+* erubis
+* json
+* mime-types
+* archive-tar-minitar
+* rspec
 
-Lightweight MVC Ruby app server. For high performance dynamic pages.
+Then you can build the merb gem from svn trunk like so:
 
-** Dependencies **
-mongrel
-erubis
-json
-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
+  $ 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
 
+  $ merb -g myapp
+
+To run your application, simply type +merb+ in the project directory.
 
-**FEATURES** 
+== Features 
 
-*Mongrel handler* 
-built in that parses incoming requests
-including multipart uploads and post as well as ?query=strings. Puts the
+=== 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* 
+=== 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 ***
+=== _NEW_ RESTful Routes
 
-note the r.resource :posts macro. That makes it possible to use a restfull crud style controller for the posts resource
+Note the <tt>r.resource :posts</tt> macro. That makes it possible to use a RESTful CRUD style controller for the posts resource
 
-Merb::RouteMatcher.prepare do |r|
-  r.resources :posts
-  r.default_routes
-  r.add '/', :controller => 'files', :action => 'index'
-end
+	Merb::Router.prepare do |r|
+	  r.resources :posts
+	  r.default_routes
+	  r.add '/', :controller => 'files', :action => 'index'
+	end
 
-The r.default_routes routes adds the standard routes:
+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
+	/controller/action/id.xml
+	/controller/action/id
+	/controller/action.xml
+	/controller/action
+	/controller.xml  # index action
+	/controller      # index action
 
+=== Controllers
 
-
-*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 :layout => :none.
+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 
@@ -70,7 +70,7 @@ 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 
+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 
@@ -81,7 +81,7 @@ 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 
+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 
@@ -90,204 +90,213 @@ 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
+	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
+	<%= 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>	
-
-
-*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
-
-
-*Controllers have powerful before and after filters*
+	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
+	class Foo < Merb::Controller
  
-  before :setup_user, :only => :foo
-  before lambda {|c| c.headers['X-Foo] = 'bar' }, :exclude => [:foo, :baz]
+	  before :setup_user, :only => :foo
+	  before lambda {|c| c.headers['X-Foo] = 'bar' }, :exclude => [:foo, :baz]
 
-  def setup_user
-    # blah blah
-  end
+	  def setup_user
+	    # blah blah
+	  end
 
-  def foo
-    # blah
-  end
+	  def foo
+	    # blah
+	  end
 
-  def regular_action
-    # blah
-  end
+	  def regular_action
+	    # blah
+	  end
 
-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.
+	# halts the filter chain and calls filters_halted which you can override 
+	# in your controller to specialize it.
 
-throw :halt
+	throw :halt
 
-# halts the filters and calls the method named after the symbol:
+	# halts the filters and calls the method named after the symbol:
 
-throw :halt, :other_action
+	throw :halt, :other_action
 
-# halts the filter chain and returns the result of the Proc being called
+	# halts the filter chain and returns the result of the Proc being called
 
-throw :halt, Proc.new{ |c| c.redirect "/foo" }
+	throw :halt, Proc.new{ |c| c.redirect "/foo" }
 
-# halts the chain and returns whatever is in the string
+	# halts the chain and returns whatever is in the string
 
-throw :halt, "<h1>You don't have permissions dude!</h1>"
+	throw :halt, "<h1>You don't have permissions dude!</h1>"
 
-or even render templates:
+	or even render templates:
 
-throw :halt, render 'foo'
-throw :halt, partial 'foo'
+	throw :halt, render 'foo'
+	throw :halt, partial 'foo'
 
-After filters accept a symbol, string or   Proc and call that proc with the controller:
+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
+	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: dist/app/helpers/global_helper.rb will be available to all of your views.
+=== Helpers
+
+dist/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*
+=== 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  
+	$ cd /path/to/your/merb/app
+	$ merb  
 
 Or to start merb on a different port:
-$ merb -p 3500
+
+	$ 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
+	$ 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
+	$merb -i
 
-*File uploads* 
+=== 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 
+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
+	def upload
+	  puts params[:file].inspect
   
-  FileUtils.mv params[:file][:tempfile].path, MERB_ROOT+"/uploads/#{params[:file][:filename]}"
+	  FileUtils.mv params[:file][:tempfile].path, MERB_ROOT+"/uploads/#{params[:file][:filename]}"
 
-  render
-end
+	  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* 
+	{ 
+	:filename => File.basename(filename),  
+	:content_type => content_type,  
+	:tempfile => <Tempfile>, 
+	:size => File.size(body) 
+	}
+
+== 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
@@ -297,21 +306,21 @@ and DIST_ROOT. MERB_ROOT is the root of the whole tree. And DISTROOT is MERB_ROO
 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
+	merb_app:
+	  Rakefile
+	  README
+	  scripts
+	  test
+	    spec
+	    unit
+	  plugins
+	  dist
+	    app
+	      controllers
+	      models
+	      views
+	    conf
+	    lib
+	    public
+	    plugins
+	    schema