@@ -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 <tt>.erb</tt> extension then it uses a mixture of ERB (included in Ruby) and HTML. If the template file has a <tt>.builder</tt> extension then a fresh instance of <tt>Builder::XmlMarkup</tt> 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 <tt>.html.erb</tt> 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:
<erb>
<b>Names of all the people</b>
<%@people.eachdo|person|%>
Name: <%=person.name%><br/>
<%end%>
</erb>
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:
<erb>
<%#WRONG%>
Hi, Mr. <%puts"Frodo"%>
</erb>
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 <tt>.builder</tt> extension.
Here are some basic examples:
<ruby>
xml.em("emphasized")
xml.em { xml.b("emph & bold") }
xml.a("A Link", "href"=>"http://rubyonrails.org")
xml.target("name"=>"compile", "option"=>"fast")
</ruby>
will produce
<html>
<em>emphasized</em>
<em><b>emph & bold</b></em>
<ahref="http://rubyonrails.org">A link</a>
<targetoption="fast"name="compile"\>
</html>
Any method with a block will be treated as an XML markup tag with nested markup in the block. For example, the following:
<ruby>
xml.div {
xml.h1(@person.name)
xml.p(@person.bio)
}
</ruby>
would produce something like:
<html>
<div>
<h1>David Heinemeier Hansson</h1>
<p>A product of Danish Design during the Winter of '79...</p>
</div>
</html>
A full-length RSS example actually used on Basecamp:
<ruby>
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.tag!("dc:creator", item.author_name) if item_has_creator?(item)
end
end
end
end
</ruby>
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"