[Zope3-checkins] CVS: Zope3/src/zope/app/browser/skins - README.txt:1.1 skinsandlayers.png:1.1

[Paul Everitt]

Update of /cvs-repository/Zope3/src/zope/app/browser/skins
In directory cvs.zope.org:/tmp/cvs-serv16575

Added Files:
	README.txt skinsandlayers.png 
Log Message:
Added initial draft of documentation for skins

=== Added File Zope3/src/zope/app/browser/skins/README.txt ===

Conventions for Zope 3 Templates

As the number of skins and usages of skins multiply in Zope 3, we need
to specificy some common patterns and conventions to make sure things
work together.  This document describes the problems that are being
addressed, lists the existing conventions, and proposes a new "usage"
top-level variable to promote template re-use.

Audience

The primary audience of this proposal is Zope 3 framework and product
developers that create templates as a part of views and skins.  This
audience needs:

  o Explanation of UI elements, their location, and what they can
  count on as "official"

  o Improved facilities for the process of generically pluggable user
  interfaces

The second audience is the "non-core" group that will want to assemble
sites and do site development.  The composition of the user interface
needs to be clear and documented.

Goals

This document and proposal has the following 
goals:

  o Allow the template writers for skins and the template writers for
  products to work together.  When someone creates a skin (such as
  Rotterdam or Basic), they are imposing a certain structure on views
  that appear through that skin.  If a product doesn't adhere to that
  structure, bad things happen.  This proposal writes down the
  structure for the built-in skins.

                                                           XXX
  o Ensure that products work in multiple skins.  In a small show this
  is easy, as everyone can adopt the same conventions.  When plugging
  together user interfaces, though, we need the moral equivalent of
  object interfaces.

  o Promote targeted skins (specific to content manager, specific to
  site visitor, etc.) without forking the "global" structure.  The
  decision to improve the UI experience should not lead to a complete
  divorce from existing template work.

Topics

  Skins, Layers, Masters, and Themes

    A Zope 3 skin is a collection of resources that define a page
    structure, behavior, and style.  While the skin doesn't literally
    contain all the templates for all the views of all the objects, it

                              XXX TempLate for templates?
    *is* the governing template for all those templates.  Those
    templates fill slots defined in the skin and use macros from the
    skin.

    Skins introduce the concept of layers, which are collections of
    skin resources for a targeted use.  Layers give a finer
    granularity to skin composition, thus providing two major
    benefits:

      o Template updates and changes are specific in scope and thus
      easier to manage

      o Greater reuse between skins, as you can compose a skin by
      picking and choosing where you get your templates and resources
      from

   Layers can be focused on different purposes.  For instance, some
   layers provide the structure and behavior for all pages on a site.
   For example, a layer might put the major boxes on a page, provide
   important JavaScript handlers, and define macro pages.  Another
   type of layer might focus on only on the look of the site.

   It's important to classify these two kinds of layers, as one has
   more repercussions than the other.  The structural layer, which we
   propose to call a "master" layer, defines a regime of structure
   that all templates rendered under that skin must be aware of.  The
   stylistic layer, which we propose to call a "theme" layer,
   shouldn't break any templates as it imposes no such regime.

   Masters 

    o Skins = Masters + Themes + (other layers)

      o Masters are structure + behavior

      - Need: site developer skin, content manager skin, site visitor
        skin

    - What you write for an application

    - Unique master template 

  The Usage Variable

    A skin must manage structural elements like navigation, tabs, 
    location breadcrumbs... Skin pages need to show all or some of 
    those elements.

      o An object view (as in the Rotterdam skin) has a lot of those 
      structural elements.

      o In dialog-style pages, you don't want elements such as tabs,
      menus, and the location bar.

      o For the screen used in adding a new item, you also want many
      items to disappear, but also to add some information specific to
      this screen.

      o In error dialogs, the location bar doesn't work, because errors
    have no location.

    One option is to manage multiple versions of the master template
    and applying them as whole-page macros on the various pages.  But
    multiple master templates is cumbersome and error-prone.

    To solve this, the skin facility introduces a top-level TAL
    variable called 'usage'.  This variable has a value that sets
    different modes of operation.  This variable can be tested, in the
    master template, to make decisions about what blocks should be
    used in the current usage. This allows to maintain a unique template,
    helping to keep a consistent look and feel.

    The values of the 'usage' are chosen to describe broad categories
    rather than individual templates or elements.  These are the
    proposed values:

      o 'usage/objectview' is the usage when browsing contents.
      Example: folder contents.

      o 'usage/activitydialog' is the usage when you are modifying an
      object in any way.  Example: rename.

      o 'usage/error' is self-explanatory.

      o 'usage/addingdialog' is used during the process of adding a
      new item.

    As an example, the 'template.pt' master template in the
    'rotterdam' skin has the following block::

      <div tal:condition="usage/objectview" 
           tal:repeat="structure view/tabs"></div>

    The main way to set the value of 'usage' for a view is through
    menus defined in ZCML.  The second is through a usage parameter
    which can be provided through some means.

  o Themes are style, look and feel

  o Slot conventions

Open Questions

  o Multiple dimensions (preferences, etc.)


XML Sprint

We're sprinting this week in Belgium.


=== Added File Zope3/src/zope/app/browser/skins/skinsandlayers.png ===
  <Binary-ish file>