Contribute: Plugins/ExportPluginsHelloOld

Export Plugin Tutorial 1: Hello, World!

In this tutorial you will learn how to create a simple export plugin for EPrints, which will generate a list of titles from the results of a search. A basic knowledge of Perl is needed, but the code will be explained nearly line by line.

Before You Start

It is sensible to separate the plugins you create for EPrints from those included with it. Create a directory for your export plugins in the main plugin directory (usually /opt/eprints3/perl_lib/EPrints/Plugin/Export) for example /opt/eprints3/perl_lib/EPrints/Plugin/Export/MyPlugins.

HelloExport.pm

Replace MyPlugins with the name of the directory you have decided to put your export plugins in and place the code below in a file called HelloExport.pm in that directory.

package EPrints::Plugin::Export::MyPlugins::HelloExport;

@ISA = ("EPrints::Plugin::Export");

use strict;

sub new
{
        my ($class, %opts) = @_;

        my $self = $class->SUPER::new(%opts);

        $self->{name} = "Hello, World!";
        $self->{accept} = [ 'dataobj/eprint', 'list/eprint' ];
        $self->{visible} = "all";
        $self->{suffix} = ".txt";
        $self->{mimetype} = "text/plain; charset=utf-8";

        return $self;
}

sub output_dataobj
{
        my ($plugin, $dataobj) = @_;

        return $dataobj->get_value("title")."\n";
}

1;

Testing Your Plugin

Restart your web server and perform a search.

If all is well your plugin should appear in the dropdown menu. Select it and click export. As long as the search provided some results, you should get a list of EPrint titles returned.

In More Detail

Housekeeping

package EPrints::Plugin::Export::Foo::HelloExport;

Export plugins need to inherit from the EPrints::Plugin::Export class.

@ISA = ("EPrints::Plugin::Export");

Constructor

The Constructor for our Plugin. After the implicit class reference, a hash of options is given.

sub new
{
        my ($class, %opts) = @_;

We create a new export plugin by calling the Eprints::Plugin::Export constructor

        my $self = $class->SUPER::new(%opts);

Now we set a number of fields to register our new plugin.

This is the name that will appear in the export dropdown menu. The name should therefore be short and descriptive.

        $self->{name} = "Hello, World!";

The accept field is set to an array containing the type of objects this plugin can deal with. In this case lists of eprints and individual eprints.

        $self->{accept} = [ 'dataobj/eprint', 'list/eprint' ];

The visible field denoes the class of user which will be able to see the plugin. For most export plugins the value "all" will be required, allowing all users to see and use the plugin. A value of "staff" would make the plugin only visible to repository staff.

        $self->{visible} = "all";

The suffix field contains the extension of files exported by the plugin.

The mimetype field defines the MIME type of the files exported by the plugin You can also specify file encoding, for example "text/plain; charset=utf-8" to specify plain text, encoded using UTF-8. [[1]] is a Unicode character encoding capable of expressing a large number of different characters and so is usually preferable to [[2]]

        $self->{suffix} = ".txt";
        $self->{mimetype} = "text/plain; charset=utf-8";

We then return our plugin reference.

        return $self;
}

Processing DataObjs

This subroutine handles the export of each DataObj. Besides an implicit reference to the plugin object, this subroutine is also provided with a reference to an individual DataObj

sub output_dataobj
{
        my ($plugin, $dataobj) = @_;

        # Return a scalar containing the title.
        return $dataobj->get_value("title")."\n";
}

Standard Perl package requirement.

1;