TWIG Styles Specification
a.k.a. Themes

Written by Jaime Kikpole
on November 16, 2004

Edits by Aaron Stone
on November 17, 2004


Background:

	TWIG 2.8.0 introduced the use of Cascading Style Sheets (CSS) to
help format the look and feel of the page.  CSS obsoletes the need for the
hundreds of <b>, <i>, <font> and other "old fashioned" HTML tags found in
the pages generated by older versions of TWIG.

	CSS brings us several advantages.  Simpler HTML is faster to
assemble on the server.  It produces less data to download, especially
important to dial-up and mobile phone users.  Simpler HTML is easier to
parse by a web browser.  All of these benefits mean that the delay between
clicking on a link and seeing the next page has been reduced.

	TWIG 2.8.0 allows for "styles" or "themes" by linking to different
CSS files.  This document describes the file structure, classes and named
attributes needed to produce a CSS style for TWIG.  Please build styles
that comply with this specification, else it may be very difficult to
maintain compatibility with future versions of TWIG.

Files:

	In the directory "styles", there is a directory for each style.  
That directory may contain the files basic.css, style.css, print.css,
readme.txt, and desc.txt.  It may also contain a directory named "images".


basic.css

	This is the most important file of a style.  Contains only CSS
code and comments.  If any code may cause a browser to be buggy, it is not
put in this file.  See style.css, below.  While not generally useful to do
so, this file may optionally be empty.  It must exist.

	This file is linked via an HTML <link rel="stylesheet"
type="text/css" href=".../basic.css" media="screen,print"> tag in
config/header.inc.php3.  The login screen uses this file from the style
named "classic" unless config/login.header.inc.php3 has been edited.


style.css

	The "advanced" part of the style.  Contains only CSS code and
comments.  Only code which may make a browser crash or behave poorly
should be put in here.  The file may optionally be empty, but must exist.

	This file is linked via an @import() command in
config/header.inc.php3 and config/login.header.inc.php3.  This generally
looks something like this:

	<style type="text/css">@import url(".../style.css");</style>

	The purpose of this technique is to take advantage of a bug in
older web browsers.  Many browsers with incomplete and buggy support of
CSS (e.g. Netscape Navigator and Communicator 3 and 4 and Internet
Explorer 3) will not understand the @import() method of linking to
external CSS files.  These same browsers often incorrectly render or even
crash when exposed to certain CSS instructions.  By using this method of
linking to style.css, you can protect users of older browsers from the
flaws of their software while making the more complicated CSS designs
available to users of more CSS compliant browsers.


print.css

	The "print view" part of the style.  This will be introduced in
version 2.8.1.  Is only relevant when a CSS compliant browser attempts to
print a page.  Useful for switching to black & white (to save color ink),
hiding parts of the page (e.g. the menus, which are useless on paper),
and otherwise simplifying the printed page.

	TWIG previously used the Print View command.  By observing users,
we learned that this command was seldom used due to the extra step, wait,
and training involved.  This command will be removed in a future version
of TWIG.

	This file may optionally be empty, but it is not recommended.  It
must exist.  Use it only to override and/or supplement settings in
basic.css or style.css.

	This file is linked via an HTML <link rel="stylesheet"
type="text/css" href="../print.css" media="print"> tag in
config/header.inc.php3.  The login screen does not reference it.


readme.txt

	This file is intended for the TWIG administrator.  It can be used
to leave notes about which web browsers tend to do well or poorly with the
style.  Other notes may be left as well, at the style writer's discretion.  
This file is not used by TWIG in any technical way.  This file may
optionally be left empty.  It is not required to exist.


desc.txt

	This file is intended for the TWIG user.  Its contents are placed
in style list in the Preferences section.  A 50 character limit is enforced
by TWIG.  By default, all styles that come with TWIG use the format of:

<Style Name> - <Description>

	This lends consitancy to the list of styles in the Preferences section 
while not limiting the Style names to any arbitrary file system limits.

	For the sake of effectiveness, keep your description short and avoid 
trendy or cute phrases.  The words in this file should tell the user why they 
should try the style.  Do not include any HTML.  This file may optionally be 
left empty.  It is not required to exist.

	If this file is either empty or does not exist, the directory name
will be used in the list of styles for the Preferences feature.


images

	This is a directory that may exist or not, as needed.  If the CSS
references additional graphics files, then they must be stored in this
directory.  In this way, the graphics may be distributed with the style.  
This may be useful for things such as background graphics.  Any graphics
files may be stored here, e.g. JPEG, GIF, PNG, etc.



TWIG's CSS Classes:

	To be written.  In the mean time, please see the classic theme for 
examples.  Note that there is also a new previous/next widget in TWIG 
called "Themed Style".  This widget uses the CSS classes navigation, 
nav-first, nav-prev, nav-current, nav-next, and nav-last.


Uses for Styles:

	The following are some reasons to considering making a style for
your site:


Brand Identity

	This is largely self explanatory.  It even works with groups that
don't appear to have brands.  For example, you may wish to use your school
colors.


Integrate TWIG Into Your Web Site

	Colors, fonts, and margins can play a large part in making your
TWIG installation look and feel like the rest of your web site.  This can
make the difference between TWIG being a program that you added that has
its own identity ("...my TWIG account is weird...") and making it into a
part of your web site ("...my email account is working now...") or even
giving your uses a sense of ownership ("I use the XYZ style.  Its great!")


Accessibility

	If you have users with visual impairments, you might want to make
a style with large font sizes.  Color blind users may appreciate carefully
selected text and background colors.


Older Equipment

	If your monitors have lower screen resolutions, then a smaller
font size might be handy.  In 640x480 resolution, horizontal scrolling may
occur with standard font sizes.  Likewise, simplistic styles might be
faster on slower computers.


Interactiveness

	Using some of CSS v2.1, you can make TWIG seem to be more "alive"
and fun.  Investigate the ":hover" pseudo-class to see a great example.  
Some of the test styles that the TWIG developers made used :hover to place
a yellow background highlight behind the message that was under the mouse
in the user's email inbox.  As the user panned up and down through their
list, TWIG gave them a visual focus.  Likewise, the underline below a link
can be changed into a faint grey outline, text and background colors can
be inverted, and more.



Reference Material:

The CSS v1 and v2.1 specifications should be the most useful items to you.
URL:  http://w3c.org/Style/CSS/