Skip to content
Browse files

Merge patch on subtemplates into layouts & rendering guide

  • Loading branch information...
1 parent e51b8e2 commit 6d0639c95e5385d65005f58ea37f337455753ea9 @ffmike ffmike committed
Showing with 49 additions and 0 deletions.
  1. +49 −0 railties/doc/guides/source/layouts_and_rendering.txt
View
49 railties/doc/guides/source/layouts_and_rendering.txt
@@ -6,6 +6,7 @@ This guide covers the basic layout features of Action Controller and Action View
* Use the various rendering methods built in to Rails
* Create layouts with multiple content sections
* Use partials to DRY up your views
+* Use nested layouts (sub-templates)
== Overview: How the Pieces Fit Together
@@ -976,10 +977,58 @@ Rails determines the name of the partial to use by looking at the model name in
In this case, Rails will use the customer or employee partials as appropriate for each member of the collection.
+=== Using Nested Layouts
+
+You may find that your application requires a layout that differs slightly from your regular application layout to support one particular controller. Rather than repeating the main layout and editing it, you can accomplish this by using nested layouts (sometimes called sub-templates). Here's an example:
+
+Suppose you have the follow ApplicationController layout:
+
++app/views/layouts/application.erb+
+
+[source, html]
+-------------------------------------------------------
+<html>
+<head>
+ <title><%= @page_title %><title>
+ <% stylesheet_tag 'layout' %>
+ <style type="text/css"><%= yield :stylesheets %></style>
+<head>
+<body>
+ <div id="top_menu">Top menu items here</div>
+ <div id="menu">Menu items here</div>
+ <div id="main"><%= yield %></div>
+</body>
+</html>
+-------------------------------------------------------
+
+On pages generated by NewsController, you want to hide the top menu and add a right menu:
+
++app/views/layouts/news.erb+
+
+[source, html]
+-------------------------------------------------------
+<% content_for :stylesheets do %>
+ #top_menu {display: none}
+ #right_menu {float: right; background-color: yellow; color: black}
+<% end -%>
+<% content_for :main %>
+ <div id="right_menu">Right menu items here</div>
+ <%= yield %>
+ <% end -%>
+<% render :file => 'layouts/application' %>
+-------------------------------------------------------
+
+NOTE: In versions of Rails before Rails 2.3, you should use +render \'layouts/applications\'+ instead of +render :file => \'layouts/applications\'+
+
+That's it. The News views will use the new layout, hiding the top menu and adding a new right menu inside the "content" div.
+
+There are several ways of getting similar results with differents sub-templating schemes using this technique. Note that there is no limit in nesting levels. One can use the +ActionView::render+ method via "+render \'layouts/news\'+" to base a new layout on the News layout.
+
== Changelog ==
http://rails.lighthouseapp.com/projects/16213-rails-guides/tickets/15[Lighthouse ticket]
+* December 27, 2007: Merge patch from Rodrigo Rosenfeld Rosas covering subtemplates
* December 27, 2008: Information on new rendering defaults by link:../authors.html#mgunderloy[Mike Gunderloy]
* November 9, 2008: Added partial collection counter by link:../authors.html#mgunderloy[Mike Gunderloy]
* November 1, 2008: Added +:js+ option for +render+ by link:../authors.html#mgunderloy[Mike Gunderloy]

0 comments on commit 6d0639c

Please sign in to comment.
Something went wrong with that request. Please try again.