Editing Tips to write plugins

[[Category:Plugins]]
I've written a lot of plugins for EPrints 3+ now and so i think its time to share the knowledge. If you care you can read about the mess I got into in the early days [http://blogs.ecs.soton.ac.uk/oneshare/2009/09/25/taking-stock-and-mopping-up-the-mess-i-made-of-eprints/ here].

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. See [[Instructions for local plugins]]

* Rule 5: For everything you want to do which doesn't 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”

You can use this to overwrite behaviour from an existing subroutine.  Make sure to delete the original first:
 package EPrints::Plugin::MyPlugin;
 use strict;
 our @ISA = qw/ EPrints::Plugin /;
 package EPrints::DataObj::EPrint;
 BEGIN { delete $EPrints::DataObj::EPrint::{existing_subroutine}; }
 sub existing_subroutine{
  return(”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.