Frequently-asked questions and answers for all things Zwiki-related.

The FAQ is organized roughly like the docs on FrontPage. At the moment there's a fair bit of overlap with the other documentation. Not very fresh - please make one update before you leave. :)

Contents

General

What is wiki, zwiki, zope, plone ?

A wiki is a special kind of website that's easy for anyone to edit. Zwiki is a wiki software implementation, based on Zope, the popular open source web application server. Plone is a content management system built on Zope. See the Glossary for more.

Who is using Zwiki ?

Zwiki is used in academic, business, community and personal sites. PeopleUsingZwiki leads to some of the public zwikis. Many zwikis are behind firewalls, used for organization and project documentation. Current and past users include GNU, Zope, Debian, and Ubuntu.

How does Zwiki differ from the original WikiWikiWeb, other wikis.. ?

FrontPage has an overview of the added features. Note these are generally optional. DifferencesFromClassicWiki might have more info.

At http://wikimatrix.org you can do a rough comparison of Zwiki against other wiki engines.

How do I make my own Zwiki sites ?

You'll need both ZoPe and Zwiki installed on your local machine, or a web server machine you have access to. Or, use one of the public zope sites where you can create your own wikis: http://zope.org, http://freezope.org, etc. At FreeHosting you can request your very own *.zwiki.org site, running the latest and greatest code on this server.

Does Zwiki require or support Plone ? CMF ? CPS ?

Zwiki does not require any of these, but does integrate well with Plone or plain CMF sites. You can move a wiki into or out of these sites and the Zwiki skin will change appropriately. CPS is not supported out of the box, but it should not be too difficult. See ZopeWiki:CPSZWiki. Patches to fix this would be welcome.

Where can I find out more about Zwiki in Plone specifically ?

Zwiki works mostly the same in or out of Plone/CMF; generally the documentation, issue tracker, etc. try to cover both at once, there is also a page specifically for Plone and CMF-specific issues: Zwiki and Plone.

Using Zwiki

How do I use a Zwiki site ?

For basic help, start at the HelpPage.

Editing

How do I edit with an external editor ?

If the server administrator has set up external editing, you'll see a pencil icon near the edit link. Install and configure the ExternalEditor helper application as described on that page. Then, clicking the pencil will bring up the page in your editor of choice.

However, there are still some glitches. If you get a spurious lock error when saving, remove the Wiki-Safetybelt: line and save again (if you're sure it's not a genuine edit conflict).

How do I edit via FTP ?

If the administrator has set up FTP access, use any ftp client or ftp-aware application to connect to the server. You'll need to know:

  • the Zope ftp port number (may be 21, 8021, or something else)
  • a zope login, if required
  • the path to the wiki folder. Note this path may be different from what you see in web urls, because zope FTP does not know about virtual hosts.
  • the id of the page you want to edit. This may be slightly different from the page name. You can find the id in the FTP directory listing or from the url of the page in your web browser.

How do I edit via webDAV ?

Try opening the url of one of your pages, or http://zwiki.org/SandBox , with a webdav-aware editor. Did it work ?

I can't edit via external editor, ftp or webdav - is there some other way I can use a real editor ?

Other options:

  • the w3m, w3m-el and lynx browsers (and eventually others, presumably) allow any editor to be configured for editing text areas.

How do I edit with Emacs ?

  • Configure emacs or gnuclient as your external editor, or text area editor (see above)

  • Use emacs' built-in ftp access (ange-ftp/efs/tramp) to access pages that way. Tramp is the latest and best of these; the path will look something like '/ftp:server#zopeftpport:/path/to/wiki/PageName'. You can configure passwords in ~/.netrc.

    If ftp hangs while connecting, you might need:

    (setq ange-ftp-try-passive-mode nil)
    

    Some glitches remain with emacs ftp access to zope. The main one I know of is where saving will sometimes stop working, permanently. The only workaround I've found is this: load userlock.el and eval-defun the ask-user-about-supersession-threat function (and keep the userlock.el buffer in memory). Thereafter you'll get a couple of debugger prompts whenever you try to change or save the page - just (c)ontinue, (y)es until it's happy - but at least it'll work.

    If you are using XEmacs? and EFS, you may need to '(setq efs-make-backup-files nil)' to prevent it deleting and recreating the page (as a DTML Document, rather than a ZWiki page).

    Turning on html-mode gives some useful highlighting. Eg you could:

    (add-to-list 'auto-mode-alist '("wikiserver:/" . html-mode))
    

How do I upload a file ?

Click edit, enter or select a filename in the "upload a file or image" area, click Change. The file will be uploaded into the wiki folder and a link will be added at the bottom of the page (if it looks like an image, it will be displayed in the page instead).

If the edit form in your wiki doesn't show this option, you probably need to enable 'Add Documents, Images, and Files' permission, normally via the wiki folder's security tab in the ZMI.

How do I rename a page ?

To rename a page, the wiki admin must have granted you the 'Zwiki: Rename pages' permission (in Plone/CMF, 'Zwiki: Edit pages' permission is sufficient, to accomodate CMF (?)). Also, if you are not authenticated you may be required to have at least a username cookie configured in options.

You can rename pages from the standard edit form. Just change the page name field and click Save. A placeholder page will be left and all links to that name will be updated, if possible.

You can also rename pages using the page management form (below).

How do I delete a page ?

To do this, you must have the 'Zwiki: Delete pages' permission and be authenticated or at least have a username cookie (see above).

You can delete a page by editing it and saving it with "DeleteMe" at the beginning.

Or, you can turn on the page management form (see below), visit the page and click the delete button.

The page will be moved to the recycle_bin subfolder (see RecycleBin?).

What is the page management form ?

The page management form is part of the default (non-CMF) skin. It makes page reparenting, renaming and deleting easier is useful when you are doing a lot of wiki maintenance.

managethispage.png

To see this form, you must:

  • be authenticated, or have a username configured in UserOptions?
  • have been granted 'Zwiki: Rename pages' or 'Zwiki: Delete pages' permission

Zope/Zwiki is inserting paragraph tags into my document, destroying the formatting. How do I fix this ?

Markup modes like Structured Text, reStructured Text and wikiwikiweb markup will do this. You should probably change this page's type to HTML. See How do I change a page's type ?

How do I get a left and right square bracket to display properly ?

You could insert a line break between them, like [this ]

You could use a WikiNameEscape, ie put a ! before the left bracket like [this].

On StructuredText pages, you could literal-quote it with :: like:

[this]

I'm starting a new wiki - how can I install the default pages now that Add Wiki Folder is gone ?

From 0.23 you should be able to call the /setupPages method to install these (requires 'Manage properties' permission).

How can I use Kupu with Zwiki pages ?

Zwiki doesn't have Kupu support yet, see #1057.

How long can pages grow, and how do you know when to archive ?

(eg Discussion pages). The largest page on this wiki is about 120K. Pages can grow until one of two things happens:

  1. you get annoyed with how long edits take. The longer the page, the longer it takes to format (especially structured text) when you save it.
  2. python's re module gives a "max recursion limit exceeded" error when you try to save (#395 zwiki's regular expressions may fail with large pages/sites). This depends on the page size, the content, the markup mode, and perhaps your python implementation. You can see in the GeneralDiscussion archive links where we've had to split up pages to work around this.

Page hierarchy

How can I view or print all pages in a hierarchy ?

There's a DTML method you can install which helps with this - see ZwikiPrinting. Another option is to point wget or curl at PAGE/contents or PAGE/offspring, and have it crawl one link deep.

Mail subscription

How does subscription work ?

You can subscribe to a Zwiki-based wiki, or to a single page, in order to receive email whenever someone adds a comment (by default; wikis may also be configured to send mail for every edit).

Some wikis also allow comments to be sent in by email. If configured, becoming a subscriber (anywhere in the wiki) will allow you to do this.

See WikiMail for more details.

How do I subscribe ?

If the wiki admin has configured it, you'll see a subscribe link on each page. Click this (the alt-U shortcut may also work). The first time you visit this form, you'll need to enter your email address and click Change. This will be remembered if you have cookies enabled.

Now you'll see two large buttons. One toggles your subscription to the whole wiki; the other toggles your subscription to the current page. When you are not subscribed, the button backgrounds are red; when you are subscribed, they are green. Try it by clicking subscribe at the bottom of this page.

CMF/Plone notes: the current zwiki_plone skin shows two small buttons, no red/green indicator. Also, you may enter your CMF member id instead of an email address; the address configured in your preferences will be used. Some CMF/Plone sites may customize the subscribe form so that entering a member id is unnecessary.

Other features: other subscribers are briefly listed. If you have other single-page subscriptions, they will be listed also.

How do I unsubscribe ?

Click the subscribe link as above. If you're subscribed to the whole wiki or the current page, you'll see green; click the buttons until they're both red (or go by the text). If you see "other page subscriptions" listed, you can follow those links to unsubscribe there also.

Note: if you don't have cookies enabled, you'll need to enter your email address (or CMF member id) and click Change, first. You should enter the same address that you subscribed with.

Issue tracking

How do I set up issue tracking in my wiki ?

See ZwikiIssueTracker. This procedure should work in CMF or Plone sites also.

Installing Zwiki

How do I install Zope ?

Start at http://zope.org/Products , or use your platform's package installation facility. Zope is cross-platform and pretty easy to install.

How do I install Zwiki ?

Download the latest release from FrontPage, unpack in your zope products directory, restart zope. The Admin Guide [Installation]? chapter has more detail.

How do I install Zwiki in a Plone or CMF site ?

After creating your plone or CMF site, register Zwiki there as described on [Chapter 06: Zwiki and Plone]?. Basically there are two ways: install the cmf_install_zwiki external method and visit SITEURL/cmf_install_zwiki; or install the CMFQuickInstallerTool tool and use it to "install" (register) Zwiki. Now you'll be able to add a Wiki Page using the plone/CMF content management interface.

Can I install Zwiki on Microsoft Windows ? on Mac OS ?

Sure, Zwiki runs anywhere Zope runs. See Installing for tips.

Configuring

What are all the special urls available, like /src, /setupPages, /upgradeAll etc. ?

These are mostly methods provided by the ZWikiPage class, which you can find out by reading the source, or from the APIDocs. Here are a few common ones:

clearCache
upgradeAll
reindex_object
backlinks
comment
diff
map
create
edit
editform
reparent
catalogId
lastEditTime
subscribeform
text
pages
pageIds
wikilink
stxToHtml
zwiki_version

They could also be other zope objects, eg ExternalMethods? or DTMLMethods? in your wiki folder or above:

mailin
fixprops
cmf_install_zwiki
view_source
print

Or they might be coming from your CMF/Plone skin, eg:

wikipage_view
recentchanges
wikinav_portlet

How do I restrict access to my wiki ? Or just to certain features like editing ?

The simplest way: go to your wiki folder's Security tab in the ZMI, find the relevant permissions, and uncheck the "acquire" and other checkboxes (except Manager, probably). Examples:

  • to prevent editing, uncheck the 'Zwiki: edit pages' permission
  • to prevent file upload, uncheck 'Add Documents, Images, and Files'
  • to deny access completely, uncheck 'Access contents information' and 'View' permissions.

Zwiki's default skin tries not to show options the current user does not have permission for, so denying edit, add comment, change page type, file upload etc. will hide those options from the user.

You can configure permissions, roles and users in more complex ways of course. Learn more about Zope's security system in the ZopeBook.

How to allow member registration, other than using Plone ?

I have been interested in registration of wiki users which is something that Plone supplied. But I see that Plone and Zwiki are not working well together if one wants the last two years worth of Zwiki improvements. What is out there to automate user registration, email confirmation and limiting edit access to registered users. JohnDeBruyn

Limiting edit-acces for registered users is quite simple: Just set the zwiki-edit-permission of the container of your zwiki-pages to authenticated and uncheck acquire permissions. For user registration one would have to write a dtml-method. Email-confirmation could be done with Zope's Mailhost object. I have no idea whether this has been done before. Benedikt

How does Zwiki handle page ids and titles ?

Zwiki assigns "canonicalised" page ids which are python-id- and url-safe and always start with a capital (for predictability and to similarity to WikiNames).

Normally you ignore this and just pay attention to the page name you want to use. If you use a bracketed [freeform name]? your page name's capitalization will be remembered.

In other words, you choose the page name, Zwiki chooses the id. Usually this does not cause trouble, especially if you install Zwiki's standard_error_message which enables FuzzyUrls.

But if you manage wiki pages with the plone content management interface, having the edit short names preference enabled, or if you mange them in the ZMI, it gets confusing, because then you can manually override Zwiki's choice of id, which interferes with wiki linking, and when you next edit that page Zwiki will adjust the id again.

So I recommend you don't do that. Let Zwiki set the page ids, and if you need to rename wiki pages it's best to do it via zwiki's edit form or page management form.

Finally if you want to change the canonicalisation scheme for all your wikis: modify canonicalIdFrom().

Ok, how do I set up a login form ?

Zope's built-in login form is a popup dialog ("basic authentication"). You can use any of a number of Zope products to provide a cookie-based, customizable login form. Here are some common options:

  • Plone (or CMF; see ZwikiAndPlone) - just create or move your wiki inside the CMF/Plone site. Advantages: easy, also includes the strongest membership features. Disadvantages: brings a different wiki skin, a bunch of other objects and functionality, and slows things down. You can always replace the zwiki_plone skin with one that hides all the extras, though (http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/zwiki/zwiki/skins/zwiki_orig/Attic/).
  • ExUserFolder (XUF) - add an ExUserFolder acl_users in your wiki folder. You'll need to study the XUF documentation and fiddle around in there to set up the login form. Advantages: lightweight, supports various user database sources. Disadvantages: less actively developed, can be hard to figure out.

How do I allow people to register themselves ?

The Plone/CMF solution above is easiest, ExUserFolder also has support for this.

Does Zwiki use a catalog ?

Most zwikis have a ZCatalog object indexing the pages. Zwiki uses this to speed up and reduce the memory usage of large wikis. Also, having a catalog allows advanced queries like FilterIssues.

Zwiki was for some time designed to work with or without a catalog, but modern versions assume a catalog is present. If you have an older wiki still running without a catalog, visit AnyPage?/upgradeAll (or AnyPage?/setupCatalog) to install one.

ZwikiAndZCatalog has more history and discussion.

How does a zwiki find it's catalog, with multiple catalogs, acquisition, Plone ?

Zwiki looks for a catalog named Catalog in the wiki folder, or a portal_catalog in the wiki folder or above.

My catalog (recent changes, search results, hierarchy) seems confused. How do I rebuild it ?

Visit AnyPage?/upgradeAll as manager. This upgrades, re-renders and re-catalogs every page in the wiki and regenerates the page hierarchy cache. With large wikis, this may take a while. It's best to do it when there is little write/edit activity from other users. It logs progress to event.log at BLATHER level. You can modify its behaviour by passing arguments, see upgradeAll in Admin.py. In the situation of extra catalog entries that shouldn't be there, this might not clear them out (?) - if so then first clear the catalog using ZMI.

You can regenerate just the page hierarchy cache by visiting AnyPage?/updatecontents. Occasionally this will not be enough to fix problems - if so then delete the outline object entirely from the wiki folder and view contents again. (This will lose any manual re-ordering of subtopics.)

Help! I get a UnicodeDecodeError when I enter UTF-8 Unicode characters in Restructured Text pages!

Edit your zope.conf and set both rest-input-encoding and rest-output-encoding to utf-8.

How do I change the list of allowed page types in the edit form ?

  • On the wiki folder in the ZMI, go to the Properties tab

  • Go down to the "add a new property" form

  • In the Name field: enter 'allowed_page_types'

  • In the Type field: select 'lines'

  • Leave the Value field empty for now, and click 'add'. You should now have a new allowed_page_types property with space for several lines in the empty Value field.

  • Now, enter the page types that you want available into the Value field, one per line. Use the page_type ID's which you can see in a page's Properties tab in the ZMI or in ZWikiPage.py. As of 0.52 they are:

    rst
    stx
    html
    plaintext
    wwml
    moin
    

    This should give you: reStructured Text, Structured Text, HTML, plain text WikiWikiWeb markup, and MoinMoin markup. For a different selection, or to adjust the order in which they appear, alter the list accordingly.

  • Click "Save".

  • Go back to your wiki, and edit a page: the page types you chose should be available, identified by descriptive name. (Assuming you have 'Zwiki: Change page types' permission, of course).

Note: this applies only to the Zwiki editform, not the page types list in the page's ZMI Properties tab.

See also http://www.netvironments.org/laurazWiki/WikiPageTypes .

Customizing appearance

How do I edit the style sheets ?

ie. I'd like to make my links look different, and the body text another font, etc... (the body font can be changed with a span tag, but to change the links you need to access the CSS or the body tag itself....)

As of Zwiki 0.18, the default skins will use a stylesheet object named 'stylesheet' if present. Simply add a DTMLMethod or File with this id to your wiki folder, containing your style sheet. If you use a DTML method, include this line:

<dtml-call "RESPONSE.setHeader('Content-Type', 'text/css')">

How do I change my wiki's appearance ?

A zwiki page gets it's appearance from a PageTemplate named 'wikipage' (DTMLMethods? named 'standard_wiki_header' and 'standard_wiki_footer' are also supported, but deprecated). The other supported skin templates are: 'backlinks', 'contentspage', 'diffform', 'editform', 'subscribeform', 'recentchanges', 'searchwiki', 'useroptions'.

Zwiki normally provides built-in defaults for these; you can override them by creating an appropriately-named page template in the wiki folder (or above). To get started, copy the code from the corresponding default, which you'll find in ZWiki/skins/default/ on the filesystem (or "here":zwikidir/skins/default).

Inside a CMF or Plone site things work a little differently: the templates are kept in the portal_skins/zwiki_plone folder, and some of the names are slightly different (eg wikipage_view). To override one of these, just visit it in the ZMI and click Customize. This will install a copy you can edit in portal_skins/custom.

Here's an example, though it uses the old standard_wiki_header the same principle applies. This recipe assumes the reader has basic knowledge in Zope:

  • Go into the Zope Management Interface and change to your wiki folder

  • Select a Zope Object of type "DTML Method" to add

  • name it (ID and Title) 'standard_wiki_header'

  • use the botton "choose" to select the file 'standard_wiki_header.dtml' from your harddrive

  • press Button "Add"

  • edit the newly created standard_wiki_header: in the third line change:

    <TITLE><dtml-var "aq_parent.title"><dtml-var title_or_id></TITLE>
    

    by adding:

    <TITLE><dtml-var "aq_parent.title"><font color="FF0000"> - You are at: </FONT><dtml-var title_or_id></TITLE>
    

Now all of your wiki pages got a new title tag. Instead of showing "Your WikiWebs Name WikiName" in the title of the browser all wiki pages got "Your WikiWebs Name - You are at: WikiName".

How do I change the default icon on my Zwiki web ?

The default skins will make use of a 'site_logo' folder property, if present, where you can put a HTML snippet for your site logo.

You can also just create an Image object with id 'site_logo' in your wiki folder.

Or you can customize your skin, see above.

How do I change the background color of a page ?

The background color comes from the page's stylesheet, or from the BODY tag in the 'wikipage' skin template (custom or default). See above for information on customizing these.

What if you'd like to let users change background colors of individual pages ? Ideas:

  • Set the colour based on a special page property, and modify the editform to allow users to set that property (Tracker.py:changeProperties might help). (It would be great if a graphics program's color choosing dialog can be used to choose the color!)
  • Set the colour based on a special tag in the page text.

Why do I see could not render this at the top of the page ?

This happens when you have an old custom 'standard_wiki_header' (or 'standard_wiki_footer') DTMLMethod in (or above) your folder that's not compatible with your zwiki version. The easiest solution is to delete these and use the default skin.

The last edited by entry gets labeled with my Zope login name, not my wiki user name. Can I change this ?

Yes, an authenticated zope username takes precedence over the zwiki_username cookie. To change this you would need to alter usernameFrom() in ZWikiPage.py.

DTML scripting

Scripts embedded in wiki pages ? Isn't that a security problem ?

Yes, but in practice less of one than you think, for reasons both social and technical:

  • Zwiki is targetted at and used by primarily cooperative communities
  • Zope has a mature and robust security system which runs DTML scripts in a sandbox, and can be configured to arbitrarily limit the access privileges of scripts
  • The vigilant many can defend themselves from the destructive few
  • undo and backups

It's true that Zwiki is not yet widespread and so we can expect to see more instances of abuse than heretofore. The factors above should remain effective however.

When can I use DTML in wiki pages ?

When it's enabled by the wiki admin. You can find out if it's enabled with a test script such as:

<dtml-var ZopeTime>

Also with an up-to-date edit form, "DTML" will show up in the listed page types, or not.

How do I enable DTML in my wiki ?

For Zwiki 0.22 to 0.25, see the 0.22 ReleaseNotes. For 0.25 or greater, see the 0.25 ReleaseNotes. For older version of Zwiki, see "How do I change the list of allowed page types ?".

Where can I find a DTML snippet to do X ?

See the DTMLCookbook, http://zopewiki.org/DtmlCookbook , and http://zopelabs.com . Also peruse the dynamic pages on zwiki.org for examples - RecentChanges?, WikiBadges, FivePages?, etc. (use of a colorizing ExternalEditor is recommended to make these more readable). And of course you can try asking on #zwiki, DTMLCookbookDiscussion or GeneralDiscussion.

Miscellaneous

How do I edit this FAQ ?

Edit this page like any other (click edit or press alt-E). RestructuredText is used for formatting. Or, just post a comment and someone will merge it later.