From 558f096115eb123eafcea6df66762ba1c10150a6 Mon Sep 17 00:00:00 2001 From: Sebastian Martinez Date: Sat, 16 Apr 2011 18:26:44 -0300 Subject: Added Templates section on ActionView guide. --- .../guides/source/action_view_overview.textile | 101 +++++++++++++++++++++ 1 file changed, 101 insertions(+) (limited to 'railties') diff --git a/railties/guides/source/action_view_overview.textile b/railties/guides/source/action_view_overview.textile index ab9b910270..2e36fd038f 100644 --- a/railties/guides/source/action_view_overview.textile +++ b/railties/guides/source/action_view_overview.textile @@ -118,6 +118,103 @@ h3. Templates, Partials and Layouts As mentioned before, the final HTML output is a composition of three Rails elements: +Templates+, +Partials+ and +Layouts+. Find below a brief overview of each one of them. +h4. Templates + +Action View templates can be written in several ways. If the template file has a .erb extension then it uses a mixture of ERB (included in Ruby) and HTML. If the template file has a .builder extension then a fresh instance of Builder::XmlMarkup library is used. + +Rails supports multiple template systems and uses a file extension to distinguish amongst them. For example, an HTML file using the ERB template system will have .html.erb as a file extension. + +h5. ERB + +Within an ERB template Ruby code can be included using both +<% %>+ and +<%= %>+ tags. The +<% %>+ are used to execute Ruby code that does not return anything, such as conditions, loops or blocks, and the +<%= %>+ tags are used when you want output. + +Consider the following loop for names: + + +Names of all the people +<% @people.each do |person| %> + Name: <%= person.name %>
+<% end %> + + +The loop is setup in regular embedding tags +<% %>+ and the name is written using the output embedding tag +<%= %>+. Note that this is not just a usage suggestion, for Regular output functions like print or puts won't work with ERB templates. So this would be wrong: + + +<%# WRONG %> +Hi, Mr. <% puts "Frodo" %> + + +To suppress leading and trailing whitespaces, you can use +<%-+ +-%>+ interchangeably with +<%+ and +%>+. + +h5. Builder + +Builder templates are a more programmatic alternative to ERB. They are especially useful for generating XML content. An XmlMarkup object named +xml+ is automatically made available to templates with a .builder extension. + +Here are some basic examples: + + +xml.em("emphasized") +xml.em { xml.b("emph & bold") } +xml.a("A Link", "href"=>"http://rubyonrails.org") +xml.target("name"=>"compile", "option"=>"fast") + + +will produce + + +emphasized +emph & bold +A link + + + +Any method with a block will be treated as an XML markup tag with nested markup in the block. For example, the following: + + +xml.div { + xml.h1(@person.name) + xml.p(@person.bio) +} + + +would produce something like: + + +
+

David Heinemeier Hansson

+

A product of Danish Design during the Winter of '79...

+
+ + +A full-length RSS example actually used on Basecamp: + + +xml.rss("version" => "2.0", "xmlns:dc" => "http://purl.org/dc/elements/1.1/") do + xml.channel do + xml.title(@feed_title) + xml.link(@url) + xml.description "Basecamp: Recent items" + xml.language "en-us" + xml.ttl "40" + + for item in @recent_items + xml.item do + xml.title(item_title(item)) + xml.description(item_description(item)) if item_description(item) + xml.pubDate(item_pubDate(item)) + xml.guid(@person.firm.account.url + @recent_items.url(item)) + xml.link(@person.firm.account.url + @recent_items.url(item)) + xml.tag!("dc:creator", item.author_name) if item_has_creator?(item) + end + end + end +end + + +h5. Template caching + +By default, Rails will compile each template to a method in order to render it. When you alter a template, Rails will check the file's modification time and recompile it in development mode. + h4. Partials Partial templates – usually just called "partials" – are another device for breaking the rendering process into more manageable chunks. With a partial, you can move the code for rendering a particular piece of a response to its own file. @@ -222,6 +319,10 @@ You can also specify a second partial to be rendered between instances of the ma Rails will render the +_product_ruler+ partial (with no data passed in to it) between each pair of +_product+ partials. +h4. Layouts + +TODO... + h3. Using Templates, Partials and Layouts in "The Rails Way" TODO... -- cgit v1.2.3