Here is documentation about how Zwiki's skins work.

For Developers

This section is pasted from Views.py:

Zwiki has a built-in skin mechanism which aims to just work and be easily customizable, whether in standard zope, CMF or Plone, without requiring any extra products or setup. Here's the scoop:

View methods

view methods are methods which render a particular screen in Zwiki's UI - editform, diffform, the main page view, etc. These define the standard wiki page views which are always available no matter what kind of site we are in. Three examples: the main page view, the edit form, the backlinks form, rendered by __call__(), editform(), and backlinks() respectively. We also have helper view methods which render smaller parts of the UI. Most view methods are defined by the SkinViews? mixin below; others are defined by plugins.

Skin templates

view methods use a skin template to control their rendering. This is a page template, dtml method or file of the same name as the method (perhaps with a suffix added). It is found by looking first in the ZODB (current folder, acquisition context, CMF skin layers), then on the filesystem (plugins, ZWiki/skins/<current skin>, ZWiki/skins/zwiki) - see getSkinTemplate for more details. The default zwiki skin provides all the standard templates, and these may be overridden selectively. They are listed here: http://zwiki.org/QuickReference#skin-templates

Skin macros

the standard zwiki skin uses METAL macros to break things into into manageable pieces. These are chunks of page template which can be reused in other page templates, in one of two ways:

  1. including - the called template fills a space within the caller
  2. wrapping - the called template takes over, and caller fills spaces (slots) within it

All of the macros in the current skin are made available to all skin templates as here/macros.

Plone compatibility

the standard zwiki skin templates (at least) are designed to work in both standard zope and plone wikis. To achieve this all templates call the "here/main_template/macros/master" macro to wrap themselves in the overall site skin. This calls CMF/Plone's main template if we are in CMF, and Zwiki's if we are not (or if we are in plone but have selected the zwiki skin).

Which kind of zodb object should you choose when customizing a skin template ?

page templates
Zope page templates are the workhorse for making dynamic views. They provide better i18n features than dtml, can be well-formed HTML and can be edited by WYSIWYG HTML editors without harm. They can include other page templates or wrap themselves in other page templates using macros.
dtml methods
Zope DTML methods are the precursor to page templates. They are a little faster, a little less explicit, not well-formed HTML, a little harder to debug, and easier to understand than page templates & macros.
files
These are best for chunks of content which do not change much and should be cached. A File object works well for a stylesheet.
images
These are like files, but better for graphics.

Other notes

  • several of the standard Zwiki page templates call a dtml method to do their work. This is simply a convenience so that these views may be installed either in the skin or as editable dtml-enabled wiki pages, allowing more agile development and tweaking. Eg: recentchanges.pt and RecentChanges?.dtml.
  • the stylesheet method looks for a skin template object named stylesheet.css, stylesheet, or stylesheet.dtml, in that order. See also http://zwiki.org/HowToSetUpAnEditableStylesheet .
  • when running zope in debug mode, all filesystem-based skin templates and macros will refresh, showing changes immediately without a zope restart.

For Administrators

Warning

This section is old and needs review.

A skin is a set of PageTemplates (or DTMLMethods?) and perhaps some Files for stylesheets. To display pages and forms Zwiki calls the appropriately-named page template found in the ZODB, or a built-in default.

There are three main ways to set up a zwiki which determine how this is done. These are: simple folder, CMF, and skinned folder, described below. The latter two support multiple skins, selected per user.

Components of a Zwiki skin

Zwiki's user interface consists of several standard views - the page view, edit form, subscribe form, etc. These standard views are defined as methods of the page object (in UI.py) so that skinning can work in all circumstances. These skin methods are responsible for finding and displaying a similarly-named skin template. The skin template is usually a PageTemplate, but DTMLMethods? are also supported for backwards compatibility.

Here are the standard views:

  • wikipage - this page template is used to display a wiki page. For (very) old wikis, DTML methods named standard_wiki_header and standard_wiki_footer are supported as an alternative.
  • backlinks - the backlinks screen
  • contentspage - the wiki contents (page hierarchy) listing
  • diffform - the diff-browsing form (when you click a page's timestamp)
  • editform - the edit form
  • subscribeform - the mail subscription form
  • stylesheet - the wiki's style sheet. May be overridden by a File, Page Template or DTML Method named stylesheet or stylesheet.css.
  • recentchanges - a skin-based version of the RecentChanges? page. Provides the same functionality without enabling DTML in pages.
  • searchwiki - ditto for SearchPage?
  • useroptions - ditto for UserOptions?

Plugins like the issue tracker and rating form provide others, such as

  • issuepropertiesformdtml - the form at the top of issue pages

How skin templates are found

This is flexible and a little complex, so as to work in all situations:

In a simple folder (or folderish object)

This is the simplest, fastest, default setup for a zwiki. Zwiki looks in

  1. the wiki folder
  2. the parent folders, up to the root, via acquisition
  3. ZWiki/skins/default on the filesystem (built-in defaults)

In a CMF or Plone site

CMF does the skinning. So by default, it will look for templates in

  1. the wiki folder (not sure - test)
  2. the parent folders, up to the root, via acquisition (ditto)
  3. portal_skins/custom
  4. portal_skins/zwiki_plone
  5. and any other layers (defined in portal_skins -> Properties) for the user's current skin (selected in Preferences) or the site's default skin (selected in Plone Setup etc.)

In a skinned folder

By using the SkinnedFolder and FileSystemSite? products, the CMF skin mechanism can be used without being in a CMF site. Zwiki will look in

  1. the wiki folder (not sure - test)
  2. the parent folders, up to the root, via acquisition (ditto)
  3. any folders or Filesystem Directory Views you have created in skins/ and added to the user's or the default skin in skins -> Properties
  4. ZWiki/skins/default on the filesystem

As with CMF, there is some small performance cost associated with running a wiki in a SkinnedFolder.

See also

updated --simon, Sun, 25 Mar 2007 16:58:11 +0000 reply