+ Custom Quick

[why the lucky stiff]

=== Daily Hobix Tip #6: Custom Quick ===

Yes, we had an introduction to Quick templates over the weekend:
<http://rubyforge.org/pipermail/hobix-is-the-way/2004-September/000003.html>
And to Quick-Summary and Quick-Archive:
<http://rubyforge.org/pipermail/hobix-is-the-way/2004-September/000008.html>

With that background, you can get an idea of how succulent these 
templates are.  You can override any part of the template, restructure 
the positionings and break off pieces into Apache SSIs.  Makes it easier 
to keep a central template that guides the overall look of what you're 
trying to do.

=== Header Tags ===

One common customization is to add meta tags or site-wide JavaScripts.  
You may been obfuscating your e-mail address or providing a popup 
reference throughout your site.

The master template can take site-wide customizations in the hobix.yaml 
config down in the `requires' section:

    requires:
    - hobix/storage/filesys
    - hobix/out/quick:
        head_tags: |
          <meta http-equiv="Pragma" content="no-cache">
          <meta http-equiv="Expires" content="-1">

Hobix plugins can accept customization options.  In Quick's case, the 
customization options are a Hash of template chunk names paired against 
their content.  Again, refer to the master template in the first tip at 
the top of this message for a view of the master template and the 
various chunk names it comes with.

=== Sidebar customization ===

You will probably want to modify the sidebar.  The `sidebar_list' chunk 
is handy if you want to simply change ordering or hide or add parts.  
The default `sidebar_list' is:

   sidebar_list: [sidebar_archive, sidebar_links,
                  sidebar_syndicate, sidebar_hobix]

While most chunks are template strings, you may choose to have chunks 
which are arrays.  Arrays are processed as concatenated chunks.  In 
other words, the above is also equal to:

    sidebar_list: |
      <+ sidebar_archive +>
      <+ sidebar_links +>
      <+ sidebar_syndicate +>
      <+ sidebar_hobix +>

The arrays just make it a bit easier to script this particular component.

Let's add a box at the top with a short blurb.

    - hobix/out/quick:
        head_tags: |
          <meta http-equiv="Pragma" content="no-cache">
          <meta http-equiv="Expires" content="-1">
        sidebar_list: [sidebar_blurb, sidebar_archive, sidebar_links,
                       sidebar_syndicate, sidebar_hobix]
        sidebar_blurb: |
          <div class="sidebarBox">
             <p>I'm a really excellent swimmer.</p>
          </div>

Now, regenerate:

  hobix regen yourBlog

=== Customizing Individual Templates ===

Creating working Quick templates is easy.  You just create a blank file 
for any prefix in skel.

  touch skel/entry.html.quick

With a blank `skel/entry.html.quick' template, Hobix will generate entry 
output using the default Quick template.  No alterations.  However, you 
can store YAML in the template to enforce customizations.

Here's a sample `skel/entry.html.quick' with customizations:

    head_tags: |
      <meta http-equiv="Pragma" content="no-cache">
      <meta http-equiv="Expires" content="-1">
    entry: |
      <% entry_id = entry.id %>
      <h2 class="dayHeader"><%= entry.created.strftime( "%d %b %Y" ) %></h2>
      <div class="entry">
            <+ entry_content +>
      </div>
      <div class="entryFooter"><+ entry_footer +></div>

I love templating this way.  You basically have templates which follow 
an inheritance chain.  At any level of the chain you can start a new 
template from scratch by overriding the `page' chunk, which is the 
top-level chunk.

We'll get into Apache SSIs and turning your template customizations into 
bona fide classes later this week.

_why