Illustration by Brendan Davis

Building a Community Site - Step-by-Step Part II

As discussed in the previous two installments, Zope 3 has a new architecture for templating. From the view of the site developer and Web designer, this system, called skins, allows the developer to give a common look-and-feel to all content in a site. (This was previously possible in CMF.)

This new article revisits the key ideas previously discussed, makes small corrections based on changes in Zope 3, and shows how information from a Zope 3 site can be included dynamically in the templates for the skin. Topics covered include:

• Review key ideas from previous article
• Point out changes in Zope 3 that lead to corrections
• Introduce a dynamic element into our "zminc" skin

This last article in the series will only show a brief amount of the capabilities of Zope 3 skins, as the important work on the Zope 3 API for templates is still ongoing.

In Part 2, we showed that a Zope 3 skin is really just a Python package, like other Zope 3 software. We can register the package with the Zope 3 configuration system and then work in our own directory.

We also saw the use of a `configure.zcml` file, which is the critical ingredient in all Zope 3 packages. This configuration file wires all new resources we create in our skin into the Zope 3 site. It let us add template files and images to our new skin, as well as organize our work into reusable layers.

Part 2 concluded by showing a simple example of filling in a ZPT slot. This dynamicism is the bridge to this last article in the series.

Let's first start by making two corrections in Part 2. The first is based on a change in the ZCML configuration system of Zope 3. In step 7 of "Turn The Mockup Into a Skin", we stated that `zopeConfigure` is the root element in a ZCML file. This element name has been changed to `configure`, though the previous element name will still be supported.

Next, step 1 in "Integrating Our Mockup" showed that we wrap the `` element in a template into a surrounding `<metal:block>` ZPT element. The last paragraph of that section complained that this produces invalid XHTML. However, use of the surrounding `<metal:block>` element is optional and it is used only when the developer wants the template to emit an XML `DOCTYPE` declaration. This usage is not widely needed, and Zope 3 is investigating ways to accomplish this goal without breaking XHTML validity.

For Part 3, the goal is to include a new navigation element in every page of the site. This navigation element is simple: show the list of subfolders residing in the current folder. This is a common requirement in Website navigation.

Instead of covering the entire system of Zope 3 template conventions and building a template from scratch, we will start by copying the default template from Zope 3. We will then add our new elements into this skin.

We want to use the `template.pt` file from the default Zope 3 skin. This default skin is called “Rotterdam”. Thus:

1. cd ~/sandboxes/Zope3 (presuming this is the directory for your Zope 3 CVS checkout.)
2. cd src/zope/app/browser/skins/rotterdam
3. cp template.pt ~/sandboxes/samplesite
   This `template.pt` file provides the look-and-feel for all pages when they are viewed through the Rotterdam skin. However, this file isn't yet configured for use in our "zminc" skin:
4. Edit the `~/sandboxes/samplesite/configure.zcml` file and change the `<browser:page>` directive to say:
   

   <browser:page
    for="*"
    name="skin_macros"
    permission="zope.View"
    layer="zminc"
    template="template.pt"
    />
   

5. Restart your Zope 3 server.
6. Open the `http://localhost:8080/++skin++zminc/contents.html` URL in your browser.
   Try clicking on the various tabs (Contents, Preview, Caching, etc.). Although the URL changes, we still have our ZMInc logo. This, of course, is the purpose of skinning.
   
   To set the stage for adding in our site navigation element, we will place a box on the screen with static HTML. In the next section, we will convert this to dynamic information from the content (documents, images, etc.) in Zope 3.
7. Open `~/sandboxes/samplesite/template.pt` in an editor.
8. We now add the static box. Find the element containing `

   <div id="navigators">
   
   <div id="sitemenu" class="box">
   <h4 i18n:translate="">Subtopics</h4>
   <div class="body">First Item</div>
   </div>
   

9. Reload the `http://localhost:8080/++skin++zminc/contents.html` URL. No server restart is needed.

By clicking on the various tabs, you can see that we have a new box on all pages. This box, at the top of the left column, is where we will place our navigation element.

The next, and final, step is to fill this box with the right information. We want a sidebar element that shows all the subfolders in the current folder. Future work could filter out the unimportant subfolders by only showing the subfolders with a property called "subtopic", for example.

The strategy for this is to use `tal:repeat` on the folder items. We then format this into HTML elements in the box. This pattern is very common in Zope 2.

1. 1) First, define a variable to contain the sequence of items in the current folder::
   

   <div id="sitemenu" class="box">
   <h4 i18n:translate="">Subtopics</h4>
    <div class="body"
    tal:define="container_contents 
    ">
    </div>
    </div>
   

2. Add a `tal:repeat` to iterate over each item:
   

    <div id="sitemenu" class="box">
    <h4 i18n:translate="">Subtopics </h4>
    <div class="body"
    tal:define="container_contents 
    ">
    <div tal:repeat="item container_contents">
    <img tal:replace="structure item/icon"/>
    </div>
   
    </div>
    </div>
   

3. 3) Finally, add the template to format each matching subfolder:
   

    <div id="sitemenu" class="box">
    <h4 i18n:translate="">Subtopics </h4>
   <div class="body"
    tal:define="container_contents 
    ">
    <div tal:repeat="item container_contents">
    <img tal:replace="structure item/icon"/>
    <a href="#"
    tal:attributes="href item/url"
    tal:content="item/id">content </a>
   </div>
   
    </div>
    </div>
   

To ensure that this works, add some folders to the current folder before viewing the new sidebar.

And that's it, we have a simple example of formatting Zope 3 content into a navigational element. The technique used to grab objects and format them, though, is the low-level API in Zope 3. In future releases, a higher-level API for template "scripters" will be added.

This finishes our series on skins in Zope 3. Much is changing in Zope 3 for the site developer, the audience of this series. In the future, site development will look more familiar to those with experience with Zope 2 techniques.

Paul Everitt: was co-founder of Zope Corporation, serving in a number of positions, including Vice President of Products, CEO, and Chief Strategy Officer. Before co-founding Zope Corporation, Paul was an officer in the United States Navy. He received a degree in materials engineering from the University of Florida in 1990. In 2002, Paul moved with his family to Rennes, France to start Zope Europe.