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. :)
- Using Zwiki
- How do I edit with an external editor ?
- How do I edit via FTP ?
- How do I edit via webDAV ?
- I can't edit via external editor, ftp or webdav - is there some other way I can use a real editor ?
- How do I edit with Emacs ?
- How do I upload a file ?
- How do I rename a page ?
- How do I delete a page ?
- What is the page management form ?
- Zope/Zwiki is inserting paragraph tags into my document, destroying the formatting. How do I fix this ?
- How do I get a left and right square bracket to display properly ?
- How can I discuss a WikiBadge without showing up in its backlinks ?
- I'm starting a new wiki - how can I install the default pages now that Add Wiki Folder is gone ?
- How can I use Kupu with Zwiki pages ?
- How long can pages grow, and how do you know when to archive ?
- Page hierarchy
- Mail subscription
- Issue tracking
- Installing Zwiki
- What are all the special urls available, like /src, /setupPages, /upgradeAll etc. ?
- How do I restrict access to my wiki ? Or just to certain features like editing ?
- How do I make the edit link bring up a login form ?
- How to allow member registration, other than using Plone ?
- How does Zwiki handle page ids and titles ?
- Why don't fuzzy links work on my site ?
- What are the Zwiki permissions ?
- Ok, how do I set up a login form ?
- How do I allow people to register themselves ?
- Does Zwiki use a catalog ?
- How does a zwiki find it's catalog, with multiple catalogs, acquisition, Plone ?
- My catalog (recent changes, search results, hierarchy) seems confused. How do I rebuild it ?
- Help! I get a UnicodeDecodeError when I enter UTF-8 Unicode characters in Restructured Text pages!
- How do I change the list of allowed page types in the edit form ?
- Customizing appearance
- How do I edit the style sheets ?
- How do I change my wiki's appearance ?
- How do I change the default icon on my Zwiki web ?
- How do I change the background color of a page ?
- Why do I see could not render this at the top of the page ?
- The last edited by entry gets labeled with my Zope login name, not my wiki user name. Can I change this ?
- DTML scripting
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.
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.
See the list of features on FrontPage. Old: ZwikiStrengths, ZwikiWeaknesses.
At http://wikimatrix.org you can do a rough comparison of Zwiki against other wiki engines.
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.
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.
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.
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).
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.
Try opening the url of one of your pages, or http://zwiki.org/SandBox , with a webdav-aware editor. Did it work ?
- the w3m, w3m-el and lynx browsers (and eventually others, presumably) allow any editor to be configured for editing text areas.
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.
Turning on html-mode gives some useful highlighting. Eg you could:(add-to-list 'auto-mode-alist '("wikiserver:/" . html-mode))
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.
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).
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?).
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.
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
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]
From 0.23 you should be able to call the /setupPages method to install these (requires 'Manage properties' permission).
(eg Discussion pages). The largest page on this wiki is about 120K. Pages can grow until one of two things happens:
- 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.
- 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.
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.
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.
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.
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.
Start at http://zope.org/Products , or use your platform's package installation facility. Zope is cross-platform and pretty easy to install.
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.
Sure, Zwiki runs anywhere Zope runs. See Installing for tips.
clearCache upgradeAll reindex_object backlinks comment diff map create edit editform reparent catalogId lastEditTime subscribeform text pages pageIds wikilink stxToHtml zwiki_versionmailin fixprops cmf_install_zwiki view_source print
Or they might be coming from your CMF/Plone skin, eg:wikipage_view recentchanges wikinav_portlet
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.
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
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().
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.
The Plone/CMF solution above is easiest, ExUserFolder also has support for this.
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.
Zwiki looks for a catalog named Catalog in the wiki folder, or a portal_catalog in the wiki folder or above.
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.)
Edit your zope.conf and set both rest-input-encoding and rest-output-encoding to utf-8.
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.
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.
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')">
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".
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.
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.
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.
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 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.
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 ?".
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.