home contents changes issues index options help subscribe

Create ZWiki skins from open web templates

Here we try to give some hints on how to use a template from http://www.openwebdesign.org and turn it into a ZWiki skin.

1 Choose a template

Find a nice template at http://www.openwebdesign.org. A good template should have the right amount of elements (especially not too much or too little navigation links, those wiki links have to go somewhere, but you can't fill too much with them). Something with one big column is usually doing fine, since wiki content tends to go in that direction. Having found something suitable, download the folder with its files.

Expand the archive, transfer the files into a fresh ZWiki instance (I use WebDAV for this, ftp works too). The template should already work as static pages now. Look at the HTML and maybe a bit at the CSS, try to understand how the page structure works.

2 The "wikipage.pt" template

Setting up a wikipage.pt template: In the ZMI, create a new Page Template called "wikipage.pt". This is where most of your work will take place and where the html for the normal wiki pages will get set up.

Your downloaded template came with a file called "index.html". Copy the contents of that file into wikipage.pt.

3 Macros and TAL

Take a look through the contents of ZWiki/skins/zwiki/maintemplate.pt on the filesystem (in your copy of the ZWiki source code). From this source code we need some of the surrounding METAL structure. We will have to "mix" this METAL structure with the HTML markup from the openwebdesign template.

A word of warning about the examples: Don't just copy and paste them. Instead look at the html of your chosen template and copy over how the TAL and METAL statements make the html dynamic.

3.1 "main" macro

For one thing we need the surrounding metal:block metal:define-macro="master" around the page, in order to set up the macros that will supply us with the wiki contents. So your wikipage.pt should after this step look something like this:

<metal:block metal:define-macro="master"><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<titl>Templatename</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />

... lots of stuff omitted ...

</html></metal:block>

3.2 Page Content

The actual page content will be filled in wherever we put a tag with tal:content="structure options/body". Easy enough and the wiki code will do all the html details in the content. With a bit of luck, the template's CSS will style the wiki contents very well. So just find the proper place in the template where the main text is and put the tal-statement around it. An excerpt of our template could now look like this:

<div class="content" tal:content="structure options/body">
  <h1>Header as given from template</h1>
  <p>Lots of sample content from the template...</p>
  <p>Which is replaced by our tal:content...</p>
</div>

3.3 Nested "subtopics" for Navigation

If you want to put a "subtopics" listing someplace, there are multiple ways to do it, depending on the style you need. If you want a full "tree" of subtopics, like the standard zwiki displays, you can use a tag with tal:content="structure here/subtopics". An alternative for small sites is a nested listing of all the pages in the site. You get that with tal:replace="structure python:here.renderNesting(here.wikiOutline().nesting())" For both of these you can customize the HTML by setting up a DTML Method called "subtopics_nautica" or "subtopics_yourname", and then setting up a property called subtopics_style (Type: String, Value: "nautica" or the name you gave it) on the ZWiki. If you don't want to show the subtopics in their regular place after the content, add a boolean property called show_subtopics and value False. Note that you can only customize these lists partially, because they are generated recursively with deep magic inside the python code. This may be one place where you would have to touch the CSS itself to adjust things.

3.3.1 Flat "subtopics" for Navigation

The other option that I now mainly use in customizing zwiki skins is to make a loop over the child pages of the current page. Find the relevant listing of such links in the template and make it dynamic with some tal statements. Here is an example:

<ul id="subnavi" tal:define="subs python:[context.pageWithName(p) for p in context.childrenAsList()]">
  <span tal:omit-tag="" tal:repeat="sub subs">
    <li><a href="#" tal:attributes="href sub/absolute_url" tal:content="sub/title">blog</a></li>
  </span>
</ul>

3.4 main menu

For the main site menu (which most templates have), I use a similar strategy. What I do is to get the child pages of the wikis front page, and have each one as one entry in the main menu. If the layout is restricted to a certain number of entries, we can restrict the number of entries in our TAL statements. Which pages are in the main menu and the order of them is defined by the zwiki structure (where each page has a parent page set) and by the ordering of the subpages of the front page. Here is an example that defines a main menu and restricts it to the first 6 entries:

<ul tal:define="subs python:[context.pageWithName(p) for p in context.defaultPage().childrenAsList()]">
  <li tal:repeat="sub python:subs[0:min(len(subs),6)]">
    <a href="onecol.html" tal:attributes="href sub/absolute_url">
      <span tal:replace="sub/title">Big Title</span><br />
    </a>
  </li>
</ul>

3.5 Sibling pages

Again in a similar style we can make links on each page, pointing to all the pages that have the same parent page. Currently the zwiki method we use does not list our own current page, which may be unusual for normal, non-wiki pages. Here is an example of how I do it. Note that I do not have the code appear at all if there are no "sibling" pages:

<div tal:omit-tag=""
tal:define="sublinks python:[context.pageWithName(p) for p in context.siblingsAsList()]">
  <ul class="extras" tal:condition="python:len(sublinks) >= 1">
    <li><a href="#" tal:content="context/title">My own page</a></li>
    <li tal:repeat="sublink sublinks">
      <a href="" tal:attributes="href sublink/absolute_url" tal:content="sublink/title"></a>
    </li>
  </ul>
</div>

3.6 The wiki functionality links

The links that handle the wiki functionality (edit, subscribe, backlinks,...) are copied over from ZWiki/skins/zwiki/links.pt. You will likely insert them in a suitable place where the layout designer made dummy links. For "nautica" I chose to use only the ones where I could reasonably support the functionality, which means that not all ZWiki functionality is properly exposed. We do not display those links if the visitor does not have the privilege to use them. Here is an example of how that may look:

<span tal:omit-tag=""
tal:condition="python:user.has_permission('Zwiki: Edit pages',context)">
  <a href="./editpage"
  tal:attributes="href string:${context/absolute_url}/editform">Edit</a> |
  <a href="./backlinks"
  tal:attributes="href python:here.pageUrl() + '/backlinks'"
  >Backlinks</a> |

  ... and so on ...

</span>

4 Conclusion

This is as far as I got now. Hopefully once the nautica example skin will ship with ZWiki you can look at it and understand more what has to be done. Even with some initial learning time it would take you only a day or two for your first skin, maybe half a week for one where you fiddle with every little detail and get all the functionality working. That's a fast way to get a good designed site!

HowToCreateZwikiSkinsFromOpenWebTemplates