From a79942542eb022812ebd6cf2f857d8ad5f6e1f07 Mon Sep 17 00:00:00 2001 From: Mike Gunderloy Date: Sun, 28 Sep 2008 17:28:26 -0500 Subject: Layout & Rendering Guide --- .../guides/actionview/layouts_and_rendering.txt | 334 ++++++++++++++++++++- 1 file changed, 330 insertions(+), 4 deletions(-) (limited to 'railties/doc/guides/actionview') diff --git a/railties/doc/guides/actionview/layouts_and_rendering.txt b/railties/doc/guides/actionview/layouts_and_rendering.txt index 20ced5913f..5a370500e5 100644 --- a/railties/doc/guides/actionview/layouts_and_rendering.txt +++ b/railties/doc/guides/actionview/layouts_and_rendering.txt @@ -1,5 +1,5 @@ Layouts and Rendering in Rails -===================================== +============================== This guide covers the basic layout features of Action Controller and Action View. By referring to this guide, you will be able to: @@ -332,21 +332,347 @@ head :created, :location => photo_path(@photo) == Structuring Layouts -=== Include Statements +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: + +* Asset tags +* +yield+ and +content_for+ +* Partials + +I'll discuss each of these in turn. + +=== Asset Tags + +Asset tags provide methods for generating HTML that links views to assets like images, javascript, stylesheets, and feeds. There are four types of include tag: + +* auto_discovery_link_tag +* javascript_include_tag +* stylesheet_link_tag +* image_tag + +You can use these tags in layouts or other views, although the tags other than +image_tag+ are most commonly used in the ++ section of a layout. + +WARNING: The asset tags do _not_ verify the existence of the assets at the specified locations; they simply assume that you know what you're doing and generate the link. + +==== Linking to Feeds with +auto_discovery_link_tag+ + +The +auto_discovery_link_tag helper builds HTML that most browsers and newsreaders can use to detect the presences of RSS or ATOM feeds. It takes the type of the link (+:rss+ or +:atom+), a hash of options that are passed through to url_for, and a hash of options for the tag: + +[source, ruby] +------------------------------------------------------- +<%= auto_discovery_link_tag(:rss, {:action => "feed"}, {:title => "RSS Feed"}) %> +------------------------------------------------------- + +There are three tag options available for +auto_discovery_link_tag+: + +* +:rel+ specifies the +rel+ value in the link (defaults to "alternate") +* +:type+ specifies an explicit MIME type. Rails will generate an appropriate MIME type automatically +* +:title+ specifies the title of the link + +==== Linking to Javascript Files with +javascript_include_tag+ + +The +javascript_include_tag+ helper returns an HTML +