NAME Programming Code Styling for Dada Mail!


DESCRIPTION

This document is to help in understanding how Dada Mail is written.

Some of the main goals for these guidelines are to:


Perl


XHTML

Must be valid XHTML 1.0 Transitional


HTML::Template Templates

HTML::Template is the templating language used for most all of Dada Mail's screens. Currently there is some inline HTML and we'd like to get rid of all of this ASAP.

Currently, there are three categories of templates. The first category is for the different top-level (X)HTML document/page types. And the latter two categories, which are the bits and pieces that then get included into those top-level templates, are Dada Mail-centric.

  1. top-level templates

    Templates that end in ``template.tmpl'' are the ``document containers'' for the various types of pages/screens in Dada Mail. Or to put it another way: these are the ones we'd add an ``.html'' extension to if it weren't for their HTML::Template includes.

    These document containers include the bare-minimum (X)HTML structure for the document (e.g.: the doctype, head, and body), plus the general structure of the type of page in question (for instance, separate #Header and #Content sections for default_list_template.tmpl).

    A few extra <div> and <span> ``wrappers'' can also be found in some of these templates, for CSS customization and cross-browser bugfixing purposes. To keep things as clean and user-friendly as possible, we'd like to keep these ``extra'' structural wrappers meaningful (like the #Logo and #Title wrappers inside the #Header), and to a minimum (no redundant divs-within-divs, unless there's a really good reason). [At the moment, this is still a work in progress.]

  2. screens

    Templates that end in ``screen.tmpl'' are basically the chunks of code that get inserted into the top-level document templates, and that contain all the interesting, screen-specific content you'll see in your web browser.

    NO screens should have form field without a <form></form> tag pair surrounding the form. DO NOT assume that there will be these tags available.

  3. widgets

    Templates that end in ``widget.tmpl'' are parts of a whole screen, and are usually inserted into a screen or another widget using the <!-- tmpl_include ... --> tag.

    The whole idea of a widget is to allow you to use the same snippet of code in more than one template.

    If the widget has part of a form in it - i.e.: an input tag of some type - please document this fact somewhere near the top of the script, as it aids debugging.

    NO widgets are allowed to have a unpaired form tag.

begin/end comments in HTML::Template templates

When making a new template, always put a:

 <!-- begin templatename.tmpl -->

tag at the beginning of the file and a:

 <!-- end templatename.tmpl -->

tag at the end of the file. This makes it easy for developers and end-users alike to debug or customize things by reading the output source code (using their browser's ``view source'' feature) and tracking any line back to the template that created it.


CSS

Must be valid, unless it's an absolutely unavoidable hack.

Absolutely unavoidable hacks must be well-commented.


JavaScript

We really ought to avoid the six ``bad practices'' at:

 http://www.quirksmode.org/blog/archives/2005/06/three_javascrip_1.html

but we haven't quite gotten to #6 yet (I'm thinking here of the admin template's: <body onLoad=``init();''> ). And similarly, we should probably also be shooting for ``unobstrusive JavaScript'' as per:

 http://www.onlinetools.org/articles/unobtrusivejavascript/

but on that front, we're not even close.

Assistance and experience here would be greatly appreciated. :-)


Commenting Code

begin/end comments in HTML::Template templates

These are the,

 <!-- begin templatename.tmpl -->

and:

 <!-- end templatename.tmpl -->

Already discussed.

Other

Several other proposed labels have been put into place for development purposes. All are optional.

Any other ideas are appreciated. I'd rather have TOO MUCH commenting going on than too little.


CVS

When you're comitting via CVS and working on a bug/feature request, please put the id of the bug/feature request in the comment of the commit.

A more verbose commit comment is appreciated, as these commits are combed to make the changelog.