Editing Instructions for local plugins

[[Category:Plugins]]
See also: [[Tips_to_write_plugins]]

To change the functionality of a core plugin within a specific archive, you can make a subclass of the original package.

'''NOTE:''' If you are on 3.2.0-3.2.3 there is a bug in plugin factory that may cause local customisation to plugins to bleed between archives. Ticket is here: [http://trac.eprints.org/eprints/ticket/3867 http://trac.eprints.org/eprints/ticket/3867]

Make a directory (in this example I'm subclassing a Screen plugin):
 ~/archives/ARCHIVEID/cfg/plugins/EPrints/Plugins/Screen

copy the original plugin to this location, with a new name:
 cp ~/perl_lib/EPrints/Plugin/Screen/Items.pm ~/archives/ARCHIVEID/cfg/plugins/EPrints/Plugins/Screen/MyItems.pm

From the file, remove any subs that you don't want to redefine, and rename the package according to the name of the new file (in this example, I'm only redefining the 'render' sub).
The file should look a bit like this:
 package EPrints::Plugin::Screen::MyItems;
 @ISA = ( 'EPrints::Plugin::Screen::Items' );
 
 use strict;
 
 sub render
 {
     my( $self ) = @_;
     my $session = $self->{session};
 ...
 ...
 } #end of sub render

Then, add the following lines to the ~/archives/ARCHIVEID/cfg/cfg.d/plugins.pl file:
 $c->{plugin_alias_map}->{"Screen::Items"} = "Screen::MyItems";
 $c->{plugin_alias_map}->{"Screen::MyItems"} = undef;
This makes calls to Screens::Items go via your new version - which has the locally defined sub (render in this case), and also makes sure that your new version doesn't appear alongside the original version.
I have found that running ~/bin/epadmin reload ARCHIVEID doesn't always pick these changes up - you might need to restart Apache to see what you've done!

=== Troubleshooting ===

Note that the above only works for plugins that are actually rendered by EPrints.   Superclass plugins (e.g. EPrints/Plugin/Screen/EPrint/MyUploadMethod.pm) are never actually rendered, but provide common functionality to all subclassed plugins (e.g. EPrints/Plugin/Screen/EPrint/UploadMethod/File.pm).  If you wish a local superclass plugin, you will need to make sure your @ISA arrays are referring to the new classes.