Taking stock and mopping up the mess I made of EPrints

So on our Language Box and other deriviative systems we thought it might be appropriate to upgrade the comments plugin (sneep) and install the meprints profile system. This meant we could go forward in a nice future proof kind of a way. In order to do this we needed to have an enoumous stock check. We still run on EPrints 3.1.0 because its part of our svn tree. What I needed to do was disentagle the work we had done from the EPrints 3.1.0 code.

The main cause of this problem was that I had no understanding of EPrints and only a basic grasp of perl when we started writing Language Box. The Faroes project which I was paid on was also massively behind schedule. This resulted in me having to learn EPrints as I went along and hack up something that worked fast with minimal fuss. Lanauge Box became fairly successful and institutions wanted their own installations of it. This meant the code had to be made portable. However their was no time to clear up the mess I had made which basically meant I did the bear minimum to make the thing deployable and then essentially copy pasted 3 times to make our respective deployments. All those deployments are now up and running so there is time to step back take a breath and make a genuinely portable system of robust plugins which can survive an EPrints upgrade process.

So without further ado let me give you the top 10 ways to avoid making a hash of your EPrints install when doing a large customization:

Rule 1: NEVER edit Session.pm if there is one file that you will absolutely not recover from it’s this. also there is an easy way to avoid editing it see rule 6.

Rule 2: Don’t edit anything in perl_lib/EPrints. Make copies with a new name and new package. That way these files wont be over written when you upgrade.

Rule 3: Everything in the Plugin/ directory which you do should be kept in the appropiate place in archives/YOUR_REPOSITORY/cfg/plugins/EPrints/Plugin etc. This is a really good way to keep track of what you’ve actually done.

Rule 4: Everything you do should be a plugin. EPrints has plugins for almost everything which means you should be able to do almost all funtionality in plugins.

Rule 5: For everything you want to do which doesnt seem to be a plugin think really hard. Are you SURE it’s not a plugin? Really SURE? Are you SURE you need this functionality? Really SURE?

Rule 6: If you have followed rule 5 and you are still really sure then kludge a plugin, a kuldgin as I like to call them, using namespace over writing. This is feature/artifact of perl, from one package you can write in another package. Add methods to the DataObj::EPrint good example of where you might want to do this. To do it :

make a Plugin (yes  a plugin) in your local cfg (see rule 3). start the plugin file in the normal way:

package EPrints::Plugin::MyPlugin;

use strict;

our @ISA = qw/ EPrints::Plugin /;

#now for the clever bit

package EPrints::DataObj::EPrint;

sub mysubroutine{

return(“foo”);

}

That has added mysubroutine to DataObj::EPrint so you can now

my $eprint = EPrint::DataObj::EPrint->new($session, 23); #get eprint 23

print $eprint->mysubroutine(); #prints “foo”

Rule 7: learn about cfg/cfg.d/plugins.pl. This file lets you disable plugins you dont want to use or map you modified plugins over other plugins. For example use MyReview.pm everywhere you would usually use Review.pm – very powerful. It also lets you define where plugins apear around about the place.

Rule 8: for plugins which use a cgi script for whatever reason (usually ajax) make a directory in cgi which has the same name as the plugin for example cgi/myfirstplugin where all the cgi used by MyFirstPlugin.pm can be found. It makes it much easier to see what youve done and if you want to deploy the plugin somewhere else you grab the plugin file and the directory and you well on the way.

Rule 9: Give each plugin its own phrase file. I got into a hidious mess where my zz_local.xml phrase file was about a 4000 lines long and it wasnt clear what phrases belonged to what plugin.

Rule 10: If your plugin needs configuring put all the config options in a cfg/cfg.d/my_plugins_config_options.pl that way the user only has to go to one place edit the options and different repositories using the same plugin can have different options.

In conclusion obey rules 1-10. If I’d known this stuff when I’d started we probably wouldnt have needed the first 6 months of the OneShare project.