The mailing list for listmasters using Sympa

[Steve Shipway <address@concealed>]

Here are a few notes I’ve put together regarding the process of porting plugins designed for Sympa 6.1.x to the new 6.2.x framework.  I’m recording them here in the hope that it will save someone else a few hours work – and maybe these can be formalised into a documentation page somewhere?

 

TT2 Plugins

 

The TT2 plugins, held under share/sympa/lib/Sympa/Template/Plugin, have not changed much.  The main difference is that they now need to be defined as subclasses of Sympa::Template::Plugin; thus have a minimal framework of:

 

package Sympa::Template::Plugin::EXAMPLE; # Set up the new plugin EXAMPLE

use base 'Template::Plugin';

use strict;

our $VERSION   = 0.01;

sub new {

    my ($class, $context, @args) = @_;;

return bless { }, $class;

}

1; # NEVER forget this line!

 

Of course, this is a boring plugin that does nothing, but you can add new data, functions and filters if you wish.

 

Any errors in a TT2 plugin are difficult to detect.    Remember that you need to restart Sympa for changes to be picked up, and check the Sympa logs for Sympa::Message::personalize when a message passes through the system.  The exact error text is lost by Sympa::Message::personalize_text ; you can retrieve it by making this change in the function:

 

my $rv = $template->parse($data, \$body, \$message_output,   is_not_template => 1);

unless ($rv) {

    $log->syslog('err', 'merge: TT2 error merging message: %s',$template->{last_error});

return undef;

}

 

You should also be aware that personalisation (merging) is done per-MIME-part.  So, a multipart message with text and HTML that has an error in the HTML part will still merge the text part, but will leave the HTML part unaltered.  Failed merges will only leave the MIME part unchanged, not the entire message.  This can cause confusion when a ‘helpful’ mail composer (eg: Outlook) inserts some unwanted HTML into the middle of TT2 code, but only in the HTML portion of the message.  It may well be easier to test new TT2 merge plugins by submitting minimal test messages via the wbe interface instead.

 

It would be useful if Sympa had a merge test mode, where failures sent the full error log back to the original sender...

 

Custom scenario conditions

 

These seem to be compatible between versions; however if your condition uses database access, see below.  Remember that changing one of these requires you to restart both Sympa and Apache (if you use FCGI)

 

Database Access

 

Any database access in TT2 plugins, Custom Actions, or Custom Conditions, will need to be changed.  The db_get_handler() function has gone, and been replaced by the Sympa::DatabaseManager class.  Strangely, you can get a warning when loading this class, which can break TT2 and Custom Action plugins, so use an eval:

 

eval { require Sympa::DatabaseManager; };

 

You can now obtain statement handles, which are optimised by the class.

 

                my( $sdm ) = Sympa::DatabaseManager->instance();

                if( ! $sdm ) {

           # handle error here

           return;

     }

                my( $sth ) = $sdm->do_prepared_query($sql,@paramlist);

 

The $sth is a DBI statement handle that has executed, and so can be tested for $sth->rows, $sth->errstr, and of course $sth->fetchrow_arrayref and similar.

 

There are other calls that can be made to the Sympa::DatabaseManager object, but these are the main ones.

 

Custom Actions

 

This is the biggest change in 6.2 plugins.  Where before you only needed to have a web_tt2/myaction.tt2 file for lca/myaction/list and ca/myaction to be valid, now you are also required to have a custom_actions/myaction.pm file.  In the following lines, replace ‘myaction’ with whatever your new custom action is, and replace ‘lca’ with ‘ca’ for a non-list custom action.

 

In Sympa 6.1, you would use a TT2 template to make function calls if you wanted to do anything external.  Now, the code needs to be located in a separate module under custom_actions, and is run before calling the TT2.  While it should be possible to migrate TT2 plugins from 6.1 and operate that way, it is better to do things the Right Way and use a custom_action module.  This can result in big changes to make to the myaction.tt2 file.

 

The myaction.pm for a lca/myaction must contain at least:

 

package myaction_plugin;

use strict;

our $VERSION   = 0.01;

sub process {

        my( $listref ) = shift; # reference to list object if lca (omit this line for ca)

        my( @params ) = @_; # other parameters

        return 'home' if(!ref $listref); # return if this LCA is being called as a CA (reverse the test is this is a ca)

       return 1; # show myaction.tt2

}

1; # NEVER forget this line!

 

The return value of the process() function can be another action (eg: ‘home’ to go to the home page), or a custom action (eg: ‘lca:otheraction’), or 1 (to go to its own my myaction.tt2), or a hash reference.  If you return a hashref, then this is placed directly into the TT2 stash before calling the myaction.tt2.   You can also set the key ‘next_action’ in the stash  to change the destination I nthe same way as if you returned a scalar.

 

When the custom action is called as /sympa/lca/myaction/listname/a/b/c then process() is called with a reference to a  Sympa::List object, and three more parameters, ‘a’, ‘b’ and ‘c’.  Nothing else is passed.  Note that any query data (via GET or POST) can override these by using variable names ‘list’ and ‘cap’.

 

The custom tt2 file will have all the normal stash, plus action == ‘lca’, custom_action == ‘myaction’, cap == [ ‘a’,’b’,’c’ ], and any extra stash objects you return from process().

 

Note that nav.tt2 is called before any custom tt2 files (but after calling process()) and you need to make changes here if you want to have a navigation menu added.

 

If you end up with nothing but your list name and subject on the page, then the call to process() failed.  This sets action to “” and does not load any tt2 file after nav.tt2.  You can track down potential problems in your custom action like this:

 

First, run perl directly on the action file with –w and –I share/sympa/lib  

        perl –w –I share/sympa/lib myaction.pm

You need to specify the correct path to your Sympa.pm in the –I flag of course.  If you can run perl like this, make sure it does not report any warnings or errors.

Check the sympa.log for any lines mentioning ‘do_lca’ and  ‘myaction’.  These should hopefully give you any runtime error messages.

 

End

 

Hopefully, people will find this of use.  I’ve migrated a couple of plugins so far, and the biggest problem was a lack of relevant logs.

 

Steve

 

 

Steve Shipway

Unix Design Team Lead

The University of Auckland

T: +64 9 3737 599 ext 86487

E: address@concealed

(GNU Terry Pratchett)

 

Attachment: smime.p7s
Description: S/MIME cryptographic signature