Example: creating a wiki

Once Zwiki is installed on your server, you are ready to start your own wiki web. Your wiki will have the "standard" or "plone" appearance depending on where you put it - a zwiki web that's inside a CMF or Plone site will show the plone user interface.

You will need manager-level access to the ZMI or plone interface, respectively. You'll be able to move or reconfigure the wiki later, so don't worry about the details.

How to make a standard wiki

  1. open up your zope server's ZMI in another window, at any folder, eg the root: http://yoursite/manage
  2. in the Add menu, choose Add ZWiki
  3. enter the id of your wiki folder. A short lower-case word is a good choice, eg: 'wiki'.
  4. click create.

You should now be looking at the front page of a brand new "standard" wiki, eg: http://yoursite/wiki/FrontPage. The wiki contains a couple of default pages and dtml methods which you can see in the ZMI. It does not yet use a catalog.

How to make a plone wiki

  1. log in to your plone site as manager
  2. Go to plone_setup, and go to the page to install new products. Then install ZWiki.
  3. Now, go to the folder where you want to start your wiki, or make a new folder, and click the contents tab. Eg http://yourplonesite/folder_contents
  4. in the add menu, choose Wiki Page; click the add new item button
  5. change the Plone-generated page name to FrontPage. You can use any other name, but FrontPage is recognized as a default page for the folder without additional steps.
  6. press enter or click the save button.

You should now be looking at the front page of a new "plone" wiki, eg http://yourplonesite/FrontPage. The wiki contains one page and uses the plone site catalog.

Configuration topics

virtual hosting

You may want to give your wiki a url that's different from your zope server's. People usually do this with the apache webserver and zope's virtual host monster .

the wiki folder

You can start a wiki in any kind of folder, eg your root folder. If you think it may grow past several hundred pages, consider using a BTree? Folder. How To Migrate To A BTree Folder

A short lower-case name for the folder distinguishes it from pages and makes urls easier to type and remember.

initial content

Zwiki comes with a small set of default pages and dtml methods which are useful for jump-starting a new wiki. The Add ZWiki form in the ZMI installs these for you. Choose the basic option; current Zwiki's add form may show other options but this is probably a bug.

You can also start a wiki by creating a single wiki page in any folder. Inside a CMF/Plone site, this is the only way to do it. If you do this you can add the default pages later by visiting SOMEPAGE/setupPages, and you can add the dtml methods (recommended) by visiting SOMEPAGE/setupDtmlMethods.

default page

When you visit a wiki folder's url, you should be redirected by the index_html DTML method to the wiki's default page, which is usually named FrontPage. To use a different front page, set a property called "default_page" of type "string" on the folder. http://WIKI/manage_propertiesForm.

Plone wikis usually rely on Plone to do this automatically. You can edit Plone's list of default page names in one of the site properties.

fuzzy urls

When fuzzy urls are enabled, you don't have to remember complete or exact urls; Zwiki will do something sensible. Either it will correct the url and take you to that page, or it will offer to do a full-text search or create a new page with that name. See also FuzzyUrls.

This is enabled by the standard_error_message object, installed by default in standard wikis. To add it to a plone wiki, you must visit SOMEPAGE/setupDtmlMethods. Caveat: this doesn't entirely work in private wikis requiring authentication; see #1117.

security

Security covers a number of issues, including: not compromising your system's security (see dtml and fit); choosing who should see and edit your wiki and keeping others out (see access policy); defending content against vandals and spammers (see wiki management).

dynamic content - DTML, or not ?

Zwiki supports dynamic DTML code embedded in pages, in a relatively safe way. This is disabled by default and most people leave it off for security and simplicity reasons.

This is a unique and powerful feature, allowing rapid iterative development of useful wiki queries, custom form handlers, full-blown web apps etc. DTMLCookbook has some examples. A number of Zwiki features like RecentChanges?, user options, and the IssueTracker were prototyped as dynamic wiki content before being moved to the skin. The latter can still be installed as pages (for easier tweaking) by visiting SOMEPAGE/setupDtmlPages.

DTML and security

For public wikis allowing untrusted editors, such a feature would normally be a huge security hole. With Zwiki, it's possible to provide this feature with relative safety even in open wikis, thanks to Zope's security model. Why ?

  • DTML is restricted code which means it is not allowed to touch the filesystem or import arbitrary libraries. Qualification: if you have localfs or similar fs-publishing objects in your ZODB, it might be possible for DTML to access those parts of the filesystem.

  • DTML runs with at most the same permissions as the user running it. You will typically not permit untrusted users to view the ZMI, delete content outside the wiki folder, add users, change permissions etc., and this will be true for any DTML they run.

  • DTML also runs with at most the same permissions as the owner of the wiki page. So, to prevent trojan attacks (where an untrusted user adds malicious DTML to be executed next time a manager views the page) you can make sure your wiki pages are owned by a low-privileged user (like "nobody"); then DTML will be restricted regardless of who runs it.

    Zwiki pages should acquire their owner from the wiki folder, so in theory you should just set the wiki folder's owner (how-to somewhere ?) and you will be all set. In practice this has not been tested recently so please re-test and update this page before relying on this.

There's no doubt that enabling DTML creates risk. Even if you are careful to restrict DTML's powers as above, denial of service attacks are probably easy to arrange. If you aren't, malicious DTML could perhaps: delete your entire zodb contents; spam the zodb history to make undo difficult; quietly add new manager accounts; add a localfs object to get access to any file your zope's effective user can access, eg /etc/passwd; etc.

So if you choose to run a wide-open DTML-enabled wiki: consider your risk sensitivity, use your own judgement, configure carefully, keep backups, and keep an eye on what's happening with your site. In intranets or public wikis with controlled editing, malicious DTML isn't a problem, but remember to review your policy if your wiki later becomes more open.

To enable DTML in a wiki (or in a single page) add a true boolean allow_dtml property in the ZMI properties tab. Conversely, if you want to make sure no wikis on your server can ever enable DTML, add a property named no_dtml, any type and value, to eg the root folder.

If you're using reStructured Text, you have to embed the DTML tags in raw blocks (starting with .. raw:: html).

access policy

You'll need to decide who is allowed to do what on your wiki, and set zope permissions accordingly. For example, your wiki may be completely open to all visitors, or it may be strictly private just for you, or anything in between.

The basic functions to consider are: view, search, rating, comments, edits, reparent, rename, delete, upload, external edit. Each of these is controlled by one or more permissions which you set in the wiki folder's Security tab in the ZMI. See QuickReference for a list of these.

membership

Membership means allowing visitors to register themselves, or to be registered by an admin, so that they have an account on the site, which remembers their password and site preferences and usually grants them more access permissions. There are some ZopeProducts which help with this. The easiest way to get this is to put your wiki inside a Plone site. See also ZopeWiki:CMF , ZopeWiki:CPS, ZopeWiki:GroupUserFolder and ZopeWiki:ExUserFolder .

scalable searching - catalog, or not ?

ZCatalog is Zope's indexing feature. Zwiki can use it to provide faster and more powerful searches, especially with larger wikis. It is not enabled by default in a standard zwiki, but probably should be. It is enabled by default in a plone zwiki, but not with all the fields that Zwiki requires for best performance. So in either case, you should probably do this at some point after creating a new wiki: visit http://yoursite/wiki/FrontPage/setupCatalog . This makes sure a catalog exists and that it has all the necessary fields for best wiki performance. It's harmless to run this more than once. Afterward, you should notice the following changes:

  • recent changes shows several "since" buttons
  • the search form's behaviour is slightly more high-level than before -

does word and boolean matching rather than character matching.

  • if your wiki contains many pages, recent changes, search and general

operations should be much faster and use less memory

The details of how search matches results depend on what text index is configured in your catalog. ZCTextIndex seems to be a good choice.

subtopics

When a page has subtopics (child pages - see the page hierarchy feature), they are automatically listed after the main page content, before any comments. This helps to make the content of the wiki more visible, and also makes manual links less necessary.

If you want to disable this feature, add a boolean property named show_subtopics to the wiki folder and leave the checkbox empty.

From 0.42: Also, you may select an alternate template for displaying the subtopics. See customizing appearance for details.

You might use DTML to display the subtopics in a special way, eg in a different location (dtml-var subtopics). If you do, Zwiki will notice this and avoid displaying the subtopics twice.

page types

By default Zwiki allows users to choose a page's type in the edit form, which determines how the source text will be rendered in a web browser. Generally this has the effect of changing the text formatting rules . You can disallow this and hide the field by denying Zwiki: Change page types permission.

You can restrict which page types are permitted by setting a property on the wiki folder. Go to the folder's Properties tab in the ZMI and add a new lines property named allowed_page_types. Enter the short names of the page types you want to allow, one per line. Eg:

stx
rst
html

The available page types are: stx, rst, moin, wwml, html and plaintext. These are described at the link above.

Whichever type comes first will be the default for new pages. To set the default page type you must create the allowed_page_types property and set your default type to the first in the list. If you include only one type, that type will always be used. In this way you can have a HTML-only or rst-only wiki for example.

Note: this property is not upgraded automatically, so if you have had it for a long time you may have outdated page type names there which need to be replaced.

file and image uploads

On the Security tab of the ZMI (http://yourwiki.org/manage) the permision Add Documents, Images, and Files determines who will be able to upload files and images. if available, there will be a Upload a file or image field at the bottom of the edit form.

internationalisation

  • In page text: all international characters should work in page text.
  • In text formatting rules: some of the text formatting systems support international characters, some don't. Set your locale in zope.conf . For Structured Text try the StructuredTextUnicodePatch also.
  • In page names and wiki links: all international characters should work in bracketed wiki links or when using the page management form. Bare wiki links will recogize the upper- and lower-case characters defined by the locale configured in zope.conf, or when no locale is configured (the default), latin-1 plus some others.
  • In the skin: if you want users to see the zwiki skin in their browser's preferred language, install PlacelessTranslationService .

wysiwyg editing

If you install the Epoz product, pages of type HTML will offer a WYSIWYG edit form to users with Firefox and other mozilla-based browsers, IE, and perhaps some other modern browsers. Users with older browsers will see the usual text area form.

This is a useful feature to offer, especially to users who may not have the time or willingness to learn text formatting rules. It has the great advantage of not requiring them to install anything. It's also the easiest way to edit tables in a zwiki page.

external edit

If you install the ExternalEditor product on your zope server, wiki users will see a pencil icon which allows them to edit pages with any text-editing application of their choice (after they install a helper script). HowToEnableExternalEditorOnYourSite describes how to do this.

This is a very worthwhile feature to offer, as it makes large pages much more convenient to edit, using Emacs, Gedit, Notepad or whatever. Or for HTML pages, tools like Mozilla Composer, FrontPage, or Dreamweaver can be used.

page rating

Zwiki provides a simple page rating feature. To turn it on or off, set the Zwiki: rate pages permission. When page rating is enabled, users will see a simple six-button rating form at top right (five stars plus invisible -1 button). Pages start out with a rating of one star (average); as time goes on, a page's rating is the average of all user votes. Each user with a login or a username cookie gets one vote per page, which can be changed at any time. Anonymous users share a single vote at present, so anonymous votes can be changed by the next visitor and aren't all that useful.

mail out

It's easy to configure your wiki to send out mail when there is a comment or edit. Usually, just add a string property named mail_replyto to the wiki folder's Properties tab in the ZMI, containing a real or dummy email address. See HowToSetUpMailOut for full details.

This allows users to monitor pages of interest or the whole wiki without having to check recent changes all the time. It's especially useful for wikis with intermittent activity.

mail in

If you have system administrator access, you can set up a special email address that will allow email to be sent to the wiki. Combined with mail out, this allows people to participate in wiki discussions using only their mail reader, and to quickly forward content of interest to the wiki. The subject header is used to select the target page. See HowToSetUpMailIn for more about this.

See mail for more about Zwiki's mail integration.

RSS feeds

Simple RSS 2.0 feeds for your wiki are available at ANYPAGE/changes_rss and ANYPAGE/pages_rss . These list the most recently modified and most recently created pages respectively. See the notes at RSS for more.

issue tracker

With a few enhancements, a zwiki can serve as a pretty good issue tracker. Issues are represented by wiki pages whose names begin with #number, and which have some extra issue fields. Special search forms are provided for browsing and filtering issues. Also, you can just write #number to link to an issue page.

Why is this useful ? You don't need a dedicated wiki for issue tracking; you can intermix issues with ordinary pages, and the usual zwiki functions work normally - editing, mail-in/mail-out, etc. This means you can quickly add a simple, usable issue tracking system to your project without having to learn anything new and without fragmenting knowledge across separate "docs" and "bug tracker" sites.

To set this up in your wiki, visit SOMEPAGE/setupTracker once. This adds some folder properties, configures the wiki catalog and creates an initial test issue. It's harmless to do this more than once, eg if you suspect your issue tracker configuration is out of date.

You'll be left looking at the basic issuetracker form, which gives an overview of current issues and allows you to add new ones. You can return here by clicking the "issues" link, which appears as long as there is at least one issue page in the wiki. Or, use the alt-t [access key]? (t for tracker). You can also access the "filter issues" and "issue browser" forms from here.

In CMF/Plone the "issues" link appears as an "issue tracker" document action link - if not, you may need to reinstall/upgrade the Zwiki product in Plone Setup.

setupTracker installs several issue_ properties on the wiki folder, which you can change in the ZMI to customize your categories, severities, statuses, and colours. There's no easy way to add additional issue properties right now, but see the IssueTrackerOwnerAndDueDate patch. Also remember you can use adhoc techniques such as WikiBadges, page hierarchy or page naming conventions to annotate your issues.

If you have a DTML-enabled wiki and prefer to install the more tweakable IssueTracker/FilterIssues/IssueBrowser pages instead of the issuetracker/filterissues/issuebrowser page templates (as on zwiki.org), visit SOMEPAGE/setupTracker?pages=1.

You can set up a special mail-in address that will create issues, as follows:

  • first, get mail-in working (see above)
  • then, set up an extra alias for the mailin script, of the form *bugs@domain or *tracker@domain. Ie, the alias must end with either "bugs" or "tracker".

fit

fit is a testing tool which reads test specifications (input data and expected results) in tabular form, runs the tests (by calling the test code) and colour-codes the table cells to indicate results. When installed together with Zwiki, you can develop and run tests in wiki pages. See ZwikiAndFit for more.

purple numbers

this feature has been mothballed, update

PurpleNumbers are small purple numbers automatically added to each paragraph of a page for easier referencing. There is a partial implementation of this in Zwiki which may be useful to some people. To enable it, go to the wiki folder's Properties tab in the ZMI and add a new boolean property named use_purple_numbers, checked. See PurpleNumbers for more.

If you change or remove this property later, you won't see the effect until pages have been re-rendered. You can force this by making an edit, by visiting EACHPAGE/clearCache, or by visiting SOMEPAGE/upgradeAll.

latex

You can make your wiki render latex markup by installing the LatexWiki add-on product.

axiom, reduce, graphviz.

Axiom and Reduce are powerful computer algebra systems which can be integrated with your wiki, so that you can write and solve mathematical problems within wiki pages. The GraphViz graph drawing toolkit has also been integrated, so that you can generate arbitrary graph diagrams. See MathAction.

Configuration tools

A list of the tools and places you might use for configuration:

  • ZMI
  • contents tab
  • properties tab
  • security tab
  • undo tab
  • Plone/CMF UI
  • plone setup
  • folder contents
  • portal_skins
  • API methods
  • /zwiki_version
  • /setupCatalog
  • /setupTracker
  • /setupDtmlMethods
  • /setupPages
  • /updatecontents
  • /upgradeAll

Questions and answers

I get a "missing site" error, if I type /setupCatalog after the root folder URL or nothing happens if I type it after FrontPage.
The url is not .../wikifolder/setupCatalog; use http://site/wikifolder/FrontPage/setupCatalog. (Any page will do.) At present this doesn't give any visible feedback, it just completes without error. You can verify that it worked by visiting .../FrontPage/hasCatalog; it will print True. Also you'll see more ...options in recent changes.

Recap

You've learned

  • how to create a wiki
  • how to control the url that users will see
  • how to control access to the wiki
  • what a wiki catalog is and whether you want one
  • what a DTML-enabled wiki is and whether you want one
  • how to configure the default page
  • how to control subtopics display
  • how to choose the available page types
  • how to choose the wiki-linking syntaxes
  • what internationalisation configuration might be needed
  • how to enable wysiwyg and external application editing
  • how page rating works
  • how to configure mail-out and mail-in
  • where to find an RSS feed for your wiki
  • how to to support issue tracking in your wiki
  • how to enable support for other features such as fit, purple numbers, latex, axiom, graphviz

Next is customizing appearance.