[Mailman-Developers] Mailman 3 custom footer

[Barry Warsaw]

On Feb 25, 2016, at 02:36 PM, treal tv wrote:

>I'm looking to modify the contents of this footer so it says something
>slightly different. However, I can't find anywhere with Mailman 3 to change
>anything about the footer.

I'll describe what you have today, but it's likely the exact details will
change at some point (maybe for 3.1 if my ideas pan out).  Still, how it works
today still contains the basic scheme for how I want it to work in the future.

The thing to remember is that while Core needs to send out emails with various
templates, it can't make any assumptions about what is on the web front-end,
so text like footers can't contain URLs and such by default.  Yes, this is a
bit of a mess right now because you'll still see substitutions like
$listinfo_url in some templates, even though these can't be correctly filled
in.

So there are two parts to this answer.  The first is finding the template to
use for the footer[*], and then filling in all the placeholders.

You've found the footer-generic.txt template, but how is this used?  Every
mailing list currently has an attribute called `footer_uri`, and this is set
in the list style.  I've previously described how style works so I won't go
down that detour here.  Suffice to say that the default style sets footer_uri
to `mailman:///$listname/$language/footer-generic.txt`.

Notice two things about this uri.

 * It has a `mailman:` scheme.
 * It has some $-placeholders.

What happens is that in the decorate handler, when the footer is put on the
outgoing message, we first substitute some useful information into the uri's
placeholders.  The values should be obvious: $listname gets the fqdn_listname
value and $language gets the preferred_language.code.  So for mailing list
alpha at example.com using Italian as its preferred language, the footer_uri
gets transformed into mailman:///alpha@example.com/it/footer-generic.txt.

Now we start to look that up.  Of course, if the scheme were http: or https:,
we'd just issue a request to that url and use whatever we find.  The intent is
that in Postorius or some other CMS or web resource repository, you'd be able
to define a custom template appropriate for your site.  You'd set the list's
footer_uri to something like https://my.cms.example.com/footer.txt and since
there are no placeholders, Mailman just grabs the text at that url and viola!
you've got your footer.  Supporting the placeholders allows your CMS to
provide different footers for different lists, and of course you'll want to
provide different footers for different human languages.

But okay, now we have mailman:///alpha@example.com/it/footer-generic.txt and
we have to look that up.  What are the rules for mailman: urls?

mailman: urls are shorthand for internal resources, homed in the source code
directory on the file system.  The search order is well documented, but not
easily discovered so here's the documentation:

https://gitlab.com/mailman/mailman/blob/master/src/mailman/utilities/i18n.py#L53

You can see how there's a search hierarchy, such that if you only want a
single template for all your lists on the site, you can define it once on the
file system, and Mailman will just find that one.  Similarly, you could have a
template that applies to all lists within the same domain, or have list
specific templates.  So, bottom line is, drop a file in the template_dir
defined in your mailman.cfg and set your list's footer_uri to a mailman: url
that points here, and Bob's your uncle.

Now the second step alluded to earlier.  Once you've located the template, the
template *itself* can have substitution placeholders, and for message headers
and footers (i.e. message decorations) they get filled in here:

https://gitlab.com/mailman/mailman/blob/master/src/mailman/handlers/decorate.py#L228

So you can see how your template can contain information about the mailing
list's name, hostname, description, etc.  `extradict` comes into play (or at
least *should* <wink>) when messages are personalized, such that some
information specific to the user could be added, e.g. their unsubscribe link.
This may not be fully plumbed out right now though.

Briefly then, how will this be different in the future?  I'm still working out
the design, but roughly, there will be a new ITemplateManager that holds
mappings between template names, a context (e.g. mailing list, domain, or
site), URIs, and "resource dictionaries".  This ITemplateManager would be a
top-level REST resource so Postorius and other REST clients could directly
manipulate these mappings.

Then you'd be able to say, through REST, "set the footer template, for all
mailing lists on example.com, to https://my.cms.example.com/footer.txt`.  When
needed, the core delivery engine would then ask the template manager for the
contents of the footer template for a given mailing list, and it would get
back a bunch of text (appropriately cached, with various cache management
knobs for efficiency).  Mailman would then fill in substitution variables in
this footer template as before, but it would *also* do a query for the
"resource dictionary" which would be e.g. a JSON mapping keys to values.  This
would then let your CMS also define additional bits of data to shove into the
footer when it gets sent out.

Cheers,
-Barry

[*] and when you read "footer", think "just about any template eventually".