next up previous contents index
Next: 9. Mailing list definition Up: Sympa Mailing Lists Management Software Previous: 7. Sympa with S/MIME and HTTPS   Contents   Index

Subsections


8. Customizing Sympa/WWSympa


8.1 Template files format

Template files within Sympa and WWSympa are text files containing programming elements (variables, conditions, loops, file inclusions) that will be parsed in order to adapt to the runtime context. These templates are an extension of programs and therefore give access to a limited list a variables (those defined in the 'hash' parameter given to the parser).

Review the Site template files (8.2, page [*]) and List template files (9.8, page [*]).

Let us describe the syntaxic elements of templates.

8.1.1 Variables

Variables are enclosed between brackets '[]'. The variable name is composed of alphanumericals (0-1a-zA-Z) or underscores (_). The syntax for accessing an element in a 'hash' is [hash-$>$elt].

Examples:

[url]
[is_owner]
[list->name]
[user->lang]

Foreach template you wish to customize, check the available variables in the documentation.

8.1.2 Conditions

Conditions include variables comparisons (= and <>) or existance. Conditions syntaxic elements are [IF xxx], [ELSE], [ELSIF xxx] and [ENDIF].

Examples:

[IF  user->lang=fr]
Bienvenue dans la liste [list->name]
[ELSIF user->lang=es]
Bienvenida en la lista [list->name]
[ELSE]
Welcome in list [list->name]
[ENDIF]

[IF is_owner]
The following commands are available only 
for lists's owners or moderators:
....
[ENDIF]

8.1.3 Loops

Loops allows to go through a list of elements (internally represented by a 'hash' or an 'array').

Example :

A review of public lists

[FOREACH l IN lists]
   [l->NAME] 
   [l->subject]
[END]

[elt-$>$NAME] is a special element of the current entry providing the key in the 'hash' (here the list name). When going the an 'array', [elt-$>$INDEX] is the index of the current entry.

8.1.4 File inclusions

You can include another file within a template . The specified file can be included asis or parsed itself (there is no loop detection). The file path is either specified in the directive or accessed in a variable.

Inclusion of a text file :

[INCLUDE 'archives/last_message']
[INCLUDE file_path]

The first example includes a file which relative path is archives/last_message. The second example includes a file which path is in file_path variable.

Inclusion and parsing of a template file :

[PARSE 'welcome.tpl']
[PARSE file_path]

The first example includes the template file welcome.tpl. The second example includes a template file which path is in file_path variable.


8.2 Site template files

These files are used by Sympa as service messages for HELP, LISTS and REMIND * commands. These files are interpreted (parsed) by Sympa and respect the template format ; every file has a .tpl extension. See 8.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 prefered language of the user) :

  1. ~sympa/expl/$<$list$>$/$<$action$>$.$<$lang$>$.tpl.
  2. ~sympa/expl/$<$list$>$/$<$action$>$.tpl.
  3. ~sympa/etc/templates/$<$action$>$.$<$lang$>$.tpl.
  4. ~sympa/etc/templates/$<$action$>$.tpl.
  5. ~sympa/bin/etc/templates/$<$action$>$.$<$lang$>$.tpl.
  6. ~sympa/bin/etc/templates/$<$action$>$.tpl.

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. Else file is taken as a text/plain message body.

The following variables may be used in these template files :

-
[conf-$>$email] : sympa email address local part

-
[conf-$>$host] : sympa host name

-
[conf-$>$sympa] : sympa's complete email address

-
[conf-$>$wwsympa_url] : WWSympa root URL

-
[conf-$>$listmaster] : listmaster email addresses

-
[user-$>$email] : user email address

-
[user-$>$gecos] : user gecos field (usually his/her name)

-
[user-$>$password] : user password

-
[user-$>$lang] : user language

8.2.1 helpfile.tpl

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

8.2.2 lists.tpl

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

-
[lists] : this is a hashtable indexed by list names containing lists' subjects. Only lists visible for this user (refering to visibility list parameter avec listed.

Example:

Here are public lists for [conf->email]@[conf->host]

[FOREACH l IN lists]
	
 [l->NAME]: [l->subject]

[END]

8.2.3 global_remind.tpl

This file is sent in used by REMIND * command. (see 14.2, page [*]) You may use additional variables

-
[lists] : this is a array containig listnames the user is subscribed to.

Example:

This is a subscription reminder.

You are subscribed to the following lists :
[FOREACH l IN lists
	
 [l] : [conf->wwsympa\_url]/info/[l]

[END]

Your subscriber email : [user->email]
Your password : [user->password]


8.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, at last uses its default.

Your list web template files should be placed in ~sympa/expl/mylist/wws_templates directory ; your site web templates in ~sympa/expl/wws_templates directory.


8.4 Internationalization

Sympa has originally been designed as a multi-lingual Mailing List Manager. First versions of Sympa already separated messages from the code itself, messages being stored in NLS catalogues (according to XPG4 standard). Later a lang list parameter was introduced. Now Sympa also keeps track of users' language preference.

8.4.1 Sympa internationalization

Every message sent by Sympa to users, owners, editors is outside the code, in a message catalog. These catalogs are located in ~sympa/nls/ directory. These messages have currently been translated into 6 different languages :

To tell Sympa to use a message catalog, you can either set the lang parameter in sympa.conf or set sympa.pl -l option on the command line.

8.4.2 List internationalization

lang list parameter defines the language for a list. It is currently used by WWSympa and to initialize user's language preference at subscription time.

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

8.4.3 User internationalization

The user language preference is currently exploited by WWSympa only. There is no email-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.


8.5 Topics

WWSympa's homepage shows a list of topics for classifying mailing lists. This is dynamically generated, based on lists' configuration parameter topics. A list may appear in multiple categories.

The list of topics is defined in topics.conf configuration file in ~sympa/etc directory. The format of this file is as follows :

<topic1_name>
title	<topic1 title>
visibility <topic1 visibility>
....
<topicn_name/subtopic_name>
title	<topicn title>

As you can see, you can use subtopics, the separator being /. The topic name is composed of alphanumericals (0-1a-zA-Z) or underscores (_). The order 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 scenario. You will find a sample of topics.conf in sample directory ; NONE is installed as default.


8.6 Scenarii

List parameters controlling commands' behaviour indicates a scenario. Example : the parameter send private is related to the scenario send.private. There are tree locations for scenario. When Sympa applies a scenario, it looks first for it into the related list directory ~sympa/expl/$<$list$>$/scenari, if it is not found, it scans ~sympa/etc/scenari and then in ~sympa/bin/etc/scenari which is the directory intall by the Makefile.

A scenario is a small configuration langage to describe who can perform an operation and what authentication method is requested for it. A scenario is a ordered set of rules. The goal is to provide a simple and flexible way to configure authorization and authentication for each operation.

Each scenario rule contains :

Example

del.auth
title.us deletion performed only by list owners, need authentication
title.fr suppression réservée au propriétaire avec authentification
title.es eliminación reservada sólo para el propietario, necesita autentificación


  is_owner([listname],[sender])  smtp       -> request_auth
  is_listmaster([sender])        smtp       -> request_auth
  true()                         md5,smime  -> do_it

Scenari can also contain includes :

    subscribe
        include commonreject
        match([sender], /cru\.fr$/)          smtp,smime -> do_it
	true()                               smtp,smime -> owner

In this case sympa apply reccursively the scenario named include.commonreject before introducing the other rules. This as been introduced in order to made a liter administration of common rules.

A bunch of scenari is provided with Sympa distribution ; it provides all possible configurations as defined in previous releases of Sympa ($<$= 2.3) whithout any change in your list configuration files.

These standard scenari are located in ~sympa/bin/scenari/ directory. Default scenari are named <command>.default.

You may also define and name your own scenari. Store them in ~sympa/etc/scenari directory. Example:

Copy the previous scenario in scenari/subscribe.rennes1 :

equal([sender], 'userxxx@univ-rennes1.fr') smtp,smime -> reject
match([sender], /univ-rennes1\.fr$/) smtp,smime -> do_it
true()                               smtp,smime -> owner

You may now refer to this scenario in any list configuration file as :

subscribe rennes1

A scenario consists in rules, evaluated from the first to the last. Rules are defined as follows :

<rule> ::= <condition> <auth\_list> -> <action>

<condition> ::= [!] <condition
		| true ()
                | equal (<var>, <var>)
                | match (<var>, /perl_regexp/)
                | is_subscriber (<listname>, <var>)
                | is_owner (<listname>, <var>)
                | is_editor (<listname>, <var>)
                | is_listmaster (<var>)
<var> ::= [email] | [sender] | [host] | [header-><smtp\_key\_word>] |  <string>
<listname> ::= [listname] | <listname_string>

<auth\_list> ::= <auth>,<auth\_list> | <auth>

<auth> ::= smtp|md5|smime

<action> ::=   do_it [,notify]
             | do_it [,quiet]
             | reject
             | request_auth
             | owner

perl_regexp can containt the string [host] (it will be interpreted at run time as the list or robot domain. The variable notation [header-$>$<smtp_key_word>] is interpreted as the SMTP header value only when performing the sending message scenario. It can be use for exemple to ask editor validation for multipart messages.


8.7 Loop detection

Sympa uses multiple tools to avoid loops in Mailing lists

First it rejects messages that either come from a robot (based on the From: and other header fields) or messages that contain commands.

Every message sent by Sympa includes a 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).

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

At last Sympa can detect loops due to command reports. Example of loop:

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 of each reports sent to an address in an internal counter. The loop detection algorithm is :


next up previous contents index
Next: 9. Mailing list definition Up: Sympa Mailing Lists Management Software Previous: 7. Sympa with S/MIME and HTTPS   Contents   Index
root 2000-12-20