[Mailman-i18n] Template file lookup

Barry A. Warsaw barry@digicool.com
Fri, 18 May 2001 14:28:40 -0400


I'm about to change the search order for templates -- you know, those
pesky .html and .txt files that live in $prefix/templates and
$prefix/lists/$mylist.  This change is necessary to properly support
language templates, and also provides a much requested feature, namely
that you will only need to specialize templates that you actually want
to change, and that you have multiple levels of specialization.

Here's how it works.

There are 4 levels of template specialization: list-centric,
vhost-centric, site-centric, and default, corresponding to the
directories

    $prefix/lists/$listname
    $prefix/templates/$host_name
    $prefix/templates/site
    $prefix/templates

Each of these locations is further organized by language
subdirectories.  So let's say you were looking for the listinfo.html
template for list foobar in language es.  You'd actually end up
searching 12 directories, with of course, the first hit stopping the
search.  Let's say further that list foobar is in the www.foobar.com
virtual domain, and that it's list-preferred language is fr, while the
server's default language is en.  Here's the files you'd search for:

    $prefix/lists/foobar/es/listinfo.html
    $prefix/templates/www.foobar.com/es/listinfo.html
    $prefix/templates/site/es/listinfo.html
    $prefix/templates/es/listinfo.html

    $prefix/lists/foobar/fr/listinfo.html
    $prefix/templates/www.foobar.com/fr/listinfo.html
    $prefix/templates/site/fr/listinfo.html
    $prefix/templates/fr/listinfo.html

    $prefix/lists/foobar/en/listinfo.html
    $prefix/templates/www.foobar.com/en/listinfo.html
    $prefix/templates/site/en/listinfo.html
    $prefix/templates/en/listinfo.html

Note that the Mailman 2.0.x search directories of
$prefix/lists/*.{html,txt} and $prefix/templates/*.{html,txt} are
deprecated and no longer searched.  The bin/upgrade script will
actually md5 checksum all the old files and remove any templates in
more-specific locations that exactly match their more-general
counterparts.

Any template in $prefix/lists or $templates will have to be moved
manually.

It is highly discouraged that you will ever manually edit a file in
$prefix/templates/$lang, and Mailman's install target will have every
right to overwrite them on an upgrade.  That's what the templates/site
subdirectory is for; upgrading will never touch site-centric,
domain-centric, or list-centric templates.  Of course, that means it's
up to site administrators to merge in changes to the default
templates.

Watch for checkins shortly.

Comments?
-Barry