(This is part question and part exposition, I apologize for combining the
two.)
I recently started playing with ComSwiki by downloading the Mac package.
Fortunately, this worked right away! All I had to do was start the image
and happy begin adding pages to my refs swiki.
I want to make some changes to the behavior of the Swiki based on
some ideas that the system inspired (and personal preference). Some
changes are cosmetic, others may require more work.
In the Squeak spirit, I poked around the Swiki directory and source code
to try to figure out what was going on. There is certainly a lot there.
Since I don't know of any documentation, here is an attempt at
understanding how to customize Swikis, in order of increasing complexity.
(Since this is all inferred from what I saw, any corrections to my warped
mindset would be appreciated!)
HOW SWIKIS ARE CUSTOMIZED
1. Of course, any user can edit any page. This effects the content of
the current page "main content area" as well as creating links to new and
existing pages. This involves editing the page, typing changes (using the
basic formatting conventions like *links* and "# numbered lists") and
submitting the changes. Users can therefore do as much content evolution
as they want.
2. Some broad things can be customized using the admin tool. For
example, you can password protect pages or otherwise set access properties
for a given swiki. This involves filling out the appropriate Web form.
3. Coarse formatting changes are possible through editing the
settings.xml file. For example, you can change your color scheme by
changing the appropriate entry. These color schemes correspond to
directories in the "swiki/x/files" directory. ("x" in my case is
"default". It looks like you can put these in your swiki's directory or
whatever directory your swiki inherits from.) So you can change the
buttons by replacing the appropriate GIFs, and change the color for the
BODY tag with the "colorScheme" file.
4. Finer-grained page formatting changes are possible through the
template schemes. It looks like there are templates in the form of
"shelves" (.shelf files), "books" (.book files), and "pages" (.page
files). Again, it appears that these are first read from your swiki's
templates directory, and then the directory from which your swiki
inherits. When a page is requested, some appropriate templates are used
to render the page (from an abstract representation into the pure HTML
that a browser expects to see.) This seemse to work like this:
4.1. ".page" files seem to be templates for different kinds of pages.
There is a custom .page for some kinds of page in a swiki (like the
history page.)
4.2. ".book" files seem to be templates for other kinds of pages in the
swiki (like the Page Not Found pages and corresponding pagenotfound.book).
The difference between a book and a page is unclear.
4.3. ".shelf" files seem to be templates for things that aggregate over
a bunch of swikis or a bunch of pages.
These templates look more-or-less like HTML with special tags like
<?colorscheme?> that eventually get replaced by appropriate strings
containing HTML. It isn't clear what mechanism does the replacements, but
it is fair to assume they either come from text files,
instance/class/global variables of some class in the server, or objects
that get sent messages that return strings. Understanding this better
would be helpful.
So, if you want to change how pages look, you can do a lot by changing
these templates.
5. More substantial changes (for example, structural changes) are handled
by source code of the Swiki. There are a lot of classes, but things like
the TextFormatter (and subclasses like BookTemplateFormatter),
SwikiStorage, SwikiBook, and NuSwikiPage seem to be involved. Some of
these have lots of complex messages, and I can't say I followed these all
that carefully.
6. Really low-level changes (to the networking protocol) are handled by
Commanche source code. This provides behavior control at the HTTP
protocol (and socket) layer.
======
(Is this right? Are there more specific ways to understand this
vagueness?)
QUESTIONS:
I think I know how to change simple stuff like the colorschemes, but how
do the templates work? What happens when <?this?> is rendered?
How would one attempt more advanced enhancements? For example, the
IP-address logging mechanism isn't good enough for our purposes (because
of our firewall, everyone's changes look like they come from the same
machine.)
I don't want to do draconian user tracking, but I would like to provide a
simple login mechanism. That would make it easier to see who made what
changes. (Of course, users could sign all their posts with their
*initials*, but if they forget to do that it would be bad.) There looks
like there is some support for cookie-based login in Comanche, but I don't
see how one could use that in the Swiki.
Another enhancement I would like to add is some more advanced notification
schemes than the current system. Some ideas include:
* To allow users to subscribe to a daily email (brief) summary of what
pages have changed that day (just a convenience on top of the "recent
changes" mechanism)
* To provide "group pages." My vision is that a group (like a project
group) would create a page for their group. The would want to know not
only when that group page changed, but any changes of pages (perhaps 1
deep) that the group pages pointed to. For example, if you have a page
*a* that refers to *b*, *c*, and *d*, you are interested when any of those
pages change.
Where would one begin to look to make that kind of modification?
I apologize for what is a very large question, but what I'm getting at is
I don't know where to start looking. A "readers guide to the swiki
classes" is an ambitious goal. It seems to be a common problem in
Smalltalk systems - browsing is very easy but understanding the bigger
picture is hard.
Next week: The Idiot's Guide to CGI Form Handling. :)
Thanks for tolerating this long-winded question,
-Eric
