Caucus 4.4 and the "overrideable" CML directories.
(Last updated 12 March 2002.)

I. Introduction
The main purpose of Caucus release 4.4 was to restructure the CML interface directories in a way that makes modifying the user interface much easier and cleaner.

In previous versions, maintaining changes to the CML files that define the user interface could get very messy, especially for a site that has many different sets of interfaces on a single host.  It got even worse when one tried to apply an official Caucus upgrade, and make the local changes all over again.

II. Interfaces -- the old way
Prior to 4.4, a Caucus "interface" was a directory under the Caucus home ~/CML directory, such as ~/CML/CS41 (the default).  Changes could be made to the files in this directory, but it was up to the site administrator to track (and remember) such changes when a Caucus upgrade was installed later on.

There was a separate interface for self-registering new Caucus users, which lived under a different directory, such as ~/CML/REG41.  One or more such registration directories could be associated with a user interface directory, but the rules for such association got confusing.

Certain "local" information lived in a deeper subdirectory, such as ~/CML/CS41/Local.  In particular this included macros.i, the list of definitions of interface macros, and switch2.i, the definitions of the manager's "editable switches" such as password confirmation or response editing.

III. Interfaces -- 4.4
In the new method, an interface is a single directory under ~/CML.  The (new) default interface is "CC44" (short for CaucusCare 4.4).  Under each interface directory is a set of subdirectories, called the "tool" directories, each of which contains CML files:

The CC44/main directory is equivalent to the old CS41 directory.  It contains most of the same files, such as center.cml (the Caucus Center page), confhome.cml (conference home page), etc.  The "Local" subdirectory is no more -- all of the relevant contents (macros.i, switch.i) have been moved up the "main" level.

The CC44/reg directory is equivalent to the old REG41 directory.  Unlike the old method, here the registration interface is automatically associated with the user interface by virtue of being under the common CC44 directory.  Furthermore, the site administrator can add multiple registration interfaces, and they are all automatically associated with the user interface.

For example, suppose a site is running a "paid" Caucus event, where most of the participants pay to attend.  Their self-registration page might have fields for billing information.  But we can also create an interface for "free" participants, perhaps the guest speakers, which does not have those fields.  To do this:

  1. Create a directory ~/CML/CC44/freereg
  2. Copy everything from CC44/reg into CC44/freereg
  3. Go to the manager page in Caucus, and begin changing the look and feel of the freereg interface.
That's it!  Caucus automatically detects the existence of multiple registration directories, and offers (on the manager page) the choice of customizing each one, individually.

IV. Overrideable Directories
A key feature in 4.4 is the ability to "override" existing CML files instead of changing them.  For example, to change the action of the center.cml file, make a copy of the file, edit it to make the desired changes, and place it in an "override" directory.

The override directory for a tool directory is its name plus a dot and a (one-digit) number.  Thus, in the previous example, create the directory CC44/main.1, copy center.cml from CC44/main to CC44/main.1, and edit it there.  Any file found in main.1 "overrides" its equivalent file in main; similarly for reg.1 and reg, help.1 and help, etc.

This has several nice effects:

  1. The original file is always around in case it is needed (for study or to undo changes).

  2. The changed files can be found and identified very easily, simply by looking in main.1 etc.

  3. When Caucus is upgraded, the new files are placed in main, reg, and help.  Your local "override" files remain untouched and continue to override the new "vanilla" files.

    (It is possible that this may cause problems, if the local overrides are incompatible with the newly upgraded files in main, reg, and help.  But even then, it is far easier to find the source of the problems, since the changed files are easily identifiable.)

There are actually ten possible levels of override: main, main.1, main.2, main.3 ... all the way up to main.9.  As you might expect, any files in main.9 override anything below them, main.8 override below that, and so on down.  In practice, three levels will probably be sufficient for all purposes: main for the original files, main.1 for locally applied changes, and main.2 for new local development happening "on top of" main.1.

It is not necessary for a file to exist in all levels; to add a new CML file, place it in main.1 even though there is no equivalent in main.  Caucus will still find it there.

Caucus automatically caches (in memory) the full pathnames of the files it finds in this way, so the searching through the override directories is very fast.  Because of this cache, however, if a new file is added to an override directory during a Caucus session, that user will not "see" the file until they quit Caucus and start a new session.  (If a file is removed from an override directory, Caucus will similarly complain that it can't find the file.)

V. Editable Switches
Prior to version 4.4, the manager "editable switches" were kept in the file ~/CML/CS41/Local/switch2.i.  Changing the value of a switch actually rewrote the CML file.  This was never really a good idea, and it is completely gone in 4.4.  Standard CML interface files are never written by Caucus operation.

To make this change, the "editable switches" were moved to what are called "site variables".  When Caucus 4.4 is installed, the values of the editable switches will revert to their defaults.  If you wish to keep your old values, copy the file ~/CML/CS41/Local/switch2.i to ~/CML/CC44/main before attempting to use the manager "editable switches" link to change any switch values.

This change has one side effect: the editable switches are now common, i.e. the same, across all interfaces on a site.  Normally this is not a problem; if it becomes one, there may be ways to create interface-specific versions of the editable switches.

VI. Compatibility with pre-4.4
Caucus 4.4 is still completely compatible with the old directory structure.  You can keep your old interface directories (such as CS41) around, and all the old links to them will still work.

The one possible exception is the "special" or "outside" Caucus URLs, such as http://yourhost.com/caucus/conference_name.  Check the file(s) ~/SWEB/start.cgi for more details, this may vary depending on your system's configuration.

VII. Integrating pre-4.4 custom pages
If you have made custom changes to Caucus CML pages prior to version 4.4, integrating them with 4.4 is fairly straightforward.  Follow these steps:

  1. Identify the changed files.  Ideally you know which files you changed.  If not, compare them against the original files ("out of the box") from your Caucus kit to find the changes. 

    (Hint: most distributions of Unix have a "diff" command that can be applied to directories.  E.g. "diff -r -q dir1 dir2" tells you which files are different between directories dir1 and dir2.)

    Once you have the changed files, copy them into the appropriate override directory.  (That is main.1 for the main interface, help.1 for help files, reg.1 for registration files.)

  2. Change the directory variables.  Caucus uses a couple of CML variables for the names of directories.  With the change in CML directory structure, you'll need to change these variable names.  Specifically:

    1. Replace all instances of "$(href)" with "$(mainurl)".
    2. Replace all instances of "$(dir)" with "$(main)" except where "$(dir)" is used as part of a Caucus site-variable or conference-variable name; in that case replace it with "$(iface)".
    3. Replace all instances of "$(help)" with "$(helpurl)".
    4. Replace all instances of "$(helpdir)" with "$(help)".  (It's important to do the last two steps in exactly that order.)
    5. The expression "$(inc)" should not be used at all.  (All code that used it has been removed or replaced in 4.4.)

  3. Merge forks.  Now that you have your changed files using the same directory structure as the 4.4 files, proceed to merge any "forks" (places where 4.4 changed in one direction, and your files changed in a different direction).  Individually compare the files in, for example, CC44/main and your new CC44/main.1 directories with a tool such as merge (or CaucusCare's open source tool merge2).  Leave the final result in main.1 (and similarly for help.1 and reg.1).