Displaying Templates with Render

Problem

Railss default mapping of one action method to one view template is not flexible enough for you. You want to customize the template that gets rendered for a particular action by calling Railss rendering code directly.

Solution

Rendering happens in the ActionController::Base#render method. Railss default behavior is to call render after the action method runs, mapping the action to a corresponding view template. The foo action gets mapped to the foo.rhtml template.

You can call render from within an action method to make Rails render a different template. This controller defines two actions, both of which are rendered using the shopping_list.rhtml template:

class ListController < ApplicationController def index @list = [papaya, polio vaccine] render :action => shopping_list end def shopping_list @list = [cotton balls, amino acids, pie] end end

By default, render assumes that you are talking about the controller and action that are running when render is called. If you call render with no arguments, Rails will work the same way it usually does. But specifying shopping_list as the view overrides this default, and makes the index action use the shopping_list.rhtml template, just like the shopping_list action does.

Discussion

Although they use the same template, visiting the index action is not the same as visiting the shopping_list action. They display different lists, because index defines a different list from shopping_list.

Recall from Recipe 15.4 that the redirect method doesn perform an immediate HTTP redirect. It tells Rails to do a redirect once the current action method finishes running. Similarly, the render method doesn do the rendering immediately. It only tells Rails which template to render when the action is complete.

Consider this example:

class ListController < ApplicationController def index render :action => shopping_list @budget = 87.50 end def shopping_list @list = [lizard food, aking soda] end end

You might think that calling index sets @list but not @budget. Actually, the reverse is true. Calling index sets @budget but not @list.

The @budget variable gets set because render does not stop the execution of the current action. Calling render is like sealing a message in an envelope that gets opened by Rails at some point in the future. You e still free to set instance variables and make other method calls. Once your action method returns, Rails will open the envelope and use the rendering strategy contained within.

The @list variable does not get set because the render call does not call the shopping_list action. It just makes the existing action, index, use the shopping_list.rhtml template instead of the index.rhtml template. There doesn even need to be a shopping_list action: there just has to be a template named shopping_list.rhtml.

If you do want to invoke one action from another, you can invoke the action method explicitly. This code will make index set both @budget and @list:

class ListController < ApplicationController def index shopping_list and render :action => shopping_list @budget = 87.50 end end

Another consequence of this "envelope" behavior is that you must never call render twice within a single client request (the same goes for renders cousin redirect_to, which also seals a message in an envelope).

If you write code like the following, Rails will complain. You e giving it two sealed envelopes, and it doesn know which to open:

class ListController < ApplicationController def plain_and_fancy render :action => plain_list render :action => fancy_list end end

But the following code is fine, because any given request will only trigger one branch of the if/else clause. Whatever happens, render will only be called once per request.

class ListController < ApplicationController def plain_or_fancy if params[:fancy] render :action => fancy_list else render :action => plain_list end end end

With redirect_to, if you want to force your action method to stop running, you can put a return statement immediately after your call to render. This code does not set the @budget variable, because execution never gets past the return statement:

class ListController < ApplicationController def index render :action => shopping_list and return @budget = 87.50 # This line won be run. end end

See Also

Related

Категории