[Mailman-Developers] Mailman 3 custom footer

[treal tv]

Hey Barry! I'm a few days late to respond to this, but I just wanted to 
let you know I found this immensely useful, and my footer looks just 
like how I want it to be :)

We are using Mailman 3 in production in a corporate environment. I'm 
willing to deal with the re-structuring of Mailman when 3.1 comes around :)

Thanks again Barry.

On 02/26/2016 07:24 PM, Barry Warsaw wrote:
> 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".
> _______________________________________________
> Mailman-Developers mailing list
> Mailman-Developers at python.org
> https://mail.python.org/mailman/listinfo/mailman-developers
> Mailman FAQ: http://wiki.list.org/x/AgA3
> Searchable Archives: http://www.mail-archive.com/mailman-developers%40python.org/
> Unsubscribe: https://mail.python.org/mailman/options/mailman-developers/trealtv%40yandex.com
>
> Security Policy: http://wiki.list.org/x/QIA9