+ Quick Templates

Sat Sep 11 12:34:18 EDT 2004

=== Your Daily Hobix Tip: Using Quick Templates ===

Hobix comes with a couple of default template types:

* ERb: These templates are discussed in the tutorial on Hobix.com.  They 
are the most basic templates: Ruby code mingled with HTML.

   <% entries.each do |e| %>
     <div class="titleBar">
     <div class="entryTitle"><%= e.title %></div>
     <div class="entryDate">
       <%= e.created.strftime( "%m %d %Y @ %I:%M %p" ) %></div>
     </div>
     <div class="entryBody">
       <%= e.content.to_html %>
     </div>
   <% end %>

* Redrum: These templates are simply ERb templates which are filtered 
through RedCloth when they are rendered.

   <% entries.each do |e| %>
     h2(entryTitle). <%= e.title %>

     p(entryDate). <%= e.created.strftime( "%m %d %Y @ %I:%M %p" ) %>

     <%= e.content %>
   <% end %>

* Quick: These templates are ERb templates which are broken up into 
chunks as a YAML document.  For me, this has proven to be a great way to 
build a central template and customize it only on certain pages.

=== The Core Quick Template ===

Here's the full default template for Quick:

   --- %YAML:1.0
   # Full page formatting
   page: |
     <+ doctype +>
     <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
     <head>
     <meta http-equiv="Content-Type"
           content="text/html; charset=utf-8" />
     <title><+ title +></title>
     <+ head_tags +>
     <style type="text/css">
     <+ css +>
     </style>
     </head>
     <body>

     <div id="page">

     <+ banner +>

     <div id="content">
     <+ sidebar +>

     <+ blog +>

     </div>
     </div>

     </body>
     </html>

   # Headers and titling
   doctype: |
     <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
                           "DTD/xhtml1-transitional.dtd">
   head_tags:
   css: |
     @import "/site.css";
   title: <%= weblog.title %>
   banner: |
     <div id="banner">
       <h1 class="title">
         <a href="<%= weblog.link %>"><%= weblog.title %></a></h1>
       <div class="tagline"><%= weblog.tagline %></div>
     </div>

   # Sidebar components
   sidebar: |
     <div id="sidebar">
       <+ sidebar_list +>
     </div>
   sidebar_list: ['sidebar_archive', 'sidebar_links',
                  'sidebar_syndicate', 'sidebar_hobix']
   sidebar_archive: |
     <div class="sidebarBox">
       <h2 class="sidebarTitle">Archive</h2>
       <ul>
       <% months = weblog.storage.get_months( weblog.storage.find ) %>
       <% months.each do |month_start, month_end, month_id| %>
           <li><a href="<%= month_id %>"><%=
               month_start.strftime( "%B %Y" ) %></a></li>
       <% end %>
       </ul>
     </div>
   sidebar_links: |
     <div class="sidebarBox">
       <h2 class="sidebarTitle">Links</h2>
       <%= weblog.linklist.content.to_html %>
     </div>
   sidebar_syndicate: |
     <div class="sidebarBox">
       <h2 class="sidebarTitle">Syndicate</h2>
       <ul>
         <li><a href="/index.xml">RSS 2.0</a></li>
       </ul>
     </div>
   sidebar_hobix: |
     <div class="sidebarBox">
       <p>Built upon <a href="http://hobix.com">Hobix</a></p>
     </div>

   # Blog content
   blog: |
     <div id="blog">
       <+ entries +>
     </div>
   entries: |
     <% entries.each_day do |day, day_entries| %>
        <+ day_header +>
        <% day_entries.each do |entry| %>
           <+ entry +>
        <% end %>
     <% end %>
   day_header: |
     <h2 class="dayHeader"><%= day.strftime( "%A, %B %d, %Y" ) %></h2>

   # Entry appearance
   entry: |
     <div class="entry">
       <+ entry_title +>
       <+ entry_content +>
     </div>
     <div class="entryFooter"><+ entry_footer +></div>
   entry_title: |
     <h3 class="entryTitle"><%= entry.title %></h3>
     <% if entry.tagline %><div class="entryTagline"><%=
           entry.tagline %></div><% end %>
   entry_content: |
     <div class="entryContent"><%= entry.content.to_html %></div>
   entry_footer: |
     posted by <%= weblog.authors[entry.author]['name'] %> |
     <a href="<%= entry.link %>"><%=
        entry.created.strftime( "%I:%M %p" ) %></a>

=== About the Core Template ===

As you can see, the core template is enormous.  I wanted the default 
template to be broken into all of its essential pieces, each of which 
can be customized.  Don't be daunted by the size of this template.
You won't need to write templates this large.

The Quick template is simply ERb chunks, each chunk given a name in 
YAML.  The names can then be used in other chunks by using the tag:

   <+ name +>

To add an index page to your site that uses the default Quick template:

   touch skel/index.html.quick

To add an entry page to your site that uses the default Quick template:

   touch skel/entry.html.quick

Now, think about this.  Index pages have several entries, but the entry 
pages only have one entry.  How does Quick template know what to do?

=== `entry' and `entries' in Quick ===

Look at the `blog' section of the template above:

   # Blog content
   blog: |
     <div id="blog">
       <+ entries +>
     </div>

The `entries' chunk is special.  If the Quick module encounters any 
template with <+ entries +>, it will check to see if the page has many 
entries or only one entry.  If the page is a single-entry page, it will 
replace that <+ entries +> with <+ entry +>.

Now look at the `entries' and `entry' templates:

   entries: |
     <% entries.each_day do |day, day_entries| %>
        <+ day_header +>
        <% day_entries.each do |entry| %>
           <+ entry +>
        <% end %>
     <% end %>
   entry: |
     <div class="entry">
       <+ entry_title +>
       <+ entry_content +>
     </div>
     <div class="entryFooter"><+ entry_footer +></div>

Make sure your `entries' chunk is just a wrapper for `entry'.  If both 
ultimately use the `entry' chunk, then your post will look consistent 
throughout your site.

That's all for today, we'll talk about .quick-archive and .quick-summary 
tomorrow.  And next week, we'll talk about customizing Quick.

_why