Software Garden wikiCalc® Program:
If you are new to wikiCalc...
This page shows you how to get acquainted with wikiCalc by downloading the right version for your system and then how to choose which configuration to use for "production" use.

wikiCalc flying bird logo
INTRODUCTION

You use the wikiCalc program with a browser, like Internet Explorer, Firefox, Safari, or Opera. The construction and editing of the spreadsheet looks similar to (but definitely is not the same as) using a traditional desktop spreadsheet like Excel, Lotus 1-2-3, or OpenOffice.org Calc. Instead of interacting directly with the program on your personal computer, as you would with a traditional desktop spreadsheet, you use your browser to interact with a web server that is connected to a running copy of the wikiCalc program.

Here is a diagram of traditional spreadsheet use:

Author and spreadsheet, paper and reader

This is a diagram of wikiCalc use:

Author and wikiCalc

In normal wikiCalc use, when you are finished constructing a new spreadsheet or making changes to an existing one, the final result produces basic, static HTML web pages. These pages are served from a normal web server (such as Apache or Microsoft IIS) running on a "remote" computer, and may be viewed using a web browser without needing the wikiCalc program to be running, as in the following diagram:

Reader and HTML pages

Probably the most common production use of wikiCalc is to have it run on the same server on which the final HTML pages will reside. In this case, you can use wikiCalc to edit spreadsheet pages from most any computer with a browser over the Internet.

A more complete, technical explanation of the wikiCalc architecture is presented on the wikiCalc Architecture page.

The problem with this setup for many people is that they do not have access to a web server on which to run the wikiCalc program, or don't know how to set this up, or just want to try out the program without going to the trouble of a server-based installation.

LOCAL "DEMONSTRATION" VERSION

To make it easier for people to "try out" wikiCalc, a specially packaged version of wikiCalc is available that can run completely on your desktop computer without needing to install wikiCalc on a remote server. Included is a simple "local" web server that only works with the combination of the wikiCalc program and a browser on the same computer. For Windows users, this version is even available as a single "setup" file which installs the wikiCalc program, the local server, and a copy of the Perl language system needed by wikiCalc. After you are done trying out the program it is easy to uninstall this entire system if you wish.

This "local" version of wikiCalc is the full program, with all of the editing and computational capabilities of the "remote" version. As explained in the Architecture page, wikiCalc has the special ability to be run locally even in a production environment such that it makes use of only local execution for editing together with normal remote web serving for serving up the "published" pages. This is helpful for situations where you have a web page hosting account that will do page serving but not one where you may run programs (such as on the "free" web space that comes along with many ISPs' Internet access accounts) or where you want to edit when you are not connected to the Internet.

In addition to this "local" version, wikiCalc comes with the ability to do a "demonstration" setup. When first run, if wikiCalc detects that the system has not been set up previously it will offer to preconfigure your system with a sample web page to edit. This will save you from the need to fill out all the initial form fields needed to set up wikiCalc and give you a complete spreadsheet with existing content to try out.

This demo setup is only meant for the initial local testing. Production installations should be carefully configured using the wikiCalc configuration pages. Setting up a production system is similar in some respects to setting up a blogging system like Blogger or Movable Type. It requires you to set the location of various directories and values for certain system variables defining what it calls "hosts" and "sites". This is are all documented in the product itself.

Unlike many wikis and other server-based tools, setting up wikiCalc does not require you to connect to a separate database system. For storage it only makes use of the server's normal file system.

GETTING THE DEMONSTRATION SYSTEM

There are two versions of the demonstration "local" wikiCalc systems. One is for use on Windows desktop/laptop systems and the other is for Mac OS X / Linux / Unix desktop/laptop systems. In either case, download the appropriate version for your system from the Downloads and Installation page (either the "Windows Local Version" or one of the two "Plain Perl" files) and install and execute it as explained in the corresponding "Desktop Execution" installation section.

CHOOSING A PRODUCTION SYSTEM

Once you have determined that wikiCalc will meet your needs and want to use it for more "production" work and not just for demonstration testing, you must decide how you want to deploy it. There are many options to consider. Here are some of them:

Where the wikiCalc program is run

Probably the most common configuration for wikiCalc is as a normal, remote-server based application. In this case, wikiCalc is installed on a normal web serving computer and all editing as well as published page serving is done from that machine. All authoring is done remotely using a browser on other computers, usually the user's personal computer of some sort.

The instructions for setting up this configuration is listed in the Remote Server-based Execution section on the Downloads and Installation page.

In some cases you may want to normally run with a remote server, set up as just described, but sometimes do editing when you are not connected to the server. In this case, you do a normal Remote Server-based installation, but also install the program for local execution on your personal computer. The remote server must allow for FTP "write" access to the directories where wikiCalc stores both its data files (the "wkcdata" directory) as well as the directory where the published HTML files (if any) will go. On the personal computer you carefully configure a "host" and "site" that specify the FTP access and those directories for publishing. At a time when the personal computer is connected to the Internet you open wikiCalc pages for edit using the Page tab while running wikiCalc using the local version on that personal computer. Copies of those pages will be downloaded to the personal computer. Editing can now be done as a local edit (connecting to the local wikiCalc server on the personal computer) whether or not the personal computer is connected to the Internet. Publishing is done when the personal computer is connected to the Internet so that the published data may be automatically uploaded to the remote server (using FTP) by the local wikiCalc instance.

This "local and remote" use of wikiCalc can be added at any point to a remote-served installation. The local version of wikiCalc can be configured to work with one or more different remote-served sites on one or more remote-served systems.

Another configuration option is to do all editing locally on personal computers and have all page serving of the final published pages be from a remote server. This way you will have no need to set up and use a running Perl environment on the remote server. This is useful because for many people setting up CGI scripts is a high hurdle while others may only have access to a page-serving environment with no Perl system. For some people, doing all editing locally provides the most security because there is no need to maintain code running on the remote server. For others, this may be considered less secure because it uses FTP and because the FTP password resides on personal computers.

To use this configuration you first do a normal "local" installation as you would for a demonstration system. This would be done on each personal computer from which you wish to do editing and publishing. Next you need to have access to a page server of some sort, such as that provided with a hosting account (including an inexpensive shared-hosting account) or even from most ISPs as part of their Internet access accounts. For that hosting account you need to know how to do FTP access and the directory structure of the serving environment. Finally, on each "local" computer you need to use the wikiCalc commands that setup a wikiCalc "host" definition for the host system (with FTP username and password, for example) and a wikiCalc "site" definition for each directory to which you wish to publish pages. Each local installation needs to have these definitions, with the main difference being different "Author Name on Host" settings in the "site" definition for each different local installation.

The final configuration is one where editing is done using a remote-server and page hosting is performed by a different server. This is sort of a combination of the other configurations. Instead of wikiCalc running on the remote server and publishing locally on the same system on which it runs you set things up so that it uses its capability to publish by FTP to publish to another server just as local editing does. This should only be set up by people familiar enough with all the issues, including security issues, to fully understand how the system is working.

wikiCalc was built to normally create static HTML pages as output. These pages consist of the table of cells in the spreadsheet (without the light editing grid displayed) "wrapped" in an HTML template that provides the borders of the page with headings, common links, etc. In this respect publishing a wikiCalc page is very much like publishing a blog page where the text of the post is wrapped in a template.

wikiCalc pages are organized into "sites" with each site consisting of pages in one directory on a web server. Pages created by systems other than wikiCalc may be in the same directory as long as the page names are unique. Again, this makes wikiCalc pages much like pages on a blog.

Publishing this way is done using the default "Publish HTML" setting for pages.

There are some issues with these static pages.

One issue is that anybody with web access to that directory can view the published pages in their browser. For public pages this is not a problem. For private pages, such as those with financial and other information, this might be a problem. If the website is behind a corporate firewall and it is OK for everybody within the company to view the pages there is no problem. If that is not the case, then you will need to provide some kind of access control. This can be done on most hosting systems through common means, such as Apache's ".htaccess" files. Unfortunately, this is not something most people want to (or know how to) deal with and is not connected to wikiCalc itself so it involves a separate unintegrated step prone to error.

Another issue is that the pages are static and do not reflect any changes since they were published. For example, a cell might include a formula that refers to the value of a cell on another page or use the wkcHTTP function to retrieve data from somewhere else on the Internet. These new data values would not be reflected in the displayed spreadsheet.

Yet another issue is that there are often times when you want to display the wikiCalc-produced table inside of another page, such as on a status page or on a page maintained by some other system. Many blog pages have separately updated content displayed on them in the borders, such as RSS feeds or photos updated on other systems. It would be nice to have content maintained by wikiCalc similarly displayed.

To help address all of these issues, wikiCalc has other ways to render pages.

In addition to producing normal static HTML pages made up of a spreadsheet wrapped in a template, wikiCalc can also produce a ".js" file that can be "embedded" in other web pages with a simple Javascript command placed in that other page. This ".js" file only contains the contents of the spreadsheet table without a surrounding template. (See "Details About Embedding" for more information.)

The wikiCalc editing system itself can also be used to render pages "live" in a variety of formats to add easy, basic access control and up-to-date calculations.

When a page is "published" wikiCalc gives you the option of specifying whether or not to produce the normal HTML version as well as an embeddable ".js" version. The program also gives you the option of allowing viewers to use the "live" view of a page without needing to login to wikiCalc.

The "live" view can produce either complete HTML pages, wrapped in a template, just like the normal HTML pages, or it can produce ".js" data that can be embedded in other pages. The main difference between "live" and static pages is that the values on the "live" page are calculated each time the page is retrieved from the server. "Live" serving uses up more server processing power than static serving because wikiCalc has to be run each time a page is displayed. Static serving just uses the web server without invoking wikiCalc and uses a small fraction of the processing and can usually be done much quicker.

When you set up a wikiCalc system, you should decide which form of rendering is going to be used. The choice can be changed on a page by page basis at any time. Details about "live" viewing can be found on the "Details About Live View" page.

Access control

When you are editing a spreadsheet page wikiCalc needs to have a name to associate with your edits. The editing is saved by wikiCalc each step along the way together with that name. During editing all changes are reflected only in the editing copy and the published page visible to normal browsers is left unchanged. After the page is published the editing copy is automatically deleted. This is similar to many blogging systems where "draft" versions of new posts exist and are only put on the public blog when the draft is published.

This use of a name and saved drafts is different than most wikis where edit drafts are only saved in the browser and "preview" is the only other step before publishing. If you close your browser before publishing the wiki edits they are lost. This is not a big problem with wikis because the assumption is that you are only making minor changes that are complete by themselves (and not leaving the wiki text in a bad intermediate state) or that the editing was done separately in a local editor or word processor and is only pasted into the wiki edit field when complete. This is different than with blogs and wikiCalc where the draft version is maintained by the system and you can close down your browser and come back to complete the editing at a later time.

wikiCalc was built assuming that multiple people would often be creating and maintaining any given site or any given page. It makes frequent use of a name for the author. Therefore, it requires you to let wikiCalc know which author you are. Also, it is common that only certain people will be allowed to change (or even have access to) pages or sites so some sort of user name / password system is needed. This is especially true for remote-server use of wikiCalc. When used locally, you can set wikiCalc to have a single built-in user name for each site you can edit. For use on a remote server wikiCalc has a simple user name and password system built in so you can set the user name by logging in. The login information can optionally be saved in a browser cookie so that you can return to editing without needing to login each time.

wikiCalc can also use the user name / password system to separately control viewing as well as edit access to "live" pages. Details about "live" viewing can be found on the "Details About Live View" page and details about "Edit This Page" on the "Details About 'Edit This Page'" page.

The wikiCalc access control system is very simple and basic and does not use any "secure" protocols or techniques (of course passwords are stored in an encrypted form in the system). A common modification to wikiCalc (allowed because it is released as Open Source) is to change it to make use of the access control system being used by other systems at the company where wikiCalc is deployed.

When wikiCalc is first installed, by default it does not have the access control system turned on. It is set for local use by one person and assumes a single name. It is important for most non-local use of wikiCalc to set up the access control system. This is done by using the Tools User Administration command. Make sure that you set at least one "Admin" user and set "Require Login" to "Yes". Only "Admin" users have access to the User Administration command as well as some other commands such as the Page Manage Sites and Manage Hosts commands.

MORE INFORMATION

There is more information about wikiCalc on the Features page and listed on the home page.


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

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