next up previous contents index
Next: 15. Mailing list definition Up: Sympa Mailing Lists Management Software version Previous: 13. Virtual robot   Contents   Index

Subsections


14. Customizing Sympa/WWSympa


14.1 Template file format

Template files within Sympa used to be in a proprietary format that has been replaced with the TT2 template format.

You will find detailed documentation about the TT2 syntax on the web site : http://www.tt2.org

Here are some aspects regarding templates that are specific to Sympa:


14.2 Site template files

These files are used by Sympa as service messages for the HELP, LISTS and REMIND * commands. These files are interpreted (parsed) by Sympa and respect the TT2 template format ; every file has a .tt2 extension. See 14.1, page [*].

Sympa looks for these files in the following order (where <list> is the listname if defined, <action> is the name of the command, and <lang> is the preferred language of the user) :

  1. /usr/local/sympa-os/expl/<list>/mail_tt2/<lang>/<action>.tt2.
  2. /usr/local/sympa-os/expl/<list>/mail_tt2/<action>.tt2.
  3. /usr/local/sympa-os/etc/my.domain.org/mail_tt2/<lang>/<action>.tt2.
  4. /usr/local/sympa-os/etc/my.domain.org/mail_tt2/<action>.tt2.
  5. /usr/local/sympa-os/etc/mail_tt2/<lang>/<action>.tt2.
  6. /usr/local/sympa-os/etc/mail_tt2/<action>.tt2.
  7. /usr/local/sympa-os/bin/etc/mail_tt2/<lang>/<action>.tt2.
  8. /usr/local/sympa-os/bin/etc/mail_tt2/<action>.tt2.

If the file starts with a From: line, it is considered as a full message and will be sent (after parsing) without adding SMTP headers. Otherwise the file is treated as a text/plain message body.

The following variables may be used in these template files :

-
[% conf.email %] : sympa e-mail address local part

-
[% conf.domain %] : sympa robot domain name

-
[% conf.sympa %] : sympa's complete e-mail address

-
[% conf.wwsympa_url %] : WWSympa root URL

-
[% conf.listmaster %] : listmaster e-mail addresses

-
[% user.email %] : user e-mail address

-
[% user.gecos %] : user gecos field (usually his/her name)

-
[% user.password %] : user password

-
[% user.lang %] : user language

14.2.1 helpfile.tt2

This file is sent in response to a HELP command. You may use additional variables

-
[% is_owner %] : TRUE if the user is list owner

-
[% is_editor %] : TRUE if the user is list editor

14.2.2 lists.tt2

File returned by LISTS command. An additional variable is available :

-
[% lists %] : this is a hash table indexed by list names and containing lists' subjects. Only lists visible to this user (according to the visibility list parameter) are listed.

Example:

These are the public lists for [conf->email]@[conf->domain]

[% FOREACH l = lists %]
[% l.key %]@[% l.value.host %] : [% l.value.subject %]

[% END %]

14.2.3 global_remind.tt2

This file is sent in response to a REMIND * command. (see 24.2, page [*]) You may use additional variables

-
[% lists %] : this is an array containing the list names the user is subscribed to.

Example:

This is a subscription reminder.

You are subscribed to the following lists :
[% FOREACH l = lists %]
	
 [% l %] : [% conf.wwsympa\_url \%]/info/[% l %]

[% END %]

Your subscriber e-mail : [% user.email %]
Your password : [% user.password %]

14.2.4 your_infected_msg.tt2

This message is sent to warn the sender of a virus infected mail, indicating the name of the virus found (see [*], page [*]).


14.3 Web template files

You may define your own web template files, different from the standard ones. WWSympa first looks for list specific web templates, then for site web templates, before falling back on its defaults.

Your list web template files should be placed in the /usr/local/sympa-os/expl/mylist/web_tt2 directory ; your site web templates in ~/usr/local/sympa-os/etc/web_tt2 directory.

Note that web colors are defined in Sympa's main Makefile (see 3.3, page [*]).

14.4 Sharing data with other applications

You may extract subscribers, owners and editors for a list from any of :

See user_data_source liste parameter 18.2.1, page [*].

The three tables can have more fields than the one used by Sympa, by defining these additional fields, they will be available from within Sympa's authorization scenarios and templates (see 6.10.10, page [*] and 6.10.11, page [*]).


14.5 Sharing WWSympa authentication with other applications

See 11.6, page [*].


14.6 Internationalization

Sympa was originally designed as a multilingual Mailing List Manager. Even in its earliest versions, Sympa separated messages from the code itself, messages being stored in NLS catalogues (according to the XPG4 standard). Later a lang list parameter was introduced. Nowadays Sympa is able to keep track of individual users' language preferences.

If you are willing to provide Sympa into your native language, please check the translation howto (http://www.sympa.org/howtotranslate.html);

14.6.1 Sympa internationalization

Every message sent by Sympa to users, owners and editors is outside the code, in a message catalog. These catalogs are located in the /usr/local/sympa-os/locale directory.

To tell Sympa to use a particular message catalog, you can should set the lang parameter in sympa.conf.

14.6.2 List internationalization

The lang list parameter defines the language for a list. It is currently used by WWSympa and to initialize users' language preferences at subscription time.

In future versions, all messages returned by Sympa concerning a list should be in the list's language.

14.6.3 User internationalization

The user language preference is currently used by WWSympa only. There is no e-mail-based command for a user to set his/her language. The language preference is initialized when the user subscribes to his/her first list. WWSympa allows the user to change it.


14.7 Topics

WWSympa's homepage shows a list of topics for classifying mailing lists. This is dynamically generated using the different lists' topics configuration parameters. A list may appear in multiple categories.

The list of topics is defined in the topics.conf configuration file, located in the /usr/local/sympa-os/etc directory. The format of this file is as follows :

<topic1_name>
title	<topic1 title>
title.fr <topic french title>
visibility <topic1 visibility>
....
<topicn_name/subtopic_name>
title	<topicn title>
title.de <topicn german title>

You will notice that subtopics can be used, the separator being /. The topic name is composed of alphanumerics (0-1a-zA-Z) or underscores (_). The order in which the topics are listed is respected in WWSympa's homepage. The visibility line defines who can view the topic (now available for subtopics). It refers to the associated topics_visibility authorization scenario. You will find a sample topics.conf in the sample directory ; NONE is installed as the default.

A default topic is hard-coded in Sympa: default. This default topic contains all lists for which a topic has not been specified.

14.8 Authorization scenarios

See 12, page [*].


14.9 Loop detection

Sympa uses multiple heuristics to avoid loops in Mailing lists

First, it rejects messages coming from a robot (as indicated by the From: and other header fields), and messages containing commands.

Secondly, every message sent by Sympa includes an X-Loop header field set to the listname. If the message comes back, Sympa will detect that it has already been sent (unless X-Loop header fields have been erased).

Thirdly, Sympa keeps track of Message IDs and will refuse to send multiple messages with the same message ID to the same mailing list.

Finally, Sympa detect loops arising from command reports (i.e. sympa-generated replies to commands). This sort of loop might occur as follows:

1 - X sends a command to Sympa
2 - Sympa sends a command report to X
3 - X has installed a home-made vacation program replying to programs
4 - Sympa processes the reply and sends a report
5 - Looping to step 3

Sympa keeps track (via an internal counter) of reports sent to any particular address. The loop detection algorithm is :


14.10 Tasks

A task is a sequence of simple actions which realize a complex routine. It is executed in background by the task manager daemon and allow the list master to automate the processing of recurrent tasks. For example a task sends every year the subscribers of a list a message to remind their subscription.

A task is created with a task model. It is a text file which describes a sequence of simple actions. It may have different versions (for instance reminding subscribers every year or semester). A task model file name has the following format : <model name>.<model version>.task. For instance remind.annual.task or remind.semestrial.task.

Sympa provides several task models stored in /usr/local/sympa-os/bin/etc/global_task_models and /usr/local/sympa-os/bin/etc/list_task_models directories. Others can be designed by the listmaster.

A task is global or related to a list.

14.10.1 List task creation

You define in the list config file the model and the version you want to use (see 18.3.5, page [*]). Then the task manager daemon will automatically create the task by looking for the appropriate model file in different directories in the following order :

  1. /usr/local/sympa-os/expl/<list name>/
  2. /usr/local/sympa-os/etc/list_task_models/
  3. /usr/local/sympa-os/bin/etc/list_task_models/

See also 15.10, page [*], to know more about standard list models provided with Sympa.

14.10.2 Global task creation

The task manager daemon checks if a version of a global task model is specified in sympa.conf and then creates a task as soon as it finds the model file by looking in different directories in the following order :

  1. /usr/local/sympa-os/etc/global_task_models/
  2. /usr/local/sympa-os/bin/etc/global_task_models/

14.10.3 Model file format

Model files are composed of comments, labels, references, variables, date values and commands. All those syntactical elements are composed of alphanumerics (0-9a-zA-Z) and underscores (_).

Here is the list of current avalable commands :

Model files may have a scenario-like title line at the beginning.

When you change a configuration file by hand, and a task parameter is created or modified, it is up to you to remove existing task files in the task/ spool if needed. Task file names have the following format :

<date>.<label>.<model name>.<list name | global> where :

14.10.4 Model file examples


next up previous contents index
Next: 15. Mailing list definition Up: Sympa Mailing Lists Management Software version Previous: 13. Virtual robot   Contents   Index
root 2005-09-30