Changelog for Products.Andreas09Theme
=====================================

Products.Andreas09Theme - 1.0 Unreleased
----------------------------------------

- Initial package structure. See Products.Andreas09Theme/docs/ZopeSkel.txt
  [zopeskel]

STEP 01 - Preparation
---------------------

Note: These tasks should be performed right after the code was generated by
ZopesSkel, preferably before installing the theme product.
In any case, a Zope (re)start will be needed after applying them.

- Change the name of the Product GS profile to
  give it a name that makes obvious in the installer that it is a theme.

  In Products.Andreas09Theme/Products/Andreas09Theme/profiles.zcml:
    - change the title of the default profile, and name it "Andreas09
      Theme" (line 8).

- Skins folders were named an ugly way by the ZopeSkel template.

  Strip names of the folders that are in skins, their names are now:
  Andreas09Theme_custom_images, Andreas09Theme_custom_templates and
  Andreas09Theme_styles.

  In Products.Andreas09Theme/Products/Andreas09Theme/skins.zcml:
    - reflect changes made on the file system (lines 8, 10, 12).

  In Products.Andreas09Theme/Products/Andreas09Theme/profiles/default/skins.xml:
    - reflect changes made on the file system (text substitution in many
      lines).

STEP 02 - Images
----------------

- The favicon can be cutomized easily by using images with same name in
  portal_skins.

  In Products.Andreas09Theme/Products/Andreas09Theme/skins/Andreas09Theme_custom_images:
    - Drop image called 'favicon.gif'. It must be in windows ICO format

- Other icons can be cutomized easily by using images with same name in
  portal_skins as well.

  In Products.Andreas09Theme/Products/Andreas09Theme/skins/Andreas09Theme_custom_images:
    - Drop images (16x16) called 'user.gif' and 'search_icon.gif'.

- Content Icons can be customized the exact same way.

  In Products.Andreas09Theme/Products/Andreas09Theme/skins/Andreas09Theme_custom_images:
    - Drop images (16x16) called 'site_icon.gif', 'folder_icon.gif',
      'document_icon.gif and 'file_icon.gif'.

- We need a folder for the images that are specific to the theme (it makes it
  easier to identify plone image customizations by keeping them in a specific
  folder, We have the _custom_ folder, we need another one).
  
  In Products.Andreas09Theme/Products/Andreas09Theme/skins/:
    - Create a folder named Andreas09Theme_images.

  In Products.Andreas09Theme/Products/Andreas09Theme/skins.zcml:
    - reflect changes made on the file system (added lines 13-14).

  In Products.Andreas09Theme/Products/Andreas09Theme/profiles/default/skins.xml:
    - reflect changes made on the file system (added lines 14-16, then 25-26).

  Zope Restart Needed at this point, + Product reinstall.

- Now we can add all the images needed for our theme in that folder.

  In Products.Andreas09Theme/Products/Andreas09Theme/skins/Andreas09Theme_custom_images:
    - Drop images named:
        'bodybg-black.jpg'
        'bodybg-blue.jpg'
        'bodybg-green.jpg'
        'bodybg-orange.jpg'
        'bodybg-purple.jpg'
        'bodybg-red.jpg'
        'footerbg.jpg'
        'menuhover-black.jpg'
        'menuhover-blue.jpg'
        'menuhover-green.jpg'
        'menuhover-orange.jpg'
        'menuhover-purple.jpg'
        'menuhover-red.jpg'

  (No restart needed if zope in debug mode..)

STEP 03 - Stylesheet Registration
---------------------------------

- From the ZopeSkel output, there is no stylesheet specific for our theme that
  is located in the portal skins tool.
  Even if we won't use base_properties, we would prefer to have our style

  In Products.Andreas09Theme/Products/Andreas09Theme/skins/Andreas09Theme_styles/:
    - Copy any existing style sheet template ('base.css.dtml' for instance) and
      rename it 'andreas09.css.dtml'

  In Products.Andreas09Theme/Products/Andreas09Theme/profiles/default/cssregistry.xml
    - Add style sheet registration with the portal_css tool (lines 10 to 15).
  
  No Zope restart needed if debug mode is ON, but product reinstall is needed
  for registering the stylesheet in portal_css.

- Start building a basic style with CSS to make our web site look a bit less
  ugly.

  In Products.Andreas09Theme/Products/Andreas09Theme/skins/Andreas09Theme_styles/andreas09.css.dtml:
    - See file to see what changes we applied to the look of our page.

  Even if the site still looks ugly, we already have the base that we will
  need later for building our CSS.

STEP 04 - Logo
--------------

- Easiest way is image customization technique as seen above.
  We won't apply this one (already covered in the principle).

- A bit more complex: use base properties.
  It makes it easy to change the image and image name without having to touch
  template.
  
  In Products.Andreas09Theme/Products/Andreas09Theme/skins/Andreas09Theme_images:
    - Drop image 'plone-logo-256-white-bg.png' available from the Logo Pack:
      available at http://plone.org/about/logo/.

  In Products.Andreas09Theme/Products/Andreas09Theme/skins/Andreas09Theme_styles/base_properties.props:
    - Change logo name (line 5).

- Change the html output: cusomize logo viewlet template.

  copy plone.app.layout/trunk/plone/app/layout/viewlets/logo.pt
  to Products.Andreas09Theme/Products/Andreas09Theme/browser/logo_modified.pt
  
  In Products.Andreas09Theme/Products/Andreas09Theme/browser/logo_modified.pt:
    - Wrap the existing code with a <div></div> tag (See file, beware of
      namespace declarations).

  In Products.Andreas09Theme/Products/Andreas09Theme/browser/configure.zcml:
    - Declare the viewlet that replaces the default one.
      Both 'class' and 'template' must be declared even if we only want to
      change the template, because we still use the logic of the original
      viewlet class.
      Done in the viewlets section of the zcml file.

  Zope Restart Needed at this point (no product reinstall needed).

STEP 05 - Viewlets reorganization - Header
------------------------------------------

- Move breadcrumbs out of header and put it at top of content region.

  In Products.Andreas09Theme/Products/Andreas09Theme/browser/configure.zcml:
    - Register viewlet with the right viewlet manager (lines 23-30).

  In Products.Andreas09Theme/Products/Andreas09Theme/profiles/default/viewlets.xml:
    - Hide the 'plone.path_bar' viewlet in the 'plone.portaltop' manager
      (lines 12-15 at final state of this step).
    - Order 'plone.path_bar' at first position in the 'plone.contentviews'
      manager (lines 27-32 at final state of this step).

- Move the logo viewlet from the 'plone.portalheader' manager to the
  'plone.portaltop' one (at first position).
  
  In Products.Andreas09Theme/Products/Andreas09Theme/browser/configure.zcml:
    - Change the name of the manager interface the viewlet is declared for
      (line 16).
  
  In Products.Andreas09Theme/Products/Andreas09Theme/profiles/default/viewlets.xml:
    - hide the 'plone.logo' viewlet for 'plone.portalheader' and order it the
      correct way in 'plone.portaltop' (lines 4-9 and 20-23 at final state).

- Hide 'plone.site_actions' from 'plone.portalheader' as it will be registered
  with the footer later on.

  In Products.Andreas09Theme/Products/Andreas09Theme/profiles/default/viewlets.xml:
    - Hide the viewlet (line 23).

- Reorder 'plone.personal_bar' inside 'plone.portaltop' to make it appear right
  after the logo section.

  In Products.Andreas09Theme/Products/Andreas09Theme/profiles/default/viewlets.xml:
    - Reorder the viewlet (lines 8-9).

A Zope restart is needed to see those changes, as well as a product reinstall.
Changes for viewlets can be seen in /@@manage-viewlets at any time if needed.

STEP 06 - Styling the new header
--------------------------------

No Zope restart needed nor product reinstall, so the following tasks can be
visually tested with a simple page reload in the browser.

- First we apply a background image to the visual wrapper, keeping the same
  pattern than the original design.
  
  In Products.Andreas09Theme/Products/Andreas09Theme/skins/Andreas09Theme_styles/andreas09.css.dtml:
    - replace line:
        background-color: #f0f0f0;
      with:
        background: #f0f0f0 url(bodybg-black.jpg) repeat-x;

- Then we align logo and personal actions, + some text contrast for these actions.

  In Products.Andreas09Theme/Products/Andreas09Theme/skins/Andreas09Theme_images/:
    - Replace the blue logo with a white one that will render better in
      printed display.

  In Products.Andreas09Theme/Products/Andreas09Theme/skins/Andreas09Theme_styles/andreas09.css.dtml:
    - Add 'Header section' and 'Personal actions' sections as seen in the file
      at final step.
    - Fix float in 'Horizontal menu':
      code needed for this task:
        /* Horizontal menu */
        
        ul#portal-globalnav {
          clear: both;
        }
    - Adjust font weight and decoration for links at top of file.

- Take care of the Sections + Search box horizontal section

  In Products.Andreas09Theme/Products/Andreas09Theme/skins/Andreas09Theme_styles/andreas09.css.dtml:
    - Change the existing code for 'Horizontal menu' with the one as it is
      when the task is completed.
    - Add 'Search box' section its content.

STEP 07 - Structuring and styling the central region
----------------------------------------------------

We can 'easily' set up the style for the content region

In Products.Andreas09Theme/Products/Andreas09Theme/skins/Andreas09Theme_styles/andreas09.css.dtml:

  We add the sections that have these names (with their content):
  'Content wrap', 'Sidebars', 'Login portlet', 'Calendar portlet', 'Navigation
  portlet', 'Breadcrumbs', 'Content' and 'Content Actions'.

STEP 08 - Footer: Viewlets work and styling
-------------------------------------------

We need to wrap the footer inside a <div></div> section with an id in order to
apply a background image.

Only two viewlets will be displayed in the footer, a viewlet with credits
given to the original design, and the portal actions.
Those two viewlets will be called from a custom manager that will be called
from a template containing the <div></div> wrapping.

- We override the original footer viewlet with a template that calls the
  manager that we need.
  We first have to create that specific viewlet manager.
  We will then be able to register 'plone.siteactions' with it.

  In Products.Andreas09Theme/Products/Andreas09Theme/browser/interfaces.py:
    - add the 'IAndreas09Footer' viewlet manager interface that will be used
      for registering the viewlets in 'configure.zcml'.
      Don't forget to add the line that imports 'IViewletManager'.

  In Products.Andreas09Theme/Products/Andreas09Theme/browser/configure.zcml:
    - Register the interface that we just declared and give it the name
      'andreas09.portalfooter' manager.

  In Products.Andreas09Theme/Products/Andreas09Theme/browser/:
    - add file called 'footer_viewlet.pt' with the code that calls the viewlet
      manager inside the right <div></div> wrapper.

  In Products.Andreas09Theme/Products/Andreas09Theme/browser/configure.zcml:
    - add the declaration for the 'andreas09.portalfooter' manager.
    - add the overriding declaration for 'plone.footer' that will use the
      template that was just added.
    - add the declaration for 'plone.site_actions' with the new manager.

- At this stage, we still have the colophon displayed. We can hide it from the
  Generic Setup profile.

  In Products.Andreas09Theme/Products/Andreas09Theme/profiles/default/viewlets.xml:
    - Hide the viewlet called 'plone.colophon' in the 'plone.portalfooter' manager.

- Now that we have the right <div></div> wrapping, we can add a viewlet that
  gives credits to the original design.

  In Products.Andreas09Theme/Products/Andreas09Theme/browser/:
    - add file called 'credits_viewlet.pt' with its entire code.

  In Products.Andreas09Theme/Products/Andreas09Theme/browser/configure.zcml:
    - add the registration of the viewlet called 'andreas09.design_credits'
      for the 'andreas09.portalfooter' manager, specifying that it uses the
      template that we just added.

  In Products.Andreas09Theme/Products/Andreas09Theme/profiles/default/viewlets.xml:
    - Order correctly the two viewlets that we want to see inside the footer,
      means inside the 'andreas09.portalfooter' viewlet manager.

- As things are at the right place, we can apply some CSS rules to the new
  display.

  In Products.Andreas09Theme/Products/Andreas09Theme/skins/Andreas09Theme_styles/andreas09.css.dtml:
    - See the 'Footer' section at the end of the style sheet.

STEP 09 - Portal title: A replacement for the logo
--------------------------------------------------

Sometimes one need to add or replace a part of the default Plone page with one
that uses some logic (or a different logic than the original one).
In this example, the Logo viewlet will be replaced with another one that
displays the title and the description of the portal.
This is not heavy logic, but fetching the portal title and description are
required in order to display them.

- Create the viewlet class that will contain the logic.

  In Products.Andreas09Theme/Products/Andreas09Theme/browser/viewlets.py:
    - Add the class declaration in the file.
      Do not forget to import 'getMultiAdapter' (see top of file).

- Create the template that will use the logic in the class.

  In Products.Andreas09Theme/Products/Andreas09Theme/browser/:
    - add file called 'portal_title_viewlet.pt' with its entire code.

- Register the viewlet as a replacement for the logo.

  In Products.Andreas09Theme/Products/Andreas09Theme/browser/configure.zcml:
    - modify the registration of the viewlet called 'plone.logo':
      remove the line declaring the template and modify the line that declares
      the class to make it use the class that we just created.

Adding a description to the portal will make it display its full content (the
viewlet displays the description of the portal itself, not the one of the
welcome page).

- New html output can be styled with CSS:

  In Products.Andreas09Theme/Products/Andreas09Theme/skins/Andreas09Theme_styles/andreas09.css.dtml:
    - See changes made under '/* Header section */'.

