From ec5070c2e2d46c5f209da99bb2f3b455ec02c349 Mon Sep 17 00:00:00 2001 From: Pratik Naik Date: Fri, 24 Oct 2008 22:13:06 +0530 Subject: Generate new guides --- .../doc/guides/html/layouts_and_rendering.html | 140 ++++++++++++++++++++- 1 file changed, 136 insertions(+), 4 deletions(-) (limited to 'railties/doc/guides/html/layouts_and_rendering.html') diff --git a/railties/doc/guides/html/layouts_and_rendering.html b/railties/doc/guides/html/layouts_and_rendering.html index 916cdd2053..63d060049a 100644 --- a/railties/doc/guides/html/layouts_and_rendering.html +++ b/railties/doc/guides/html/layouts_and_rendering.html @@ -523,7 +523,7 @@ http://www.gnu.org/software/src-highlite --> 
render :file => filename, :content_type => 'application/rss'
The :layout Option
-

With most of the options to render, the rendered content is displayed as part of the current layout. You'll learn more about layouts and how to use them later in this guide. To find the current layout, Rails first looks for a file in app/views/layouts with the same base name as the controller. For example, rendering actions from the PhotosController class will use /app/views/layouts/photos.html.erb. If there is no such controller-specific layout, Rails will use /app/views/layouts/application.html.erb.

+

With most of the options to render, the rendered content is displayed as part of the current layout. You'll learn more about layouts and how to use them later in this guide.

You can use the :layout option to tell Rails to use a specific file as the layout for the current action:

render :xml => photo, :location => photo_url(photo)
-

2.2.11. Avoiding Double Render Errors

+

2.2.11. Finding Layouts

+

To find the current layout, Rails first looks for a file in app/views/layouts with the same base name as the controller. For example, rendering actions from the PhotosController class will use /app/views/layouts/photos.html.erb. If there is no such controller-specific layout, Rails will use /app/views/layouts/application.html.erb. If there is no .erb layout, Rails will use a .builder layout if one exists. Rails also provides several ways to more precisely assign specific layouts to individual controllers and actions.

+
Specifying Layouts on a per-Controller Basis
+

You can override the automatic layout conventions in your controllers by using the layout declaration in the controller. For example:

+
+
+
class ProductsController < ApplicationController
+  layout "inventory"
+  #...
+end
+
+

With this declaration, all methods within ProductsController will use app/views/layouts/inventory.html.erb for their layout.

+

To assign a specific layout for the entire application, use a declaration in your ApplicationController class:

+
+
+
class ApplicationController < ActionController::Base
+  layout "main"
+  #...
+end
+
+

With this declaration, all views in the entire application will use app/views/layouts/main.html.erb for their layout.

+
Choosing Layouts at Runtime
+

You can use a symbol to defer the choice of layout until a request is processed:

+
+
+
class ProductsController < ApplicationController
+  layout :products_layout
+
+  def show
+    @product = Product.find(params[:id])
+  end
+
+  private
+    def products_layout
+      @current_user.special? ? "special" : "products"
+    end
+
+end
+
+

Now, if the current user is a special user, they'll get a special layout when viewing a product. You can even use an inline method to determine the layout:

+
+
+
class ProductsController < ApplicationController
+  layout proc{ |controller| controller.
+  # ...
+end
+
+
Conditional Layouts
+

Layouts specified at the controller level support :only and :except options that take either a method name or an array of method names:

+
+
+
class ProductsController < ApplicationController
+  layout "inventory", :only => :index
+  layout "product", :except => [:index, :rss]
+  #...
+end
+
+

With those declarations, the inventory layout would be used only for the index method, the product layout would be used for everything else except the rss method, and the rss method will have its layout determined by the automatic layout rules.

+
Layout Inheritance
+

Layouts are shared downwards in the hierarchy, and more specific layouts always override more general ones. For example:

+
+
+
class ApplicationController < ActionController::Base
+  layout "main"
+  #...
+end
+
+class PostsController < ApplicationController
+  # ...
+end
+
+class SpecialPostsController < PostsController
+  layout "special"
+  # ...
+end
+
+class OldPostsController < SpecialPostsController
+  layout nil
+
+  def show
+    @post = Post.find(params[:id])
+  end
+
+  def index
+    @old_posts = Post.older
+    render :layout => "old"
+  end
+  # ...
+end
+
+

In this application:

+
+

2.2.12. Avoiding Double Render Errors

Sooner or later, most Rails developers will see the error message "Can only render or redirect once per action". While this is annoying, it's relatively easy to fix. Usually it happens because of a fundamental misunderstanding of the way that render works.

For example, here's some code that will trigger this error:

@@ -666,8 +799,7 @@ http://www.gnu.org/software/src-highlite -->

3. Structuring Layouts

-

When Rails renders a view as a response, it does so by combining the view with the current layout. To find the current layout, Rails first looks for a file in app/views/layouts with the same base name as the controller. For example, rendering actions from the PhotosController class will use /app/views/layouts/photos.html.erb. If there is no such controller-specific layout, Rails will use /app/views/layouts/application.html.erb. You can also specify a particular layout by using the :layout option to render.

-

Within a layout, you have access to three tools for combining different bits of output to form the overall response:

+

When Rails renders a view as a response, it does so by combining the view with the current layout (using the rules for finding the current layout that were covered earlier in this guide). Within a layout, you have access to three tools for combining different bits of output to form the overall response:

  • -- cgit v1.2.3