As the request is handled, the server passes off some information to the dispatcher, principally

The dispatcher’s job is to

All of this happens quickly, behind the scenes. It’s unlikely that you would ever need to dig into the source code for the dispatcher; it’s the sort of thing that you can take for granted to just work. However, to really understand the Rails way, it is important to know what’s going on with the dispatcher. In particular, it’s important to remember that the various parts of your application are just bits (sometimes long bits) of Ruby code, and that they’re getting loaded into a running Ruby interpreter.

For instructional purposes let’s trigger the Rails dispatching mechanism manually. It will give you a good feel for the flow of program control in Rails.

We’ll do this little exercise from the ground up, starting with a new Rails application:

$ rails dispatch_me

Now, create a single controller, with an index action:

$ cd dispatch_me/
$ ruby ./script/generate controller demo index

If you look at the controller you just generated, in app/controllers/demo_controller.rb, you’ll see that it has an index action:

class DemoController < ApplicationController
  def index
  end
end

There’s also a view template file, app/views/demo/index.rhtml, corresponding to the action, and also created automatically, courtesy of the generate script. That template file contains some placeholder language. Just to see things more clearly, let’s replace it with something we’ll definitely recognize when we see it again. Delete the lines in index.rhtml and enter the following:

Hello!

Not much of a design accomplishment, but it will do the trick. Now that we’ve got a set of dominos lined up, it’s just a matter of pushing over the first one: the dispatcher. To do that, start by firing up the Rails console from your Rails application directory. Type ruby script/console from a command prompt:

$ ruby script/console
Loading development environment.
>>

We’re now inside the beating heart of a Rails application and it’s waiting to receive instructions.

There are a pair of environment variables that would normally be set by the web server passing the request to the Rails dispatcher. Since we’re going to be invoking the dispatcher manually, we have to set those environment variables manually:

>> ENV['REQUEST_URI'] = "/demo/index"
=> "/demo/index"
>> ENV['REQUEST_METHOD'] = "get"
=> "get"

We’re now ready to fool the dispatcher into thinking it’s getting a request. Actually, it is getting a request. It’s just that it’s coming from someone sitting at the console, rather than from a web server.

Here’s the command:

>> Dispatcher.dispatch

And here’s the response from the Rails application:

Content-Type: text/html; charset=utf-8
Set-Cookie: _dispatch_me_session_id=336c1302296ab4fa1b0d838d; path=/
Status: 200 OK
Cache-Control: no-cache
Content-Length: 7

Hello!

We’ve executed the dispatch class method of the Ruby class Dispatcher, and as a result, the index action got executed and the index template (such as it is) got rendered and the results of the rendering got wrapped in some HTTP headers and returned.

Just think: If you were a web server, rather than a human, and you had just done the same thing, you could now return that document, headers and “Hello!” and all, to a client. And that’s exactly what happens. Have a look in the public subdirectory of dispatch_me (or any other Rails application). Among other things, you’ll see these dispatcher files:

$ ls dispatch.*
dispatch.cgi  dispatch.fcgi  dispatch.rb

Every time a Rails request comes in, the web server hands control to one of those files. Which file depends on the exact server configuration. Ultimately, they all do the same thing: They call Dispatcher.dispatch, just as you did from the console.

You can follow the trail of bread crumbs even further, if you look at public/.htaccess and your server configuration. But for purposes of understanding the chain of events in a Rails request, and the role of the controller, the peek under the hood we’ve just done is sufficient.

Rails knows that when it gets a request for the index action of the demo controller, what really matters is handing something back to the server. So if there’s no index action in the controller file, Rails shrugs and says, “Well, let’s just assume that if there were an index action, it would be empty anyway, and I’d just render index.rhtml. So that’s what I’ll do.”

You can learn something from an empty controller action, though. Let’s go back to this version of the demo controller:

class DemoController < ApplicationController
  def index
  end
end

What you learn from seeing the empty action is that, at the end of every controller action, if nothing else is specified, the default behavior is to render the template whose name matches the name of the controller and action. In this case, that means app/views/demo/index.rhtml.

In other words, every controller action has an implicit render command in it. And render is actually a real method. You could write the preceding example like this:

def index
  render :template => "demo/index"
end

You don’t have to, though, because it’s assumed that that’s what you want, and that is part of what Rails people are talking about when they discuss convention over configuration. Don’t force the developer to add code that could simply be assumed by convention.

The render command, however, does more than just provide a way of telling Rails to do what it was going to do anyway.

Rendering a template is like putting on a shirt: If you don’t like the first one you find in your closet—the default, so to speak—you can reach for another one and put it on instead.

If a controller action doesn’t want to render its default template, it can render a different one by calling the render method explicitly. Any template file in the app/views directory tree is available. (Actually, that’s not exactly true. Any template on the whole system is available!) But why would you want your controller action to render a template other than its default? There are several reasons, and by looking at some of them, we can cover all of the handy features of the controller’s render method.

A common reason for rendering an entirely different template is to redisplay a form, when it gets submitted with invalid data and needs correction. In such circumstances, the usual web strategy is to redisplay the form with the submitted data, and trigger the simultaneous display of some error information, so that the user can correct the form and resubmit.

The reason that process involves rendering another template is that the action that processes the form and the action that displays the form may be—and often are—different from each other. Therefore, the action that processes the form needs a way to redisplay the original (form) template, instead of treating the form submission as successful and moving on to whatever the next screen might be.

Wow, that was a mouthful of an explanation. Here’s a practical example:

class EventController < ActionController::Base

  def new
    # This (empty) action renders the new.rhtml template, which
    # contains the form for inputting information about the new

    # event record and is not actually needed.
  end
  def create
    # This method processes the form input. The input is available via
    # the params hash, in the nested hash hanging off the :event key.
    @event = Event.new(params[:event])
    if @event.save
      flash[:notice] = "Event created!"
      redirect_to :controller => "main"  # ignore this line for now
    else
      render :action => "new" # doesn't execute the new method!
    end
  end

end

On failure, that is, if @event.save does not return true, we render the "new" template, new.rhtml, again. Assuming new.rhtml has been written correctly, this will automatically include the display of error information embedded in the new (but unsaved) Event object, @event.

Note that the template itself, new.rhtml, doesn’t “know” that it’s been rendered by the create action rather than the new action. It just does its job: It fills out and expands and interpolates, based on the instructions it contains and the data (in this case, @event) that the controller has passed to it.

In a similar fashion, if you are rendering a template for a different action, it is possible to render any template in the system by calling render with either a :template or :file option pointing to the desired template file.

The :template option takes a path relative to the template root (app/views, unless you changed it, which would be extremely unusual), whereas :file takes an absolute filesystem path.

Admittedly, the :template option is rarely used by the majority of Rails developers.

render :template => "abuse/report" # renders 
app/views/abuse/report.rhtml
render :file => "/railsapps/myweb/app/views/templates/common.rhtml"

Another option is to render a partial template (usually referred to simply as a “partial”). In general, usage of partial templates allows you to organize your template code into small files, which helps you to avoid clutter and encourages you to break your template code up into reusable modules.

Partial rendering from a controller is mostly used in conjunction with AJAX calls that need to dynamically update segments of an already displayed page. The technique, along with generic use of partials in views, is covered in greater detail in Chapter 10, “ActionView.”

Occasionally, you need to send the browser the result of translating a snippet of template code, too small to merit its own partial. I admit that this practice is contentious, because it is a flagrant violation of proper separation of concerns between the MVC layers.

One common use case for inline rendering, and probably the only reason it was introduced to begin with, is when using one of the Rails AJAX view helpers, such as auto_complete_result (covered in Chapter 12, “Ajax on Rails”).

render :inline => "<%= auto_complete_result(@headings, 'name') %>"

Rails treats the inline code exactly as if it were a view template.

What if you simply need to send plain text back to the browser, particularly when responding to AJAX and certain types of web service requests?

render :text => 'Submission accepted'

The render command also accepts a series of (convenience) options for returning structured data such as JSON or XML. The content-type of the response will be set appropriately and additional options apply.

render :json => @record.to_json

render :xml => @record.to_xml

On rare occasions, you don’t want to render anything at all. (To avoid a bug in Safari, rendering nothing actually means sending a single space character back to the browser.)

render :nothing => true, :status => 401 # Unauthorized

It’s worth noting that, as illustrated in this snippet, render :nothing => true is often used in conjunction with an HTTP status code (as covered in the next section, “Rendering Options”).

Most calls to the render method accept additional options. Here they are in alphabetical order.

def paid_resource
  if current_user.account_expired?
    response.headers['Location'] =
      account_url(current_user)
    render :text => "Account expired", :status => 307
  end
end

def index
  return render :nothing => true,
                :status => 403 unless logged_in?
  @favorites = current_user.favorites.find(:all)
end

Controller inheritance hierarchies share filters downward. Your average Rails application has an ApplicationController from which all other controllers inherit, so if you wanted to add filters that are always run no matter what, that would be the place to do so.

class ApplicationController < ActionController::Base
  after_filter :compress

Subclasses can also add and/or skip already defined filters without affecting the superclass. For example, consider the two related classes in Listing 2.1, and how they interact.

class BankController < ActionController::Base

  before_filter :audit

  private

    def audit
      # record this controller's actions and parameters in an audit log
    end

end

class VaultController < BankController

  before_filter :verify_credentials

  private

    def verify_credentials
      # make sure the user is allowed into the vault
    end

end

Any actions performed on BankController (or any of its subclasses) will cause the audit method to be called before the requested action is executed. On the VaultController, first the audit method is called, followed by the verify_credentials method, because that’s the order in which the filters were specified. (Filters are executed in the class context where they’re declared, and the BankController has to be loaded before VaultController, since it’s the parent class.)

If the audit method happens to return false for whatever reason, verify_credentials and the requested action are never called. This is called halting the filter chain and when it happens, if you look in your development log, you’ll see a message to the effect that such-and-such a filter halted request processing.

A filter can take one of three forms: method reference (symbol), external class, or inline method (proc). The first is by far the most common and works by referencing a protected or private method somewhere in the inheritance hierarchy of the controller. In the bank example in Listing 2.1, both BankController and VaultController use this form.

class OutputCompressionFilter
  def self.filter(controller)
    controller.response.body = compress(controller.response.body)
  end
end

class NewspaperController < ActionController::Base
  after_filter OutputCompressionFilter
end

class WeblogController < ActionController::Base
  before_filter {|controller| false if controller.params["stop"]}
end

Using before_filter and after_filter appends the specified filters to the existing chain. That‘s usually just fine, but sometimes you care more about the order in which the filters are executed. When that’s the case, you can use prepend_before_filter and prepend_after_filter. Filters added by these methods will be put at the beginning of their respective chain and executed before the rest, like the example in Listing 2.3.

class ShoppingController < ActionController::Base
  before_filter :verify_open_shop

class CheckoutController < ShoppingController
  prepend_before_filter :ensure_items_in_cart, :ensure_items_in_stock

The filter chain for the CheckoutController is now :ensure_items_in_cart, :ensure_items_in_stock, :verify_open_shop. So if either of the ensure filters returns false, we’ll never get around to seeing if the shop is open or not; the filter chain will be halted.

You may pass multiple filter arguments of each type as well as a filter block. If a block is given, it is treated as the last argument.

Around filters wrap an action, executing code both before and after the action that they wrap. They may be declared as method references, blocks, or objects responding to filter or to both before and after.

To use a method as an around_filter, pass a symbol naming the Ruby method. Use yield (or block.call) within the method to run the action.

For example, Listing 2.4 has an around filter that logs exceptions (not that you need to do anything like this in your application; it’s just an example).

around_filter :catch_exceptions

private

  def catch_exceptions
    yield
  rescue => exception
    logger.debug "Caught exception! #{exception}"
    raise
  end

To use a block as an around_filter, pass a block taking as args both the controller and the action block. You can’t call yield directly from an around_filter block; explicitly call the action block instead:

around_filter do |controller, action|
  logger.debug "before #{controller.action_name}"
  action.call
  logger.debug "after #{controller.action_name}"
end

To use a filter object with around_filter, pass an object responding to :filter or both :before and :after. With a filter method, yield to the block like this:

around_filter BenchmarkingFilter

class BenchmarkingFilter
  def self.filter(controller, &block)
    Benchmark.measure(&block)
  end
end

A filter object with before and after methods is peculiar in that you must explicitly return true from the before method if you want the after method to run.

around_filter Authorizer

class Authorizer
  # This will run before the action. Returning false aborts the action
  def before(controller)
    if user.authorized?
      return true
    else
      redirect_to login_url
      return false
    end
  end

  def after(controller)
    # runs after the action only if the before returned true
  end
end

Declaring a filter on a base class conveniently applies to its subclasses, but sometimes a subclass should skip some of the filters it inherits from a superclass:

class ApplicationController < ActionController::Base
  before_filter :authenticate
  around_filter :catch_exceptions
end

class SignupController < ApplicationController
  skip_before_filter :authenticate
end

class ProjectsController < ApplicationController
  skip_filter :catch_exceptions
end

Filters may be limited to specific actions by declaring the actions to include or exclude. Both options accept single actions (like :only => :index) or arrays of actions (:except => [:foo, :bar]).

class Journal < ActionController::Base
  before_filter :authorize, :only => [:edit, :delete]

  around_filter :except => :index do |controller, action_block|
    results = Profiler.run(&action_block)
    controller.response.sub! "</body>", "#{results}</body>"
  end

  private

    def authorize
      # Redirect to login unless authenticated.
    end

end

The before_filter and around_filter methods may halt the request before the body of a controller action method is run. This is useful, for example, to deny access to unauthenticated users.

As mentioned before, all you have to do to halt the filter chain is to return false from the filter. Calling render or redirect_to will also halt the filter chain.

After filters will not be executed if the filter chain is halted. Around filters halt the request unless the action block is called.

If an around filter returns before yielding, it is effectively halting the chain and any after filters will not be run.

If a before filter returns false, the second half of any around filters will still run, but the action method itself will not run, and neither will any after filters.

The send_data method allows you to send textual or binary data to the user as a named file. You can set options that affect the content type and apparent filename, and alter whether an attempt is made to display the data inline with other content in the browser or the user is prompted to download it as an attachment.

send_data generate_tgz('dir'), :filename => 'dir.tgz'

require 'RMagick'

class CaptchaController < ApplicationController

  def image
    # create an RMagic canvas and render difficult to read text on it
    ...
    image = canvas.flatten_images
    image.format = "JPG"

    # send it to the browser
    send_data(image.to_blob, :disposition => 'inline',
                             :type => 'image/jpg')
  end
end

The send_file method streams a file 4096 bytes at a time down to the client. The API docs say, “This way the whole file doesn’t need to be read into memory at once, which makes it feasible to send even very large files.”

Unfortunately, that isn’t true. When you use send_file in a Rails app that runs on Mongrel, which most people do nowadays, the whole file is indeed read into memory! Therefore, using send_file to send big files will give you big headaches. The following section discusses how you can get your web server to serve files directly.

public_dir = File.join(RAILS_ROOT, 'public', 
controller_path)
FileUtils.mkdir_p(public_dir)

FileUtils.cp(filename, File.join(public_dir, 
filename))

send_file '/path/to.zip'

send_file '/path/to.jpg',
          :type => 'image/jpeg',
          :disposition => 'inline'

send_file '/path/to/404.html,
          :type => 'text/html; charset=utf-8',
          :status => 404

send_file @video_file.path,
          :filename => video_file.title + '.flv',
          :type => 'video/x-flv',
          :disposition => 'inline'

The solution to the memory-consumption problems inherent to send_file is to leverage functionality provided by Apache, Lighttpd, and Nginx that allows you to serve files directly from the web server, even if they’re not in a public document directory. The technique works by setting a special HTTP request header with the path to the file you want the web server to send along to the client.

Here’s how you do it in Apache and Lighttpd:

response.headers['X-Sendfile'] = path

And here’s how you do it with Nginx:

response.headers['X-Accel-Redirect'] = path

In both cases, you want to end your controller action method by telling Rails to not bother sending anything, since the web server will handle it.

render :nothing => true

Regardless of how you do it, you may wonder why you would need a mechanism to send files to the browser anyway, since it already has one built in—requesting files from the public directory. Well, lots of times a web application will front files that need to be protected from public access.^[7] (That’s practically every porn site in existence!)