A contributed administrator's guide from 2002. For modern Zwiki, see AdministratorsGuide.

Table of contents

Zwiki Requirements and Installation

Creating a Successful Wiki

Customising the look of your Zwiki Installation

Setting up Email

Managing Users

Upgrading Zwiki or Zope

Troubleshooting: What to do when things go wrong

Other Zwiki Administration related documentation

This guide has been developed using Zwiki version 0.12.0 and above, and may not be 100% accurate for older versions

If you have experience in doing things with Zwiki, please feel free to add them directly to this page and/or add appropriate comments


Zwiki Requirements and Installation

These are covered in the InstallationNotes? page


Creating a Successful Wiki

Guidelines by Simon Michael

Extracted from an email by Simon Michael

[Wiki's are] a versatile tool and like anything else you've got to set them up right and use them effectively. This can take some practice.

  1. Have a fast clutter-free page layout. Surfing the wiki must be fast and content should not be diluted with irrelevant extras.
  2. Integrate the wiki seamlessly with email. People should be able to monitor discussion and participate fully from their mail client.
  3. Do not make people register to participate.
  4. Make changes visible. Email integration as above, a FastChanges? [page] when [the] RecentChanges? [page] gets too slow, automated queries on the front page to highlight key changes, stats, etc.
  5. Maintain the wiki. Keep the page hierarchy meaningful (surprisingly easy); delete test and insufficiently useful pages; keep control of ThreadMode? (discussion) by channeling it to a single discussion page, and summarizing or just deleting old comments elsewhere. This can be done by one person or many, but it should get done. It's like refactoring a code base to keep it clean.
  6. [Having a] few, bigger wikis can be more efficient to maintain and to use than many, smaller wikis.


Customising the look of your Zwiki Installation

Creating your own headers and footers

Additional steps needed when using folders in your wiki

Files you will need to change

Pages worth adding to your site


Creating your own headers and footers

When you install Zwiki it comes with a number of default pages.

With Zwiki version 0.12.0 they are stored in the $ZWIKI_ROOT/templates/default directory, but from Zwiki 0.13.0 onwards they've been moved to the $ZWIKI_ROOT/skins/default directory.

Any of these can be overridden by using the Zope Management Interface to create a DTML Method document of the same name (minus the .dtml extension) in the directory you want it to affect.

For example, lets say you have the site www.foobar.com. If you want all of this site to have a customised layout, then through the Zope Management Interface you create a standard_wiki_header DTML Method and a standard_wiki_footer DTML Method in the root folder for this website:

A strong advantage with Zwiki is that all subfolders will inherit the headers and footers from their parent folders.

For example, lets say that you want to have two seperate areas of the www.foobar.com website, each with their own look and feel.

If you create a standard_wiki_header DTML Method and standard_wiki_footer DTML Method in the /nifty subdirectory:

then all of the pages in the "/nifty" folder will use them, overriding the ones you created for the top folder.

Without creating specific headers and footers for the /forums folder (www.foobar.com/forums) the forums will use the standard_wiki_header and standard_wiki_footer DTML Methods from the folder above.


Additional steps needed when using folders in your wiki

Most Zwiki installations don't use folders. For example, every page is of the form:

http://www.foobar.com/SomePage
http://www.foobar.com/SomePageA
http://www.foobar.com/SomePageB
http://www.foobar.com/SomePageC

Instead of the traditional:

http://www.foobar.com/SomePage
http://www.foobar.com/SomePageA
http://www.foobar.com/foldera/SomePageB
http://www.foobar.com/folderb/SomePageC
http://www.foobar.com/folderc/SomePageD

etc.

If you plan to use folders in your Zwiki, there are a few extra steps you'll need to take care of.

  1. After creating each folder or sub-folder, copy the SearchPage? into it, otherwise page creation inside the folder won't work properly

    For example:

    http://www.foobar.com/SearchPage (this exists by default)
    http://www.foobar.com/foldera/SearchPage (you need to manually copy SearchPage to here)
    http://www.foobar.com/folderb/SearchPage (you need to manually copy SearchPage to here)
    http://www.foobar.com/folderc/SearchPage (you need to manually copy SearchPage to here)

  2. If you don't want to inherit the standard_wiki_header and standard_wiki_footer files from a parent folder (and thereby retain the look of the page above), you'll need to add versions of them specific to each folder or sub-folder

    For example:

    http://www.foobar.com/foldera/standard_wiki_header
    http://www.foobar.com/foldera/standard_wiki_footer
    http://www.foobar.com/folderb/standard_wiki_header
    http://www.foobar.com/folderb/standard_wiki_footer
    http://www.foobar.com/folderc/standard_wiki_header
    http://www.foobar.com/folderc/standard_wiki_footer


There is further detailed information and notes about using folders/sub-folders and/or sub-wikis on the WikiAcquisition page.

There might be some AcquisitionProblems for you to solve. The use of subfolders is an issue of SubWiki. (just temporary link --FloK)


Files you will need to change

When people go to the RecentChanges? page, it displays a list of pages in your Zwiki site and the people who recently changed them. There are two hardcoded links in the source of this page that will incorrectly direct people to the zwiki.org site when they click on the name of the person who made a change to a Zwiki page.

You will need to adjust these in the source to point to the URL of your Zwiki installation.


Pages worth adding to your site

One of the more useful pages is the AllPages document, as it displays an alphabetical list of all the pages on a Zwiki site. It's not included by default with ZWiki, however if you copy the code from the AllPages page on the Zwiki site into your own Zwiki page, it will work fine.


Setting up Email

Getting email subscription running

An important part of Zwiki is allowing people to Subscribe to a page, so they are emailed whenever someone makes a change to the page and can respond with feedback about the change.

This is covered in some detail in the WikiMail page

An alternative 'mailin' approach is shown in the ZwikiFrontend? page. In the long run this one may be more efficient.


Adding a prefix to outgoing mail subjects

From version 0.12.0 of Zwiki onwards you can now add a prefix to the Subject line of your Zwiki's outgoing email.

You do this by creating a property called mail_subject_prefix for your Zwiki folder, of type string. The value for this property needs to be the text you want added to the start of the subject line on all outgoing email.

For example, if using a mail_subject_prefix with the value of [foo.com] then an email with the Subject of:

    GeneralDiscussion

would instead be emailed out with the subject of:

    [foo.com] GeneralDiscussion


Managing Users

Zwiki uses Zope's user and permissions system. If you want to treat any users differently from others, whether by arranging them into groups or something else, you're going to have to become familar with Zope's system.

If you're using the Zope 2.5.x series, the "Users and Security" section is here:

http://www.zope.org/Documentation/Books/ZopeBook/current/Security.stx

If you're using the Zope 2.6.x series, the "Users and Security" section is here:

http://www.zope.org/Documentation/Books/ZopeBook/2_6Edition/Security.stx

Once you're familiar with that, you'll know how to create new groups (roles) to put users into, you'll know how to create new users and put them in these groups, and you'll also have an understanding of how to give users access to various Zwiki features (i.e. editing pages).


Displaying different options for different users

One of the more important aspects that's not covered however, is how to show different options to users who are logged in, compared to users that are unknown/anonymous.

Let's say that you want your Zwiki to be viewable without restrictions, and anyone can also add a comment, but only users who have logged in are able to edit a page.

Firstly you'll need to adjust the permissions of your Zwiki through the Zope Management Interface (ZMI), then you'll want to make sure that the "Edit Page" option is only shown to the correct users.

This can be done with this piece of DTML code:

 <dtml-if "AUTHENTICATED_USER.has_permission('Zwiki: Edit pages',this())">
 <a href="http://zwiki.org/OldAdministrationGuide2002/editform" title="Edit Page (&dtml-linkTitle;)" accesskey="e">Edit Page</a>
 </dtml-if>
The important thing here is that the DTML "if" statement only executes if the user running it has permission to edit the present Zwiki page. If you've setup the permissions correctly first then the "Edit Page" link will be displayed only for the correct people. You can replace the Zwiki: Edit pages permission with any other valid Zope/Zwikipermission instead too. The 'Zwiki: Add comments to pages' permission is easily restricted in this way also.

And alternative method, for displaying options to users in a particular group, is this:

 <dtml-if "AUTHENTICATED_USER.has_role('somegroup',this())">
 <a href="http://zwiki.org/OldAdministrationGuide2002/editform" title="Edit Page (&dtml-linkTitle;)" accesskey="e">Edit Page</a>
 </dtml-if>
For this example only logged in users belonged to the group somegroup would see the Edit Page option. It won't appear for anyone else.

These two examples of code are generally used in the standard_wiki_header or standard_wiki_footer DTML methods, but are able to be used anywhere that DTML is enabled.


Changing Passwords

Zope doesn't have an inbuilt way of allowing users to change their own passwords in a secure fashion through a website form, so you may need to create your own. Fortunately it's very easy and the instructions + code for doing this can be found here (it's only 1 page):

http://www.zope.org/Members/msx/ChangeOwnPassword-mini-howto


Upgrading Zwiki or Zope

Instructions for upgrading Zwiki, Zope, or both, from prior versions are in the UpgradeGuide? and UpgradeGuide? pages.


Troubleshooting: What to do when things go wrong

When something is going wrong and you're getting error messages, you should do a search of the Zwiki site to find out if other people had the same problem and have already solved it.

If that doesn't help, you're generally best to ask for assistance through the GeneralDiscussion page. You'll need to give details about which Operating System, version of Python, version of Zope, and version of Zwiki you're using, then describe the problem you're having. This should let the experienced members give you some good suggestions on how to fix things.

If you're directed to provide a Traceback for an error, then the instructions for doing that are on the HowToPostATraceback page.


Debugging ZWiki

If you need to debug through Zwiki's python code (the .py files) to find out where something is going wrong, you can use the Zwiki DLOG facility.

Firstly you'll need to restart Zope with two environment variables defined:

 $ export STUPID_LOG_FILE=/tmp/zope.log
 $ export STUPID_LOG_SEVERITY=-100
 $ ./start

This will put the Zope server into a debugging mode, outputing extra debugging information to /tmp/zope.log. This can be a different filename if you want, but the STUPID_LOG_SEVERITY really should be set to -100.

The second thing you can do is embed DLOG statements in the python source code files before you start the Zope server. When Zwiki processes these, the results from them will be sent to the debugging logfile for you to see.

For example, lets say you are debugging a file called mailin.py originally looking like this:

    if self.meta_type == 'ZWiki Page':
        # called in a page context - this will be the destination
        folder, workingpage, destpage, destpagename, creating = \
                self.aq_parent, self, self, self.id(), 0
    else:
        folder = findVirtualHostFor(self,msg) or self
        #  a "working" page, the wiki's default page if possible
        defaultpagename = getattr(folder,'default_page',defaultpage)
        workingpage = getattr(folder,defaultpagename,None)

Adding in some DLOG statements (these are just example) you could get:

    if self.meta_type == 'ZWiki Page':
        # called in a page context - this will be the destination
        DLOG('mailin.py: Not in the else part of things')
        folder, workingpage, destpage, destpagename, creating = \
                self.aq_parent, self, self, self.id(), 0
    else:
        folder = findVirtualHostFor(self,msg) or self
        DLOG('mailin.py: In the else part of things')
        #  a "working" page, the wiki's default page if possible
        defaultpagename = getattr(folder,'default_page',defaultpage)
        workingpage = getattr(folder,defaultpagename,None)
        DLOG('mailin.py: In the else part of things, defaultpagename = ',defaultpagename)

Now, when the mailin.py code is run, the text and variable values from the DLOG statements will be shown in the debugging file /tmp/zope.log


Other Zwiki Administration related documentation

These are other guides, notes, and documents in various stages of completion, related to Administering and configuring Zwiki