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

• Recipe 15.4, "Redirecting to a Different Location"
• Recipe 15.14, "Refactoring the View into Partial Snippets of Views," shows examples of calling render within a view template