Template Design Documentation
  
  Meta::
  
    Valid for:  Silva 0.9, Zope 2.5.1, Python 2.1.3
    Author:     kit blake
    Email:      kitblake+infrae.com
    CVS:        $Revision: 1.8 $ $Date: 2003/02/24 06:29:59 $

  This document describes how template designers can customize layouts at
  different levels and locations within Silva. 

  The first section explains how the public view can be customized in
  different locations. The second section describes the default layout 
  that appears in the "PreviewTab":../../AuthorEditorChief/ContainerObject/PreviewTab.

  Assumptions: --   
    The reader is assumed to have a working knowledge of Zope, and a high
    level knowledge of HTML, CSS, and experience with ZPT's (Zope Page
    Templates). See the references in Appendix B for links to more
    information.
  
    For the purposes of locating objects, the Silva installation is
    assumed to be 'default', where Silva is installed at the
    root level of a Zope instance, and named 'silva'. All paths in this
    document begin with '/silva'.
  
  Nomenclature: -- 
    To limit confusion, we don't use the word 'user'. Silva
    has several built in roles (Author, Editor, ChiefEditor, SiteManager).
    These are always spelled with a capital letter. When we refer to the
    person or organization which has installed Silva, we use the word
    'customer'.
  
  Adding custom layouts in Silva
    
    If no local custom layouts exist, public pages will be defined by a
    ZPT at the top level of Silva::
      
      /silva/layout_macro.html
      
    This ZPT can be adjusted by the customer. It will be acquired by all
    documents in lower folders. Before we analyze its structure, first we
    should explain what happens when a browser request comes in. When an
    index is requested (e.g. 'http://www.x.yz/silva/folder') there is a
    Python script at the top level of Silva which checks for custom
    layouts::
  
      /silva/index_html
  
    This script checks first for an override. An override occurs if a ZPT
    called 'override.html' is present in the current folder. If so, its
    contents are displayed. 
  
    Using override.html
    
      In the 0.8.x release there is a ZPT called 'rename-to-override.html'
      at the top level. There is also a demo of a working override in
      '/silva/demo/layout_demo/override_layout'. If you go to this
      location and click the
      "PreviewTab":../../AuthorEditorChief/PreviewTab, you'll see the
      content of the 'index'. Then click the "presentation
      preview" link. A new window pops up which displays the content
      of the local 'override.html'. The content is 'pure'
      HTML, with no logic, TAL, or macros. You can add your own logic if
      you wish, and there's a tip about how to pull XML content out of the
      local 'index'.
  
      Thus by placing an 'override.html' in a folder, you insert a page
      that is completely custom, meaning that it doesn't necessarily use
      XML content or layout macros from Silva.
  
    Adjusting layout_macro.html and content.html
  
      If no override is found, the 'index_html' script uses 'content.html'
      to render the page. There is a 'content.html' at the top level of
      Silva. If you open it, you'll find that it uses a macro::
        
        metal:use-macro="container/layout_macro.html/macros/layout"
      
      and it contains a number of fill-slots. (If you're not familiar 
      with METAL, see "http://www.zope.org/Members/tone/METAL":http://www.zope.org/Members/tone/METAL 
      for an explanation.) Lets first look at the macro.
      
      Analysis of layout_macro.html
  
        The idea behind this macro is it should be as generic as possible,
        and thus can be used throughout an entire site or branch. To
        achieve this it contains a hierarchy of define-slots, which can be
        filled in a local 'content.html', if necessary. The slots don't
        have to be filled, in fact the fill-slots in 'content.html' can be
        deleted if they're not used.
        
        The layout macro contains the following slots:
        
        - title: the HTML title
        
        - meta: for local metatags
        
        - style: insert stylesheet references
        
        - script: if javascript is needed
        
        - page_header
        
        - navigation: the example 'content.html' fills this slot with a
        breadcrumb trail
        
        - table_of_contents
        
        - main: 'content.html' fills this slot with content from Silva 
        
        - page_footer
        
        One of the metatags is set up to get the Subject field metadata
        from a Silva document::

          <meta name="subject" content="Silva metadata"
            tal:attributes="content python:getattr(here, 'subject', '')" />

        Title, meta, and style are singleton tags, while the others follow
        this format::
  
          <div metal:fill-slot="page_header" tal:omit-tag="">
            
          </div>
  
        The 'tal:omit-tag=""' is there so that if the slot is not filled
        in 'content.html' the tag is not rendered in the HTML. However in
        the demo all the above slots are filled, either with content or a
        comment.
        
        With this setup, generic layout characteristics can be coded in
        the layout macro, while local elements can be implemented in
        'content.html'. For instance, the current layout uses a table to
        present the content. The table never changes, so it's coded in the
        layout macro. To demonstrate the navigation slot, we placed the
        breadcrumb trail in 'content.html', but it really should be in the
        layout macro, because it will work in all locations.
  
        If you view the HTML source of the presentation preview, you'll
        find comments which identify all of the slots except 'main', which
        contains Silva content. We use a convention for the comments in
        these templates: comments which will appear in the HTML source
        start with a capital letter. Those which will be replaced by TAL
        actions are in lower case.
  
        To simplify the 'content.html' ZPT, most of the slots can be
        deleted. In::
  
          /silva/release_demo/local_content/content.html/manage_main
  
        you'll find a simplified version, with a bit of custom text to
        demonstrate the workings. 
  
        There are two additional slots in 'layout_macro.html' which
        contain those listed above:
        
        - head
          
        - body
          
        When necessary you can replace the entire head or body with custom
        content created in 'content.html'. The layout_macro supports this
        and thus doesn't need to be changed.

      Using content.html
  
        In the ZMI, if you go to the 'release_demo' folder::
  
          /silva/release_demo/local_content/manage_main 
          
        you won't find a 'layout_macro.html'. When 'content.html' calls
        the macro, it's acquired from the top level. You also won't find a
        'content.html'. When you view '/silva/release_demo', the
        'index_html' script doesn't find an override, so it looks for
        'content.html', and moves up the acquisition tree until it finds
        one, in this case on the top level.
        
        However, in the subfolder '/silva/release_demo/local_content' the
        script does find a 'content.html', so it uses that one.
        
        **Tip/warning:** when in the Silva Management Interface, if you
        copy and paste a Silva folder, all of the contents -
        including invisible items like 'content.html' - are pasted
        with it.
   
        When you want to customize content locally, use 'content.html'.
        But remember that it will also be acquired by subfolders. If you
        don't want that to happen, use an 'override.html' in that location.
        
        If every page on your site is custom, then you'll have to locate
        each document in a Silva folder with a 'content.html'. 
        
    Wrap up
  
      Ideally you can set up your site so that there is one
      'layout_macro.html' and one 'content.html' at the top level. This
      will make it very easy to maintain, since the layout code exists in
      just one location. If you do need different layouts, you can copy
      the templates into a branch, and hopefully design them so they
      render the entire branch. 
      
      Then let the Authors and Silva do the work....

  Use of 'absolute_url' when <a name="absolute_url">referencing images</a>
 
    Most of the time Zope acquisition works nicely, even correcting
    mistakes in paths. If you're working in a document::
 
      /foo/bar/document
 
    and insert an image which is actually in a top level 'images'
    directory, but the path is not complete (no starting slash)::
 
      <img src="images/logo.gif" ... />
 
    then Zope still finds it. Zope climbs the acquisition tree until it
    finds 'images', then it finds 'logo.gif', and the page displays fine.
    The problem is, the web browser thinks 'logo.gif' is in::
 
      /foo/bar/images/
 
    and if 'logo.gif' is used in multiple pages (because it's included in
    a template), as a visitor descends further, the web browser thinks
    there's an images directory in all directories, such as::
 
      /foo/bar/daz/images/

    This means 'logo.gif' is not cached by the browser, because it thinks
    it's another 'logo.gif' in another location. The same thing happens
    with stylesheet references.
 
    The trick to solve this problem is of general interest (not just for
    Silva). If you reference the image with a TAL attribute that ends with
    'absolute_url'::
 
      <img src="/images/logo.gif" ... 
        tal:attributes="src here/images/logo.gif/absolute_url | nothing" />
 
    then when the html is rendered, the image src is::
 
    "http://www.x.yz/images/logo.gif"
 
    The browser caches the image, and every other reference to 'logo.gif'
    will be the same, so it stays cached. The '| nothing' at the end of
    the attribute insures that if the object is not found, no Zope error
    gets triggered.
 
    *Note for Silva developers*: in the SMI templates, we use an
    additional  element which defines the 'silva_root'. In 0.8 this is a
    property in the root folder. Since 0.8.3 it's included in the core
    code (which also fixes the problem of renaming 'silva' to something
    else). By defining this at the top of a template, Zope doesn't have
    to climb the tree for every reference. The same can be done in the
    layout templates if there are a lot of images in being referenced.
  
    Stylesheet references 
    
      Note that the stylesheet references in the Silva layout templates
      (0.8.x) use the same 'absolute_url' technique::

        <link rel="stylesheet" href="globals/silva.css" type="text/css" 
          tal:attributes="href here/globals/silva.css/absolute_url | nothing" />

<br />
Copyright &copy; 2002, 2003 Infrae. All rights reserved.<br />
See also "LICENSE.txt":license.txt
