An Introduction to JSPWiki

By Neil Youngman

The good, the bad, and the wiki?

Wikis

In this article I explain what a Wiki is and how it is used, for those readers who haven't come across Wikis before. I discuss why I chose JSPWiki from the hundreds of Wikis out there, and I explain how I set it up.

Wiki is a short form of WikiWikiWeb. Wikis are collaboratively authored Web sites that are created and edited by their users. Wikis provide a quick and simple way of generating a set of linked Web pages. The emphasis is on collaboration and simplicity. Anyone can contribute and it doesn't take long to get started.

According to "One-Minute Wiki" WikiWiki is Hawaiian and means "quick".

Wikis can be used almost like a bulletin board to share information and ask questions, but there is no concept of boards or thread, just a set of interlinked pages.

Collaborative authoring means that pages aren't owned by any one author. If you spot a mistake on a page, you can correct it there and then and of course other people can correct your pages.

There are all sorts of uses for Wikis. They can be used anywhere you need to share information among a large group of people. I have seen them used for informal documentation within a development project, question and answer sessions and even a collaboratively written encyclopedia. I also sometimes keep a set of notes on my Wiki, allowing me to access them easily from multiple locations and share them with anyone else that needs the same information.

Typically there is an edit option on each page, which allows a user to alter the page and a simple convention for creating links to another page. To create a new page, you just create a link and that link allows you to edit the page.

You don't have to learn HTML to create and edit Wiki pages. Instead, there are a set of simple conventions, e.g., in JSPWiki, you create a new link simply by enclosing a phrase in square brackets.

    [New Link]

Unfortunately, these conventions are not standardised, so, if you use more than one Wiki, you may have to learn more than one set of formatting conventions.

To try out a Wiki why not go to the JSPWiki Sandbox or take a look at Wikipedia, a collaboratively authored encyclopedia.

Why JSPWiki?

When I wanted to set up a Wiki for myself, I looked around and I found that there are hundreds of WikiClones to choose from. Many of them are still pre-release and I wanted something that would be stable, reliable, easy to install, setup and use. JSPWiki provides all of this plus authentication, version control, attachments, and plugins.

Ease Of Use

Wikis are designed for ease of use, so this should not be a major issue with any Wiki. The main differences in ease of use come from choosing a mature and stable Wiki with simple formating rules.

JSPWiki's mark up language seems relatively clear and simple to me. Links are created simply by putting square brackets around the link name. Headers can be created by putting an exclamation mark at the start of the line and tables by dividing up the text with with pipe characters. So, for example:

!!! This is an example

which links to [The Linux Gazette|http://linuxgazette.net]

and shows 

! a table

|plate|knife|fork
|mat|glass|cup

comes out looking like

This is an example

which links to The Linux Gazette

and shows

a table

plate	knife	fork
mat	glass	cup

JSPWiki can also be configured to allow people to enter HTML, but this is strongly discouraged as insecure.

Installation and Configuration

Ease of installation was a big plus for JSPWiki. If you have a suitable Java servlet container already installed, installation on Red Hat is very simple. Jakarta Tomcat was set up on the machine I wanted to use. Installation was a simple matter of creating a directory called mywiki in the Tomcat webapps directory, unpacking JSPWiki.war and JSPWiki-samplepages.zip in that directory, editing the configuration file, and restarting Tomcat.

    mkdir /usr/local/jakarta-tomcat-5.0.19/webapps/mywiki
    pushd /usr/local/jakarta-tomcat-5.0.19/webapps/mywiki
    /usr/local/j2sdk1.4.2_04/bin/jar xvf JSPWiki.war
    unzip ~neily/JSPWiki/JSPWiki-samplepages.zip
    emacs -nw /usr/local/jakarta-tomcat-5.0.19/webapps/mywiki/WEB-INF/jspwiki.properties
    mkdir /usr/local/jakarta-tomcat-5.0.19/webapps/mywiki/attached
    /usr/local/jakarta-tomcat-5.0.19/bin/catalina.sh start

The configuration file is webapps/mywiki/WEB-INF/jspwiki.properties; this is well commented, so configuration is simple.

The configuration was a simple matter of changing 3 or 4 settings in jspwiki.properties. The comments in this file are generally pretty clear and most of the settings can be left unchanged. Properties you should set are jspwiki.applicationName, jspwiki.pageProvider, jspwiki.fileSystemProvider.pageDir, jspwiki.attachmentProvider, jspwiki.basicAttachmentProvider.storageDir,

Installation on other Linux versions may not be as simple. I later installed JSPWiki on a Debian machine, and found that, although installation with apt-get was very simple, it wouldn't run outside the default directory without more configuration.

To get it to work on Debian in a directory called mywiki, I had to create the file /var/lib/tomcat4/webapps/mywiki.xml, which was an edited copy of /var/lib/tomcat4/webapps/jspwiki.xml.

Authentication

JSPWiki provides a simple authentication mechanism. This can be supplemented by authentication methods available from the servlet container under which it runs.

As I was setting up a Wiki on a small private network, authentication was unlikely to be an issue, but choosing a Wiki with support for authentication allows it to be added later if the Wiki is abused or we wish to set up an external Wiki.

Setting up basic authentication in JSPWiki should be simple. Add the lines

  jspwiki.authenticator = FileAuthenticator
  jspwiki.fileAuthenticator.fileName = /path/to/passwords.txt

and create the passwords.txt file, which will look something like

  # The format is simply username = password
  # No encryption is used currently.
  # Comments are allowed; prepend with hash.
  user1 = pass1
  user2 = pass2

If you need more sophisticated authorisation look at the Authorization And Authentication HOWTO and the Auth Plugin. If you still haven't found anything that meets your requirements, you could consider writing your own Authenticator or using the authentication provided by your servlet container, e.g., Tomcat.

Version Control

Version control is a useful feature, which stores each version of a page as it is updated. This allows you to restore pages which are lost or damaged. JSPWiki supports RCS-based version control and also implements its own mechanism as an alternative for platforms without RCS.

This does not appear to be a well documented feature, but is fairly easy to use. Every time you save a change to a page, a new version is stored. There is "more info" link at the bottom of each page, which provides a link to previous versions of the page. You can select any previous version, which is then displayed, with a message explaining that it is not the current version of the page and a "restore this page" link.

Version control is particularly important on a publicly accessible Wiki. These can be defaced with advertising and worse. Version control allows you to easily revert to an undamaged page.

To use RCS-based version control set jspwiki.pageProvider = RCSFileProvider and jspwiki.fileSystemProvider.pageDir = /path/to/dir/for/RCS/files

Attachments

JSPWiki allows you to attach files to a page. This can be a good mechanism for sharing documents. If you refer to a large document, or a document in a non-text format, attaching it to the page ensures that it is accessible to your readers.

To use attachments set jspwiki.attachmentProvider = BasicAttachmentProvider and jspwiki.basicAttachmentProvider.storageDir = /path/to/dir/for/attached/files.

Plugins

JSPWiki can be extended with the use of plugins. JSPWiki plugins are written in Java, like JSPWiki itself. If you don't want to write your own, take a look at the plugins that have already been contributed.

Using JSPWiki

Using JSPWiki is dead simple. Once you've got it installed and setup with all the features you want to use, just go to the main page, set up some links to new pages, and edit them. Voila, you have a Wiki. Start off with a page describing who the Wiki is for and what you want to achieve with it, then let your imagination run riot.

 

---

Neil is a programmer, specialising in C++ on Unix and Linux. He has degrees in Computer science and Next Generation Computing.

Neil has worked on a wide range of systems from the control system for the British Gas national grid to video servers for the Home Choice video on demand service. He first programmed computers in 1980 with his school General Studies class, which was allowed access to a mainframe at The National Institute of Oceanography, programmed in Fortran on punch cards.

A computer science degree followed at Queen Mary College, London, then Neil worked for Logica for 3 years before taking an MSc in New Generation Computing at Exeter University.

The next 5 years saw Neil researching parallel simulation algorithms at the Royal Signals and Radar Establishment, initially on transputers and subsequently on SPARC based parallel systems. Since leaving RSRE, Neil has mostly worked freelance and has worked on financial data feeds, video servers and virus scanning proxies.

Neil first used Unix at college in 1982 and started working on Linux in 1996.

As of May 2004, Neil is working for Wirefast a global messaging company.

Outside of computing, Neil is into motor sport, particularly Formula 1, the World Rally Championship and the British Touring Car Championship. He doesn't race himself. If you've seen Neil's driving, you'll understand why.