| 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. Where it runs 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:  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:  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. |
Directory structure 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 (usually the directory where the wikiCalc program is installed). That directory is "wkcdata". In that directory it 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:  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", "pagename.backup.date-time.txt", and "pagename.edit.name.txt". The published.txt files hold the information needed to edit a published page from the most recent time it was published. The backup files are the same, but they hold each previous publish (including the most recent). (Currently, until the Beta version, there is no built-in way to get to these backups, but if you copy one to replace a "published.txt" file you will effect a restore.) The edit.txt 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 edit.name.txt 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. (You may need to reload the data from the server periodically to keep the information up to date -- it is not refreshed otherwise.) When you publish a page, the edit.name.txt 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 "pagename.txt" will be placed in the same directory as the HTML file so it may be accessed to copy the page, runtime recalc, 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. Templates 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 current 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 may also be a "name.livetemplate.txt" file for the template used when a "live" page is published (for example this template could create a page that does a browser redirect to the WKCrecalc.pl program with appropriate arguments). 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. |
Runtime Recalculation The 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 View" on the "What's new in Beta 0.95" 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. |
| wikiCalc Beta Test Home |