Establishing Style and Supporting Multi-Lingualism

using the ArsDigita Community System by Philip Greenspun

User-accessible directory: none
Site administrator directory: none (/doc/styles is as close as it gets)
data model : none; entirely Tcl- and virtual memory-based
Tcl scripts: /tcl/ad-style
style definitions: by convention in /tcl/sitename-styles
Templates: /web/yourservername/templates/

This document explains how to establish site-wide style and presentation conventions. A core element of the system is AOLserver's ADP template parsing system.

The Big Problem

Here are some of the challenges that we need to attack:

consistent look and style conventions across thousands of pages
publishers who change their mind about how the site should look
users who are browsing on a simple device (e.g., Nokia 9000 cell phone) and need a text-only site
users who can't read English (even though it was good enough for Jesus Christ)

Some Trivial Solutions

Suppose that you simply want consistent look and feel, changeable by editing only one file, across thousands of dynamic pages:

edit the ad.ini file to set site background and text colors (these parameters are read by ad_header)
bash the source code for ad_header in /tcl/ad-defs to do something more dramatic (e.g., display a company logo at the top right of each page).
bash the source code for ad_footer in /tcl/ad-defs to do something consistent at the bottom of all the pages on a site

What about static HTML pages? You can put regsub calls in ad_serve_html_page (in /tcl/ad-html) to consistently change the appearance of outgoing pages.

If you're building from scratch, you could build in ADP instead of HTML and use ns_register_adptag to augment the HTML a bit.

Some Trivial Solutions in a Perfect World

In a perfect world, you'd modify ad_header or your static HTML to reference a cascading style sheet (CSS). See the HTML chapter of Philip and Alex's Guide to Web Publishing for an explanation and also do a View Source on the document to see a style sheet reference from the HEAD of a document.

This doesn't work out too great because (1) only the 4.0 browsers interpret style sheets, and (2) Brand M and Brand N browsers do very different things given the same instructions (each implements a subset of the CSS standard).

Why These Trivial Solutions Won't Work for You

Publishers and the designers they hire want to control much more than background, text, alink, and vlink colors. They want to move around the elements on each page.

So what's the big deal? Let them write whatever HTML they want.

The problem is that they want control over pages that are generated by querying the database and executing procedures but they don't want to learn how to program. Your naive solution is to let the designers build static HTML files and show them to you. You'll work these elements into Tcl string literals and write programs that print them to the browser. In the end you'll have programs that query the database and produce output exactly like what the designer wanted... on Monday. By Friday, the designer has changed his or her mind. Would you rather spend your life attacking the hard problem of Web-based collaboration or moving strings around inside pages?

Templates

Suppose that you send your staff the following message:

To: Web Developers

I want you to put all the SQL queries into Tcl functions that get loaded
at server start-up time.  The graphic designers are to build ADP pages
that call a Tcl procedure which will set a bunch of local variables with
values from the database.  They are then to stick