Software Garden wikiCalc® Program:
wikiCalc Architecture
The wikiCalc program has a variety of architectural characteristics that may be different than other programs with which you are familiar. This page describes some of those characteristics.

wikiCalc flying bird logo

wikiCalc can run either client-side or server-side. In both cases the operation of the product is accomplished through a normal web browser. When run locally (client-side), the browser connects to the wikiCalc program running on the same machine. (wikiCalc can communicate locally through HTML and HTTP which is understood by the browser -- it does not need a web server on your computer and does not allow browsers on other computers to access it.) When run remotely (server-side), the browser connects over the Internet to a normal web server which then executes wikiCalc as a normal CGI program (that is, program code running with the web server). In both cases, wikiCalc stores information about the pages and other settings on the same machine on which it is running so that it can always continue from where you left off. In both cases, when you "publish" an update to a page, wikiCalc connects to the final web server system to upload an updated copy of the HTML file that makes up the page to be served to readers. It also saves a data file on the server system with the details needed to do further editing.

Here is a diagram of using it with local (client-side) execution:

Client-side diagram

One of the advantages to running locally is that you don't need to install wikiCalc on a web server. Most people do not know how to do such an installation and many hosting systems do not support running your own code. Another advantage is that wikiCalc communicates more quickly with your browser while editing since, among other reasons, it doesn't have to connect over the Internet. In addition, while editing, you don't need to be connected to the Internet.

A major disadvantage of running locally is that you must have wikiCalc installed on your local computer and properly configured. This is normally not a problem if you always edit from the same computer, but if you want to use different computers for editing, especially ones on which you are not allowed to install any programs, then it is a problem.

Here is a diagram of using wikiCalc with remote (server-side) execution:

Server-side diagram

A major advantage of running wikiCalc remotely is that you can use it from almost any computer with a modern browser and an Internet connection. Disadvantages include the fact the wikiCalc appears to respond much slower when run this way and that you need to use its user administration functionality and do login/logout. Some of the slowness can be avoided if you are able to install wikiCalc to run with mod_perl or equivalent, but again, that requires expertise many people do not have and is even less likely to be available on simple hosting accounts.


wikiCalc sets up a series of special directories and files that help it support multi-user use and make its operation as transparent as possible to maintainers. The same directory structure is created on the client (if doing local editing) and also on the server (even if doing local editing).

The top-most directory it creates is in the working directory by default (usually the directory where the wikiCalc program is installed) though it may be created elsewhere through use of the "$WKCdirectory" setting in the file.

This important directory is "wkcdata". It is here that wikiCalc stores a file named "hostinfo.txt" which contains the definitions of Hosts and Sites. Three other directories may be present within wkcdata: sites, templates, and users.

Here is an example of the directory tree on a system running wikiCalc:

Directory structure diagram

Each site is given a directory with the site's name within wkcdata/sites. In the site's directory you will find "siteinfo.txt" which caches information about the pages to speed up the execution of the Pages tab. If deleted it is recreated automatically. You will also find files in the form of "pagename.published.txt", "", "", and "".

The published.txt files hold the information needed to edit a published page from the most recent time it was published. The backup and archive files are similar, but they hold previously published versions (including the most recent). They are accessible using the Tools Backups command.

The files hold the data for a page while it is being edited. Here is how it is used to help let only one person modify a page at a time: When you open a page for editing, the most recent published.txt file for that page is copied into an file with the current author's name (e.g., about.published.txt gets copied to about.edit.jsmith.txt). In the case of local editing, a file with that name is left on the server to indicate to other potential editors that the page has been "checked out". The Page tab list of pages lets you know of this potential conflict before you open a page for editing. (With local editing, you may need to reload the data from the server periodically to keep the information up to date -- it may not be refreshed otherwise that frequently.)

When you publish a page, the file is copied to a new published.txt file (and a backup), the HTML is produced and uploaded appropriately, and then the edit file is deleted (locally and on the server if doing local edit). If you specify "Publish Source" in the page's properties a copy of "pagename.txt" will be placed in the same directory as the HTML file so it may be accessed to copy the page, be accessible to pages on other servers for value references in formulas, etc.

The user directory contains a file for each defined user. The password is stored in the file encrypted with a standard one-way encryption.


wikiCalc has templates to simplify doing some of the initial settings for a page and to make maintaining the HTML wrapped around the sheet on a page easier. The two types of template files are for HTML rendering (name.htmltemplate.txt) and for creating new pages (name.pagetemplate.txt). These files may have a first line that starts with "{{templatedescriptionline}}" to provide a longer description than the "name" in the filename.

There are three types of places where template files may be stored. They are in the working directory (usually where the wikiCalc program resides), in the wkcdata/templates directory, and in a templates directory within a site directory. The first two are for "shared" system templates and the third for site-specific ones. The wikiCalc program comes with some templates already present in the first directory. You should put your system-wide ones in the second directory. The "default" template is found by searching first in the site templates directory, then in the wkcdata/templates directory, and finally in the first directory for a template with the name "default". If none is found a built-in template is used.

The format of the HTML templates should be easy to figure out by looking at the sample files as well as reading the help text shown on the Tools Page Properties page when you select "Edit a copy for just this page" for the HTML Template setting. The format of the page templates is just a normal published page data file (with the optional {{templatedescriptionline}} that is not copied). The maintenance of the templates needs to be done by the maintainer of the wikiCalc system by direct creation and deletion of files and is not done through wikiCalc commands.


A wikiCalc-maintained web page may be recalculated and rendered each time a visitor views the final published page if you wish. Normally wikiCalc produces static HTML pages. There are times, though, when there are changing values and you'd like the displayed calculations to reflect them. To do this you use the "Live View" functionality (see the description of "Live vs. static pages" on the "If You Are New to wikiCalc..." page and the details about live viewing on the "Details About Live View" page). Pages may be rendered either as full pages or as page-parts that may be automatically embedded into other web pages using simple Javascript.

(c) Copyright 2007 Software Garden, Inc.
All Rights Reserved.

wikiCalc, Software Garden, and Garden are registered trademarks of Software Garden, Inc.
Dan Bricklin's is a registered trademark of Daniel S. Bricklin.