diff options
Diffstat (limited to 'guides/source/layouts_and_rendering.textile')
| -rw-r--r-- | guides/source/layouts_and_rendering.textile | 104 |
1 files changed, 54 insertions, 50 deletions
diff --git a/guides/source/layouts_and_rendering.textile b/guides/source/layouts_and_rendering.textile index 4b4f9f3745..b0a87a5981 100644 --- a/guides/source/layouts_and_rendering.textile +++ b/guides/source/layouts_and_rendering.textile @@ -78,16 +78,16 @@ If we want to display the properties of all the books in our view, we can do so <tr> <td><%= book.title %></td> <td><%= book.content %></td> - <td><%= link_to 'Show', book %></td> - <td><%= link_to 'Edit', edit_book_path(book) %></td> - <td><%= link_to 'Remove', book, :confirm => 'Are you sure?', :method => :delete %></td> + <td><%= link_to "Show", book %></td> + <td><%= link_to "Edit", edit_book_path(book) %></td> + <td><%= link_to "Remove", book, :confirm => "Are you sure?", :method => :delete %></td> </tr> <% end %> </table> <br /> -<%= link_to 'New book', new_book_path %> +<%= link_to "New book", new_book_path %> </ruby> NOTE: The actual rendering is done by subclasses of +ActionView::TemplateHandlers+. This guide does not dig into that process, but it's important to know that the file extension on your view controls the choice of template handler. Beginning with Rails 2, the standard extensions are +.erb+ for ERB (HTML with embedded Ruby), and +.builder+ for Builder (XML generator). @@ -177,13 +177,13 @@ h5. Rendering an Action's Template from Another Controller What if you want to render a template from an entirely different controller from the one that contains the action code? You can also do that with +render+, which accepts the full path (relative to +app/views+) of the template to render. For example, if you're running code in an +AdminProductsController+ that lives in +app/controllers/admin+, you can render the results of an action to a template in +app/views/products+ this way: <ruby> -render 'products/show' +render "products/show" </ruby> Rails knows that this view belongs to a different controller because of the embedded slash character in the string. If you want to be explicit, you can use the +:template+ option (which was required on Rails 2.2 and earlier): <ruby> -render :template => 'products/show' +render :template => "products/show" </ruby> h5. Rendering an Arbitrary File @@ -216,18 +216,18 @@ In fact, in the BooksController class, inside of the update action where we want <ruby> render :edit render :action => :edit -render 'edit' -render 'edit.html.erb' -render :action => 'edit' -render :action => 'edit.html.erb' -render 'books/edit' -render 'books/edit.html.erb' -render :template => 'books/edit' -render :template => 'books/edit.html.erb' -render '/path/to/rails/app/views/books/edit' -render '/path/to/rails/app/views/books/edit.html.erb' -render :file => '/path/to/rails/app/views/books/edit' -render :file => '/path/to/rails/app/views/books/edit.html.erb' +render "edit" +render "edit.html.erb" +render :action => "edit" +render :action => "edit.html.erb" +render "books/edit" +render "books/edit.html.erb" +render :template => "books/edit" +render :template => "books/edit.html.erb" +render "/path/to/rails/app/views/books/edit" +render "/path/to/rails/app/views/books/edit.html.erb" +render :file => "/path/to/rails/app/views/books/edit" +render :file => "/path/to/rails/app/views/books/edit.html.erb" </ruby> Which one you use is really a matter of style and convention, but the rule of thumb is to use the simplest one that makes sense for the code you are writing. @@ -306,7 +306,7 @@ h6. The +:content_type+ Option By default, Rails will serve the results of a rendering operation with the MIME content-type of +text/html+ (or +application/json+ if you use the +:json+ option, or +application/xml+ for the +:xml+ option.). There are times when you might like to change this, and you can do so by setting the +:content_type+ option: <ruby> -render :file => filename, :content_type => 'application/rss' +render :file => filename, :content_type => "application/rss" </ruby> h6. The +:layout+ Option @@ -316,7 +316,7 @@ With most of the options to +render+, the rendered content is displayed as part You can use the +:layout+ option to tell Rails to use a specific file as the layout for the current action: <ruby> -render :layout => 'special_layout' +render :layout => "special_layout" </ruby> You can also tell Rails to render with no layout at all: @@ -378,7 +378,7 @@ You can use a symbol to defer the choice of layout until a request is processed: <ruby> class ProductsController < ApplicationController - layout :products_layout + layout "products_layout" def show @product = Product.find(params[:id]) @@ -398,7 +398,7 @@ You can even use an inline method, such as a Proc, to determine the layout. For <ruby> class ProductsController < ApplicationController - layout Proc.new { |controller| controller.request.xhr? ? 'popup' : 'application' } + layout Proc.new { |controller| controller.request.xhr? ? "popup" : "application" } end </ruby> @@ -445,7 +445,7 @@ end <ruby> class OldPostsController < SpecialPostsController - layout nil + layout false def show @post = Post.find(params[:id]) @@ -583,7 +583,7 @@ def show @book = Book.find_by_id(params[:id]) if @book.nil? @books = Book.all - render "index", :alert => 'Your book was not found!' + render "index", :alert => "Your book was not found!" end end </ruby> @@ -686,7 +686,7 @@ You can specify a full path relative to the document root, or a URL, if you pref Rails will then output a +script+ tag such as this: <html> -<script src='/assets/main.js' type="text/javascript"></script> +<script src='/assets/main.js'></script> </html> The request to this asset is then served by the Sprockets gem. @@ -718,8 +718,8 @@ If the application does not use the asset pipeline, the +:defaults+ option loads Outputting +script+ tags such as this: <html> -<script src="/javascripts/jquery.js" type="text/javascript"></script> -<script src="/javascripts/jquery_ujs.js" type="text/javascript"></script> +<script src="/javascripts/jquery.js"></script> +<script src="/javascripts/jquery_ujs.js"></script> </html> These two files for jQuery, +jquery.js+ and +jquery_ujs.js+ must be placed inside +public/javascripts+ if the application doesn't use the asset pipeline. These files can be downloaded from the "jquery-rails repository on GitHub":https://github.com/indirect/jquery-rails/tree/master/vendor/assets/javascripts @@ -770,7 +770,7 @@ By default, the combined file will be delivered as +javascripts/all.js+. You can <erb> <%= javascript_include_tag "main", "columns", - :cache => 'cache/main/display' %> + :cache => "cache/main/display" %> </erb> You can even use dynamic paths such as +cache/#{current_site}/main/display+. @@ -805,7 +805,7 @@ To include +http://example.com/main.css+: <%= stylesheet_link_tag "http://example.com/main.css" %> </erb> -By default, the +stylesheet_link_tag+ creates links with +media="screen" rel="stylesheet" type="text/css"+. You can override any of these defaults by specifying an appropriate option (+:media+, +:rel+, or +:type+): +By default, the +stylesheet_link_tag+ creates links with +media="screen" rel="stylesheet"+. You can override any of these defaults by specifying an appropriate option (+:media+, +:rel+): <erb> <%= stylesheet_link_tag "main_print", :media => "print" %> @@ -833,7 +833,7 @@ By default, the combined file will be delivered as +stylesheets/all.css+. You ca <erb> <%= stylesheet_link_tag "main", "columns", - :cache => 'cache/main/display' %> + :cache => "cache/main/display" %> </erb> You can even use dynamic paths such as +cache/#{current_site}/main/display+. @@ -860,12 +860,6 @@ You can supply a hash of additional HTML options: <%= image_tag "icons/delete.gif", {:height => 45} %> </erb> -You can also supply an alternate image to show on mouseover: - -<erb> -<%= image_tag "home.gif", :onmouseover => "menu/home_highlight.gif" %> -</erb> - You can supply alternate text for the image which will be used if the user has images turned off in their browser. If you do not specify an alt text explicitly, it defaults to the file name of the file, capitalized and with no extension. For example, these two image tags would return the same code: <erb> @@ -884,7 +878,7 @@ In addition to the above special tags, you can supply a final hash of standard H <erb> <%= image_tag "home.gif", :alt => "Go Home", :id => "HomeImage", - :class => 'nav_bar' %> + :class => "nav_bar" %> </erb> h5. Linking to Videos with the +video_tag+ @@ -905,7 +899,7 @@ Like an +image_tag+ you can supply a path, either absolute, or relative to the + The video tag also supports all of the +<video>+ HTML options through the HTML options hash, including: -* +:poster => 'image_name.png'+, provides an image to put in place of the video before it starts playing. +* +:poster => "image_name.png"+, provides an image to put in place of the video before it starts playing. * +:autoplay => true+, starts playing the video on page load. * +:loop => true+, loops the video once it gets to the end. * +:controls => true+, provides browser supplied controls for the user to interact with the video. @@ -1134,13 +1128,6 @@ In Rails 3.0, there is also a shorthand for this. Assuming +@products+ is a coll Rails determines the name of the partial to use by looking at the model name in the collection. In fact, you can even create a heterogeneous collection and render it this way, and Rails will choose the proper partial for each member of the collection: -In the event that the collection is empty, +render+ will return nil, so it should be fairly simple to provide alternative content. - -<erb> -<h1>Products</h1> -<%= render(@products) || 'There are no products available.' %> -</erb> - * +index.html.erb+ <erb> @@ -1162,6 +1149,13 @@ In the event that the collection is empty, +render+ will return nil, so it shoul In this case, Rails will use the customer or employee partials as appropriate for each member of the collection. +In the event that the collection is empty, +render+ will return nil, so it should be fairly simple to provide alternative content. + +<erb> +<h1>Products</h1> +<%= render(@products) || "There are no products available." %> +</erb> + h5. Local Variables To use a custom local variable name within the partial, specify the +:as+ option in the call to the partial: @@ -1175,7 +1169,7 @@ With this change, you can access an instance of the +@products+ collection as th You can also pass in arbitrary local variables to any partial you are rendering with the +:locals => {}+ option: <erb> -<%= render :partial => 'products', :collection => @products, +<%= render :partial => "products", :collection => @products, :as => :item, :locals => {:title => "Products Page"} %> </erb> @@ -1193,6 +1187,16 @@ h5. Spacer Templates Rails will render the +_product_ruler+ partial (with no data passed in to it) between each pair of +_product+ partials. +h5. Partial Layouts + +When rendering collections it is also possible to use the +:layout+ option: + +<erb> +<%= render :partial => "product", :collection => @products, :layout => "special_layout" %> +</erb> + +The layout will be rendered together with the partial for each item in the collection. The current object and object_counter variables will be available in the layout as well, the same way they do within the partial. + h4. 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: @@ -1204,9 +1208,9 @@ Suppose you have the following +ApplicationController+ layout: <erb> <html> <head> - <title><%= @page_title or 'Page Title' %></title> - <%= stylesheet_link_tag 'layout' %> - <style type="text/css"><%= yield :stylesheets %></style> + <title><%= @page_title or "Page Title" %></title> + <%= stylesheet_link_tag "layout" %> + <style><%= yield :stylesheets %></style> </head> <body> <div id="top_menu">Top menu items here</div> @@ -1229,7 +1233,7 @@ On pages generated by +NewsController+, you want to hide the top menu and add a <div id="right_menu">Right menu items here</div> <%= content_for?(:news_content) ? yield(:news_content) : yield %> <% end %> -<%= render :template => 'layouts/application' %> +<%= render :template => "layouts/application" %> </erb> 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. |