Dr. Dobb's is part of the Informa Tech Division of Informa PLC

This site is operated by a business or businesses owned by Informa PLC and all copyright resides with them. Informa PLC's registered office is 5 Howick Place, London SW1P 1WG. Registered in England and Wales. Number 8860726.

Channels ▼

Corporate Collaboration (Web Techniques, Dec 2000)

Corporate Collaboration (Web Techniques, Dec 2000)

Corporate Collaboration

With TWiki

By Peter Thoeny

We take collaboration on the Internet for granted. Email is the most ubiquitous method we use to share ideas with others. There are also mailing lists, Usenet groups, bulletin boards, and proprietary systems like Lotus Notes. Each one has its purpose, and each one has strengths and weaknesses.

The WikiWiki system offers a new method for collaboration. Programmer Ward Cunningham adopted WikiWiki (from the Hawaiian term for "quick") as the title of an experiment he conducted for the Portland Pattern Repository. In his words, WikiWiki is a set of informational Web pages "that are open and free for anyone to edit as they wish. They're stored in a database and managed using some Perl CGI scripts. The system creates cross-reference hyperlinks between pages automagically." Cunningham's idea was to create a Web site on which anybody could create and change Web pages via an ordinary Web browser. Such an idea seems chaotic at first, but the system works amazingly well.

Cunningham's original WikiWiki Web has inspired a whole avalanche of clones. A number of these clones are Open Source projects, including TWiki, which I partially developed at Wind River (see "TWiki Deployment at Wind River"). TWiki is especially useful for corporate intranets. While each clone has practical extensions, each one also adheres to the goals of the original system.


Cunningham designed the original WikiWiki system with four properties in mind. First, as in Tim Berners Lee's original vision of a read-write Web, he wanted the system's users to be able to edit any page on the site using an ordinary Web browser. Every page in a WikiWiki system has an edit link (or an edit button). Selecting the link lets you edit the page via an HTML form containing the page code in a text box. To change a page, you simply alter the text in the box and submit the form. Because the form is created in regular HTML, you don't need special software to interact with it.

The second property of the system stipulates that all Web pages should be created and served on the fly. When a user follows a link to a WikiWiki page, he or she sees a dynamically generated page. Serving pages this way offers several advantages over serving static pages. It assures that page content remains fresh and that the system can generate accurate links between pages. Although dynamic pages increase the load on the Web server, experience shows that systems built with Apache's mod_perl module can support up to several hundred simultaneous users.

The third property requires pages to be linked dynamically with WikiWords. When creating a link to a new page in WikiWiki, users first specify a bit of text as a WikiWord. WikiWords are capitalized words, run together, for example:


Note that there's a question mark at the end of the word. The question mark is a link. When selecting the link, the WikiWiki system lets you create a new page called CollaborationTools. The WikiWord in the original page is now a link to the newly created page, rendered as CollaborationTools. In this way, you can easily create a hyperlinked web of pages.

Listing 1 shows a simplified part of the TWiki Perl source that links WikiWords. (The TWiki source can be downloaded from the TWiki Web site. See "Online.") The getRenderedVersion subroutine in Listing 1 renders the page. The code shows only the automatic link mechanism of WikiWords. The pattern


is considered a WikiWord, but only if it's preceded by white space, a parenthesis, or an asterisk. The internalLink subroutine handles each identified WikiWord and generates the correct HTML.

The final property of a WikiWiki system is the simplified markup language. Because WikiWiki systems use HTML forms to edit pages, users must edit pages in a non-WYSIWYG manner. Nevertheless, it's possible to create rich pages with WikiWiki's simplified markup language.

Example 1 shows several instances of the TWiki markup; its syntax varies somewhat between clones.

The TWiki Way

Because TWiki targets the corporate intranet world, it has several features not found in other WikiWiki clones. For instance, it's important to authenticate users and control pages across versions in a business environment. To do this, TWiki uses basic authentication or SSL, which is compatible with all popular browsers.

A user must first register at the TWiki site to create an account. Then, before the user can edit a page, the browser prompts him or her for a username and password. TWiki logs all changes to Web pages, so you always know who changed what, and when. TWiki uses the popular RCS system for version control. Each time a user saves a page, TWiki checks it into a repository file. Links displayed at the bottom of each page provide access to document versions and differences between versions (see Figure 1). When you follow a right arrow (>) link you're shown the difference between two versions, as demonstrated in Figure 2.

Because several groups within a corporation may have different collaboration needs, each group can have its own collaboration space called a TWiki Web. Each Web has its own group-specific functions like search or view/edit statistics. This program specificity ensures that collaboration groups don't step on each other's toes.

It should be noted that while a number of advanced collaboration systems use complex URLs, TWiki keeps them simple and usable. For instance, a normal TWiki URL is written:


The script being run is view. The name of this particular TWiki Web is Know. And the name of the page being viewed is WebHome. Other usability features include visual clues on the pages themselves. Each page bears the name of the current TWiki Web. In Figure 3, this information is available in the TWiki.Know.WebHome line. The list of other available Webs is shown on the right side.

TWiki displays a list of the most recently altered pages—this is an easy way to find out what's new in a TWiki Web. A TWiki subscription service can also email you this list. Because most things in WikiWiki are accomplished by modifying a Web page, users subscribe to email lists by entering their addresses into the WebNotify page using the following format:

* Main.TimBernersLee - [email protected]

The text preceding the email address specifies a link to the user's home page; in this case, it's a link to the TimBernersLee page in the Main Web.

When configured properly, the cron utility regularly executes the mailnotify script, which in turn calls the getEmailNotifyList subroutine (see Listing 2). This subroutine parses the WebNotify page and creates a space-delimited list of email addresses. The script first performs a grep on the WebNotify page, looking for lines with email addresses. The foreach loop extracts each email address and adds it to the list.

User-Level Enhancements

A popular TWiki feature is the ability to attach files to Web pages in a method that's similar to email attachments. Following the Attach link shows a form where you can open a File dialog box in your Web browser. The file you select from the box is sent to the server, and then a FileAttachment table appears at the end of the page to notify other users of its presence (see Figure 4).

On the technical side, the HTML file input tag makes the upload possible. This type of input tag is rendered by the browser as a text field and a browse button. The user can enter a filename in the input field, or use the browse button to select it graphically. The CGI.pm library makes it easy to accept the uploaded file and store it in a temporary location.

Listing 3 shows the file attachment code used in TWiki. The script assigns the filename to the $tmpFilename variable. After making sure the file isn't empty, the script strips the path from the filename and saves the file to the desired location.

TWiki also relies on file attachments to insert inline images into Web pages: Upload a JPEG or GIF file and the image will display on the page. This is a powerful and intuitive method of managing files. When TWiki is used as a product knowledge base—for instance, in an Open Source project—users can attach product revisions and patches directly to the page describing the issue. This system is easier to maintain than one that works by placing a patch on an FTP site, because the problem description and patches can be managed in the same location; also you don't have to worry about broken links.


Another feature users will like is the ability to use variables. TWiki parses each variable and replaces it with its value when the user views a page. For example, you can insert the name of the current TWiki Web with the %WEB% variable, or the current username with the %USERNAME% variable. Server Side Includes (SSIs) can be initiated with the %INCLUDE{page}% expression.

You can even perform inline searches dynamically with an expression similar to %SEARCH{food}%. These searches can show a list of pages within a page that logically belong together. For example, you can create a page about XHTML that includes introductory text, related links, and a dynamically generated list of all pages containing the word XHTML.


The variables can be used in templates for building Web pages. This format separates the presentation from the Perl script and lets anyone who knows HTML modify the page design easily. Consider Listing 4, which shows a simple template used by the view script. TWiki scripts automatically substitute values for placeholder variables. The %TOPIC% variable is replaced with the page name, just as the %TEXT% variable is replaced with the body text. This layout means users can change the look of the page without modifying the Perl source. In this way, each TWiki Web can have its own template files.

Category Tables

The last major enhancement distinguishing the current TWiki version from other WikiWiki clones is the optional category table. Category tables let you add more structure to a site's content. Figure 5 shows the form for a sample category table that appears below the text area when you edit a page. In this example, the category table implements a knowledge base for a fictitious customer support service. You can classify a page—which is a knowledge base entry—in one of several categories, such as NoDisclosure, which means the document isn't to be disclosed outside the company, or PublicFAQ, which specifies the document is an open FAQ on the company Web site. Note that in this example, the knowledge base entry is categorized by the operating system specified. Of course, on your own Web you can create any categories that apply to your particular project.

Further processing is possible based on the category table. For example, you could program the system to automatically publish PublicFAQ entries to the company Web site. The category table is defined by the twikicatitems.tmpl template file (see Listing 5).

Category tables and inline searches work well together when you need to implement a simple workflow system. For example, the TWiki development team itself uses this sort of system to handle new features. Pages can appear in one or more stages: new feature requests, status of features under construction, or completed requests. As the request progresses, the page containing information about it changes categories to reflect its current status. Index pages can then use the inline search feature to locate all pages of a certain status.

The New Collaboration

Unlike many traditional collaboration tools, the WikiWiki system is flexible, powerful, and easy to use (see Table 1). Yet, some of WikiWiki's ideas for open, shared environments may not be appropriate for corporate environments. TWiki solves these problems by providing for user accountability and version control. Because the Perl source for TWiki is available under the GNU Public License, corporate technology departments can modify TWiki as needed. (The main TWiki site has a list of many sites using customized TWiki installations.)

TWiki can help you build dynamic intranet Web sites, knowledge base systems, document management systems, and even bulletin board Web sites. Anyone experienced with Perl can understand the source and change it if necessary. To make upgrades easier, the local configuration file contains functions to which you may add custom rendering and tag-interpreting code. This lets a user easily propagate custom changes when upgrading to a new TWiki version.

(Get the source code for this article here.)

Peter is a software development manager for Wind River and the author of TWiki. Contact him at [email protected] and www.thoeny.com/peter.

Related Reading

More Insights

Currently we allow the following HTML tags in comments:

Single tags

These tags can be used alone and don't need an ending tag.

<br> Defines a single line break

<hr> Defines a horizontal line

Matching tags

These require an ending tag - e.g. <i>italic text</i>

<a> Defines an anchor

<b> Defines bold text

<big> Defines big text

<blockquote> Defines a long quotation

<caption> Defines a table caption

<cite> Defines a citation

<code> Defines computer code text

<em> Defines emphasized text

<fieldset> Defines a border around elements in a form

<h1> This is heading 1

<h2> This is heading 2

<h3> This is heading 3

<h4> This is heading 4

<h5> This is heading 5

<h6> This is heading 6

<i> Defines italic text

<p> Defines a paragraph

<pre> Defines preformatted text

<q> Defines a short quotation

<samp> Defines sample computer code text

<small> Defines small text

<span> Defines a section in a document

<s> Defines strikethrough text

<strike> Defines strikethrough text

<strong> Defines strong text

<sub> Defines subscripted text

<sup> Defines superscripted text

<u> Defines underlined text

Dr. Dobb's encourages readers to engage in spirited, healthy debate, including taking us to task. However, Dr. Dobb's moderates all comments posted to our site, and reserves the right to modify or remove any content that it determines to be derogatory, offensive, inflammatory, vulgar, irrelevant/off-topic, racist or obvious marketing or spam. Dr. Dobb's further reserves the right to disable the profile of any commenter participating in said activities.

Disqus Tips To upload an avatar photo, first complete your Disqus profile. | View the list of supported HTML tags you can use to style comments. | Please read our commenting policy.